| // |
| // 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 |
| ---- |
| ==== |