Updated Branches: refs/heads/master 04836b61e -> e977ac090
[KARAF-2511] Add transaction/jta page in the user guide Project: http://git-wip-us.apache.org/repos/asf/karaf/repo Commit: http://git-wip-us.apache.org/repos/asf/karaf/commit/e977ac09 Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/e977ac09 Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/e977ac09 Branch: refs/heads/master Commit: e977ac090e501cd89d28c147818624e3ea90be23 Parents: 04836b6 Author: Jean-Baptiste Onofré <[email protected]> Authored: Thu Dec 19 17:51:26 2013 +0100 Committer: Jean-Baptiste Onofré <[email protected]> Committed: Thu Dec 19 17:51:26 2013 +0100 ---------------------------------------------------------------------- manual/src/main/webapp/_navigation.conf | 2 +- manual/src/main/webapp/manual.conf | 1 + manual/src/main/webapp/users-guide/index.conf | 2 +- manual/src/main/webapp/users-guide/jta.conf | 105 +++++++++++++++++++++ 4 files changed, 108 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/karaf/blob/e977ac09/manual/src/main/webapp/_navigation.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/_navigation.conf b/manual/src/main/webapp/_navigation.conf index ae3169f..feecd5d 100644 --- a/manual/src/main/webapp/_navigation.conf +++ b/manual/src/main/webapp/_navigation.conf @@ -23,7 +23,7 @@ h3. [Users Guide|/users-guide/index] - [Enterprise|/users-guide/enterprise] -- [WebContainer (JSP/Servlet)|/users-guide/webcontainer] -- [Naming (JNDI)|/users-guide/jndi] --- Transaction (JTA) +-- [Transaction (JTA)|/users-guide/jta] -- [DataSource (JDBC)|/users-guide/jdbc] -- [MOM (JMS)|/users-guide/jms] -- Persistence (JPA) http://git-wip-us.apache.org/repos/asf/karaf/blob/e977ac09/manual/src/main/webapp/manual.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/manual.conf b/manual/src/main/webapp/manual.conf index 2564804..0aef238 100644 --- a/manual/src/main/webapp/manual.conf +++ b/manual/src/main/webapp/manual.conf @@ -52,6 +52,7 @@ h1. Users Guide {include:users-guide/enterprise} {include:users-guide/webcontainer} {include:users-guide/jndi} +{include:users-guide/jta} {include:users-guide/jdbc} {include:users-guide/jms} {include:users-guide/failover} http://git-wip-us.apache.org/repos/asf/karaf/blob/e977ac09/manual/src/main/webapp/users-guide/index.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/users-guide/index.conf b/manual/src/main/webapp/users-guide/index.conf index f24f9a9..b318be6 100644 --- a/manual/src/main/webapp/users-guide/index.conf +++ b/manual/src/main/webapp/users-guide/index.conf @@ -18,7 +18,7 @@ h1. Users Guide * [Enterprise|enterprise] ** [WebContainer (JSP/Servlet)|webcontainer] ** [Naming (JNDI)|jndi] -** Transaction (JTA) +** [Transaction (JTA)|jta] ** [DataSource (JDBC)|jdbc] ** [MOM (JMS)|jms] ** Persistence (JPA) http://git-wip-us.apache.org/repos/asf/karaf/blob/e977ac09/manual/src/main/webapp/users-guide/jta.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/users-guide/jta.conf b/manual/src/main/webapp/users-guide/jta.conf new file mode 100644 index 0000000..718068a --- /dev/null +++ b/manual/src/main/webapp/users-guide/jta.conf @@ -0,0 +1,105 @@ +h1. 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: + +{code} +karaf@root()> feature:install transaction +{code} + +However, the {{transaction}} feature is installed (as a transitive dependency) when installing enterprise features +(like {{jdbc}} or {{jms}} features for instance). + +h2. 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. + +h2. Configuration + +The installation of the {{transaction}} feature installs a new configuration: {{org.apache.aries.transaction}}. + +You can see the configuration properties using: + +{code} +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.0.1 +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-3.0.0/data/txlog + aries.transaction.howl.bufferSizeKBytes = 4 +{code} + +* {{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: + +{code} +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.0.1 +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-3.0.0/data/txlog + aries.transaction.howl.bufferSizeKBytes = 4 +{code} + +{warning} +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: + +{code} +# 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-3.0.0/data/txlog +aries.transaction.howl.bufferSizeKBytes = 4 +{code} +{warning} \ No newline at end of file
