Author: timothyjward
Date: Thu Apr 28 18:35:43 2016
New Revision: 1741488
URL: http://svn.apache.org/viewvc?rev=1741488&view=rev
Log:
Add coordinator and last resource gambit documentation
Added:
aries/site/trunk/content/modules/tx-control/coordinator.mdtext (with
props)
aries/site/trunk/content/modules/tx-control/lastResourceGambit.mdtext
(with props)
Modified:
aries/site/trunk/content/modules/tx-control/index.mdtext
aries/site/trunk/content/modules/tx-control/localJDBC.mdtext
aries/site/trunk/content/modules/tx-control/xaJDBC.mdtext
Added: aries/site/trunk/content/modules/tx-control/coordinator.mdtext
URL:
http://svn.apache.org/viewvc/aries/site/trunk/content/modules/tx-control/coordinator.mdtext?rev=1741488&view=auto
==============================================================================
--- aries/site/trunk/content/modules/tx-control/coordinator.mdtext (added)
+++ aries/site/trunk/content/modules/tx-control/coordinator.mdtext Thu Apr 28
18:35:43 2016
@@ -0,0 +1,116 @@
+Title: Using the Coordinator to optimise Transactions
+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.
+
+#Using the Coordinator to optimise Transactions
+
+The transaction control service provides a transactional scope around resource
access, but sometimes it
+makes sense to delay doing this work until it can be batched efficiently
together in a single transaction:
+
+##Bulk resource access
+
+In this case we simply do each insert in a separate transaction:
+
+ public void persistMessage(String message) {
+ txControl.required(() -> {
+ PreparedStatement ps = connection.prepareStatement(
+ "Insert into TEST_TABLE values ( ? )");
+ ps.setString(1, message);
+ return ps.executeUpdate();
+ });
+ }
+
+If called a large number of times from an external service:
+
+ List<String> messages = getMessages();
+
+ messages.stream()
+ .forEach(svc::persistMessage);
+
+Then this code can be quite slow as the message list becomes large
+
+## The naive approach
+
+The obvious way to reduce overhead is to batch all of the inserts into a
single transaction:
+
+ List<String> messages = getMessages();
+
+ txControl.required(() -> {
+ messages.stream()
+ .forEach(svc::persistMessage);
+ return null;
+ });
+
+This reuses the same physical connection each time, and it avoids repeated
commits, so it should be faster
+right?
+
+Actually it turns out that this approach can be slower for some databases. By
building up a very large
+transaction it can actually slow down the rate at which data can be insterted.
+
+## Using the coordinator
+
+By adding in the Coordinator we can **dramatically** improve our performance:
+
+ public void persistMessage(String message) {
+ if(coordinator.addParticipant(this)) {
+ ((List<String>)coordinator.peek().getVariables()
+ .computeIfAbsent(getClass(), k -> new ArrayList<String>()))
+ .add(message);
+ } else {
+ txControl.required(() -> {
+ PreparedStatement ps = connection.prepareStatement(
+ "Insert into TEST_TABLE values ( ? )");
+ ps.setString(1, message);
+ return ps.executeUpdate();
+ });
+ }
+ }
+
+ @Override
+ public void ended(Coordination coord) throws Exception {
+ txControl.required(() -> {
+ List<String> l = (List<String>) coord.getVariables()
+ .get(getClass());
+
+ PreparedStatement ps = connection.prepareStatement(
+ "Insert into TEST_TABLE values ( ? )");
+
+ l.stream().forEach(s -> {
+ try {
+ ps.setString(1, s);
+ ps.addBatch();
+ } catch (SQLException sqle) {
+ throw new RuntimeException(sqle);
+ }
+ });
+
+ return ps.executeBatch();
+ });
+ }
+
+Now, if we do our bulk add inside a coordination:
+
+ coordinator.begin("foo", MINUTES.toMillis(5));
+ try {
+ messages.stream()
+ .forEach(this::persistMessage);
+ } finally {
+ coordinator.peek().end();
+ }
+
+Then we find that it is **much** faster! This is because we can make use of
more efficient JDBC API, and
+because we can batch up a suitable number of inserts in a single transaction.
\ No newline at end of file
Propchange: aries/site/trunk/content/modules/tx-control/coordinator.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
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=1741488&r1=1741487&r2=1741488&view=diff
==============================================================================
--- aries/site/trunk/content/modules/tx-control/index.mdtext (original)
+++ aries/site/trunk/content/modules/tx-control/index.mdtext Thu Apr 28
18:35:43 2016
@@ -51,8 +51,10 @@ These modules provide portable JPA resou
###Advanced topics
-* [Custom Resource Providers][8]
-* [Advanced Scope control][9]
+* [Using the Coordinator to optimise Transactions][8]
+* [Making use of the Last Resource Gambit][9]
+* [Custom Resource Providers][10]
+* [Advanced Scope control][11]
[1]: quickstart.html
@@ -62,5 +64,7 @@ These modules provide portable JPA resou
[5]: xaJDBC.html
[6]: localJPA.html
[7]: xaJPA.html
- [8]: advancedResourceProviders.html
- [9]: advancedScopes.html
\ No newline at end of file
+ [8]: coordinator.html
+ [9]: lastResourceGambit.html
+ [10]: advancedResourceProviders.html
+ [11]: advancedScopes.html
\ No newline at end of file
Added: aries/site/trunk/content/modules/tx-control/lastResourceGambit.mdtext
URL:
http://svn.apache.org/viewvc/aries/site/trunk/content/modules/tx-control/lastResourceGambit.mdtext?rev=1741488&view=auto
==============================================================================
--- aries/site/trunk/content/modules/tx-control/lastResourceGambit.mdtext
(added)
+++ aries/site/trunk/content/modules/tx-control/lastResourceGambit.mdtext Thu
Apr 28 18:35:43 2016
@@ -0,0 +1,75 @@
+Title: Using the Last Resource Gambit
+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.
+
+#Using the Last Resource Gambit
+
+The Last Resource Gambit is a technique by which a non-XA capable resource may
be (relatively) safely
+included in a two-phase commit transaction containing multiple resources.
+
+Importantly:
+
+* The transaction must be 2-phase (typically XA)
+* All but one of the resources must be XA capable
+* The Transaction Manager must support the Last Resource Gambit
+
+##How does it work?
+
+In a two phase commit/rollback the Transaction Manager prepares all of the
resources before calling commit.
+This means that the resources have the opportunity to do any constraint
checking and buffer flushing before
+committing, so that they know that a commit will succeed. If any of the
prepare calls fail then all of the
+resources (including the ones that were already prepared) may be rolled back
to ensure consistency.
+
+If a "local" (i.e. one phase) resource is included in the transaction then
this model breaks. It
+is not possible to prepare a one-phase resource, so typically a transaction
manager must "commit and hope"
+expecting that all other resources will commit successfully.
+
+In the case of the Last Resource Gambit this possiblity can be reduced to near
zero by including the local
+resource as the "last resource". Specifically all of the XA resources are
prepared, and if the prepare succeeds
+then the local resource is committed. If the commit succeeds then all of the
XA resources are committed,
+otherwise the XA resources are rolled back. This model means that the overall
transaction is robust to
+resource failures.
+
+##Taking advantage of the Last Resource Gambit
+
+The [Aries XA Transaction Control service][1] implements the last resource
gambit automatically, so there is
+nothing that needs to be explicitly done by the client to enable the
behaviour, other than to use a local
+resource alongside XA resources.
+
+For example, if one database in use is HSQLDB, which does not support XA, but
two others use H2,
+which does support XA, then the following configurations would be used:
+
+_org.apache.aries.tx.control.jdbc.xa_
+
+ osgi.jdbc.driver.class=org.h2.Driver
+ url=jdbc:h2:tcp://192.168.1.31:12345/path/to/db
+
+_org.apache.aries.tx.control.jdbc.xa_
+
+ osgi.jdbc.driver.class=org.h2.Driver
+ url=jdbc:h2:tcp://192.168.1.63:23456/path/to/another/db
+
+_org.apache.aries.tx.control.jpa.local_
+
+ osgi.jdbc.driver.class=org.hsqldb.jdbc.JDBCDriver
+ url=jdbc:hsqldb:hsql://192.168.1.127/xdb"
+ osgi.unit.name=jpa-workspace
+
+If these three resource providers are used in the same transaction then the
Last Resource Gambit will
+ensure that the one-phase resource is committed reliably.
+
+ [1]: xaTransactions.html
\ No newline at end of file
Propchange:
aries/site/trunk/content/modules/tx-control/lastResourceGambit.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Modified: aries/site/trunk/content/modules/tx-control/localJDBC.mdtext
URL:
http://svn.apache.org/viewvc/aries/site/trunk/content/modules/tx-control/localJDBC.mdtext?rev=1741488&r1=1741487&r2=1741488&view=diff
==============================================================================
--- aries/site/trunk/content/modules/tx-control/localJDBC.mdtext (original)
+++ aries/site/trunk/content/modules/tx-control/localJDBC.mdtext Thu Apr 28
18:35:43 2016
@@ -27,7 +27,8 @@ The Aries Local JDBC provider implementa
</dependency>
This module is a prototype implementation of the OSGi Transaction Control JDBC
resource provider.
-It supports Local transactions only.
+It supports Local transactions only. The provider also has built-in support
for Database connection
+pooling using Hikari CP.
## When should I use this module?
@@ -60,6 +61,9 @@ ResourceProvider if more than one is pre
This Resource Provider is used in conjunction with a TransactionControl
service to provide scoped
access to a JDBC connection with support for Local Transactions.
+When using local transactions the JDBC API is used to commit or rollback the
Database connection.
+There is no need for client code to call commit, rollback, or close on the
connection.
+
## Creating a resource programmatically
Preparing a resource for use is very simple. Create a
<code>JDBCConnectionProvider</code> using the
Modified: aries/site/trunk/content/modules/tx-control/xaJDBC.mdtext
URL:
http://svn.apache.org/viewvc/aries/site/trunk/content/modules/tx-control/xaJDBC.mdtext?rev=1741488&r1=1741487&r2=1741488&view=diff
==============================================================================
--- aries/site/trunk/content/modules/tx-control/xaJDBC.mdtext (original)
+++ aries/site/trunk/content/modules/tx-control/xaJDBC.mdtext Thu Apr 28
18:35:43 2016
@@ -27,7 +27,8 @@ The Aries Local JDBC provider implementa
</dependency>
This module is a prototype implementation of the OSGi Transaction Control JDBC
resource provider.
-It supports XA transactions and Local Transactions.
+It supports both XA transactions and Local Transactions. The provider also has
built-in support for
+Database connection pooling using Hikari CP.
## When should I use this module?
@@ -60,6 +61,10 @@ ResourceProvider if more than one is pre
This Resource Provider is used in conjunction with a TransactionControl
service to provide scoped
access to a JDBC connection with support for XA Transactions and Local
Transactions.
+When using XA transactions the XAResource from the Database provider is used
to integrate with an
+ongoing XA transaction. When using local transactions the JDBC API is used to
commit or rollback
+the Database connection.
+
## Creating a resource programmatically
Preparing a resource for use is very simple. Create a
<code>JDBCConnectionProvider</code> using the
