Author: timothyjward
Date: Thu Apr 28 14:15:44 2016
New Revision: 1741429
URL: http://svn.apache.org/viewvc?rev=1741429&view=rev
Log:
Add descriptions for the Local and XA Transaction Control service
implementations
Added:
aries/site/trunk/content/modules/tx-control/localTransactions.mdtext
(with props)
aries/site/trunk/content/modules/tx-control/xaTransactions.mdtext (with
props)
Modified:
aries/site/trunk/content/modules/tx-control/index.mdtext
Modified: aries/site/trunk/content/modules/tx-control/index.mdtext
URL:
http://svn.apache.org/viewvc/aries/site/trunk/content/modules/tx-control/index.mdtext?rev=1741429&r1=1741428&r2=1741429&view=diff
==============================================================================
--- aries/site/trunk/content/modules/tx-control/index.mdtext (original)
+++ aries/site/trunk/content/modules/tx-control/index.mdtext Thu Apr 28
14:15:44 2016
@@ -1,4 +1,4 @@
-Title:
+Title: The Aries Transaction Control Service
Notice: Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
@@ -23,8 +23,8 @@ first.
###The Aries Transaction Control implementations
-* TODO Local Transactions
-* TODO XA Transactions and Last Participant support
+* [The Local Transaction Control Service][2]
+* [The XA Transaction Control Service and Last Participant support][3]
###Configuring JDBC access
@@ -38,10 +38,12 @@ first.
###Advanced topics
-* [Custom Resource Providers][2]
-* [Advanced Scope control][3]
+* [Custom Resource Providers][4]
+* [Advanced Scope control][5]
[1]: quickstart.html
- [2]: advancedResourceProviders.html
- [3]: advancedScopes.html
\ No newline at end of file
+ [2]: localTransactions.html
+ [3]: xaTransactions
+ [4]: advancedResourceProviders.html
+ [5]: advancedScopes.html
\ No newline at end of file
Added: aries/site/trunk/content/modules/tx-control/localTransactions.mdtext
URL:
http://svn.apache.org/viewvc/aries/site/trunk/content/modules/tx-control/localTransactions.mdtext?rev=1741429&view=auto
==============================================================================
--- aries/site/trunk/content/modules/tx-control/localTransactions.mdtext (added)
+++ aries/site/trunk/content/modules/tx-control/localTransactions.mdtext Thu
Apr 28 14:15:44 2016
@@ -0,0 +1,61 @@
+Title: Aries Local Transaction Control implementation
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+#Aries Local Transaction Control implementation
+
+The Aries Local Transaction control implementation is available at the
following maven coordinates:
+
+ <dependency>
+ <groupId>org.apache.aries.tx-control</groupId>
+ <artifactId>tx-control-service-local</artifactId>
+ <version>${aries.tx.control.version}</version>
+ </dependency>
+
+## Using the Transaction Control Service
+
+For the basics of using the Transaction Control Service see the [Quick Start
Documentation][1]
+
+As per the Transaction Control specification the Aries Local implementation
registers a
+TransactionControl service in the OSGi Service Registry with the
<code>osgi.local.enabled</code>
+property set to <code>true</code>
+
+## Local Transactions
+
+Local transactions occur purely in-memory, and do not coordinate between
resources.
+
+This means that Local Transactions are _not recoverable_ in the event of
failure, and also
+that Local Transactions are _not_ atomic across multiple resources. In
particular, if two
+resources are accessed in a transaction (for example two different databases
are modified)
+then it is possible that one resource will be committed and the other rolled
back.
+
+Local transactions are therefore best suited to scenarios where only a single
resource is
+accessed within the transaction, or where consistency between resources is not
important.
+
+## Working with local transactions
+
+The Local Transaction Control Service supports participants in ongoing
transactions via the
+<code>registerLocalResource(LocalResource)</code> method. It does not support
XA resources
+and will throw an <code>IllegalStateException</code> if
<code>registerXAResource(XAResource)</code>
+is called.
+
+Lifecycle callbacks can be registered against the current scope using the
+<code>preCompletion(Runnable)</code> and
<code>postCompletion(Consumer<TransactionStatus>)</code>
+methods.
+
+
+ [1]: quickstart.html
\ No newline at end of file
Propchange: aries/site/trunk/content/modules/tx-control/localTransactions.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: aries/site/trunk/content/modules/tx-control/xaTransactions.mdtext
URL:
http://svn.apache.org/viewvc/aries/site/trunk/content/modules/tx-control/xaTransactions.mdtext?rev=1741429&view=auto
==============================================================================
--- aries/site/trunk/content/modules/tx-control/xaTransactions.mdtext (added)
+++ aries/site/trunk/content/modules/tx-control/xaTransactions.mdtext Thu Apr
28 14:15:44 2016
@@ -0,0 +1,87 @@
+Title: Aries XA Transaction Control implementation
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+#Aries XA Transaction Control implementation
+
+The Aries XA Transaction control implementation is available at the following
maven coordinates:
+
+ <dependency>
+ <groupId>org.apache.aries.tx-control</groupId>
+ <artifactId>tx-control-service-xa</artifactId>
+ <version>${aries.tx.control.version}</version>
+ </dependency>
+
+It is based on the JTA transaction manager provided by Apache Geronimo.
+
+## Using the Transaction Control Service
+
+For the basics of using the Transaction Control Service see the [Quick Start
Documentation][1]
+
+As per the Transaction Control specification the Aries XA implementation
registers a
+TransactionControl service in the OSGi Service Registry.
+
+The Aries XA Transaction Control implementation is able to support the use of
both XA
+and Local Resources within the same transaction. The service is therefore
registered
+with the <code>osgi.local.enabled</code> _and_ <code>osgi.xa.enabled</code>
+properties set to <code>true</code>.
+
+## XA Transactions
+
+The XA transactions created by the XA Transaction Control implementation are
not configured
+to create a transaction log. Therefore the XA Transactions are _not
recoverable_ in the event of failure.
+This may change in the future if transaction log support is added to the
implementation.
+
+The primary difference between XA and Local Transactions is that XA
transactions _are_ atomic across multiple resources. In particular, if two
+resources. This means that all resources in the transaction will be committed
or rolled back together.
+
+
+XA transactions are therefore best suited to scenarios where multiple
resources are
+accessed within the transaction, particularly if consistency between the
resources is important.
+
+## Working with XA transactions
+
+The XA Transaction Control Service supports participants in ongoing
transactions via the
+<code>registerXAResource(XAResource)</code> method.
+
+Lifecycle callbacks can be registered against the current scope using the
+<code>preCompletion(Runnable)</code> and
<code>postCompletion(Consumer<TransactionStatus>)</code>
+methods.
+
+##Local Resources and the Last Participant Gambit
+
+In addition to supporting XA resources the XA Aries Transaction Control
implementation also supports
+Local Resources which can be added using the
<code>registerLocalResource(LocalResource)</code>
+method.
+
+When local resources are added to the XA transaction they are processed in a
special way. When
+the two-phase commit is preparing resources it first prepares all of the
registered <code>XAResources</code>,
+then the Local resources are committed or rolled back as appropriate, then the
XAResources are completed.
+This is known as the _Last Resource Gambit_.
+
+The value of the Last Resource Gambit is highest when there is exactly one
Local resource in the transaction.
+In this case the Local resource is effectively doing a prepare and
commit/rollback in one step, but as all of the
+other resources have been prepared already there is *almost* no risk of
inconsistency across the resources.
+As the number of Local Resources involved in the transaction rises the risk of
inconsistency becomes much
+greater. It is therefore recommended that XA transactions contain _zero_ or
_one_ Local resources, although
+any number may be registered.
+
+
+
+
+
+ [1]: quickstart.html#TODO
\ No newline at end of file
Propchange: aries/site/trunk/content/modules/tx-control/xaTransactions.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
