aries-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From timothyjw...@apache.org
Subject svn commit: r1741488 - in /aries/site/trunk/content/modules/tx-control: coordinator.mdtext index.mdtext lastResourceGambit.mdtext localJDBC.mdtext xaJDBC.mdtext
Date Thu, 28 Apr 2016 18:35:43 GMT
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 



Mime
View raw message