//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

==== Transaction (JTA)

Apache Karaf provides container managed transactions, available as OSGi services.

As most of the enterprise features, it's an optional feature that you can install with:

----
karaf@root()> feature:install transaction
----

However, the `transaction` feature is installed (as a transitive dependency) when installing enterprise features
(like `jdbc` or `jms` features for instance).

===== Apache Aries Transaction and ObjectWeb HOWL

The `transaction` feature uses Apache Aries and ObjectWeb HOWL. Aapache Aries Transaction "exposes" the transaction
manager as OSGi service. The actual implementation of the transaction manager is ObjectWeb HOWL.

ObjectWeb HOWL is a logger implementation providing features required by the ObjectWeb JOTM project, with a public API
that is generally usable by any Transaction Manager.
ObjectWeb HOWL uses unformatted binary logs to maximize performance and specifies a journalization API with methods
necessary to support JOTM recovery operations.

ObjectWeb HOWL is intended to be used for logging of temporary data such as XA transaction events.
It is not a replacement for traditional log kits such as LOG4J and Java SE Logging.

In Apache Karaf, ObjectWeb HOWL (High-speed ObjectWeb Logger) is used to implement TransactionLog (in Aries Transaction),
providing a very performant transaction manager in an OSGi way.

===== Configuration

The installation of the `transaction` feature installs a new configuration: `org.apache.aries.transaction`.

You can see the configuration properties using:

----
karaf@root()> config:list "(service.pid=org.apache.aries.transaction)"
----------------------------------------------------------------
Pid:            org.apache.aries.transaction
BundleLocation: mvn:org.apache.aries.transaction/org.apache.aries.transaction.manager/1.1.0
Properties:
   aries.transaction.recoverable = true
   aries.transaction.timeout = 600
   service.pid = org.apache.aries.transaction
   org.apache.karaf.features.configKey = org.apache.aries.transaction
   aries.transaction.howl.maxBlocksPerFile = 512
   aries.transaction.howl.maxLogFiles = 2
   aries.transaction.howl.logFileDir = /opt/apache-karaf-4.0.0/data/txlog
   aries.transaction.howl.bufferSizeKBytes = 4
----

* `aries.transaction.recoverable` property is a flag to enable support of recoverable resource or not. A recoverable
 resource is a transactional object whose state is saved to stable storage if the transaction is committed, and whose
 state can be reset to what it was at the beginning of the transaction if the transaction is rolled back.
 At commit time, the transaction manager uses the two-phase XA protocol when communicating with the recoverable resource
 to ensure transactional integrity when more than one recoverable resource is involved in the transaction being committed.
 Transactional databases and message brokers like Apache ActiveMQ are examples of recoverable resources.
 A recoverable resource is represented using the javax.transaction.xa.XAResource interface in JTA.
 Default is `true`.
* `aries.transaction.timeout` property is the transaction timeout. If a transaction has a lifetime longer than this timeout
 a transaction exception is raised and the transaction is rollbacked. Default is `600` (10 minutes).
* `aries.transaction.howl.logFileDir` property is the directory where the transaction logs (journal) are stored.
 Default is `KARAF_DATA/txlog`.
* `aries.transaction.howl.maxLogFiles` property is the maximum number of transaction log files to retain. Combined with the
 `aries.transaction.howl.maxBlocksPerFile`, it defines the transaction retention.

You can change the configuration directly using the `config:*` commands, or the Config MBean.

For instance, to increase the transaction timeout, you can do:

----
karaf@root()> config:edit org.apache.aries.transaction
karaf@root()> config:property-set aries.transaction.timeout 1200
karaf@root()> config:update
karaf@root()> config:list "(service.pid=org.apache.aries.transaction)"
----------------------------------------------------------------
Pid:            org.apache.aries.transaction
BundleLocation: mvn:org.apache.aries.transaction/org.apache.aries.transaction.manager/1.1.0
Properties:
   aries.transaction.recoverable = true
   aries.transaction.timeout = 1200
   service.pid = org.apache.aries.transaction
   org.apache.karaf.features.configKey = org.apache.aries.transaction
   aries.transaction.howl.maxBlocksPerFile = 512
   aries.transaction.howl.maxLogFiles = 2
   aries.transaction.howl.logFileDir = /opt/apache-karaf-4.0.0/data/txlog
   aries.transaction.howl.bufferSizeKBytes = 4
----

[NOTE]
====
The `transaction` feature defines the configuration in memory by default. It means that changes that you can do will
be lost in case of Apache Karaf restart.
If you want to define your own transaction configuration at startup, you have to create a `etc/org.apache.aries.transaction.cfg`
configuration file and set the properties and values in the file. For instance:

----
# etc/org.apache.aries.transaction.cfg
aries.transaction.recoverable = true
aries.transaction.timeout = 1200
aries.transaction.howl.maxBlocksPerFile = 512
aries.transaction.howl.maxLogFiles = 2
aries.transaction.howl.logFileDir = /opt/apache-karaf-4.0.0/data/txlog
aries.transaction.howl.bufferSizeKBytes = 4
----
====