aries-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From timothyjw...@apache.org
Subject svn commit: r1741196 - in /aries/site/trunk/content/modules/tx-control: ./ index.mdtext quickstart.mdtext
Date Wed, 27 Apr 2016 10:05:26 GMT
Author: timothyjward
Date: Wed Apr 27 10:05:26 2016
New Revision: 1741196

URL: http://svn.apache.org/viewvc?rev=1741196&view=rev
Log:
Add initial transaction control documentation pages

Added:
    aries/site/trunk/content/modules/tx-control/
    aries/site/trunk/content/modules/tx-control/index.mdtext   (with props)
    aries/site/trunk/content/modules/tx-control/quickstart.mdtext   (with props)

Added: 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=1741196&view=auto
==============================================================================
--- aries/site/trunk/content/modules/tx-control/index.mdtext (added)
+++ aries/site/trunk/content/modules/tx-control/index.mdtext Wed Apr 27 10:05:26 2016
@@ -0,0 +1,40 @@
+Title:
+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.
+
+#The Transaction Control service
+
+If you're new to the Transaction Control service then we suggest that you read the [Quick
Start Page][1]
+first.
+
+###The Aries Transaction Control implementations
+
+* TODO Local Transactions
+* TODO XA Transactions and Last Participant support
+
+###Configuring JDBC access
+
+* TODO With Local Transactions
+* TODO With XA Transactions
+
+###Configuring JPA access
+
+* TODO With Local Transactions
+* TODO With XA Transactions
+
+
+  [1]: quickstart.html
\ No newline at end of file

Propchange: aries/site/trunk/content/modules/tx-control/index.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native

Added: aries/site/trunk/content/modules/tx-control/quickstart.mdtext
URL: http://svn.apache.org/viewvc/aries/site/trunk/content/modules/tx-control/quickstart.mdtext?rev=1741196&view=auto
==============================================================================
--- aries/site/trunk/content/modules/tx-control/quickstart.mdtext (added)
+++ aries/site/trunk/content/modules/tx-control/quickstart.mdtext Wed Apr 27 10:05:26 2016
@@ -0,0 +1,127 @@
+Title:
+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.
+
+#Getting started with the Transaction Control Service
+
+To make use of scoped resources and transactions using the transaction control service you
need two things:
+
+ * A <code>org.osgi.service.transaction.control.TransactionControl</code> implementation

+(found in the service registry)
+
+ * A <code>org.osgi.service.transaction.control.ResourceProvider</code> for each
of the 
+resources that you want to use.
+
+
+##Scoping Work using TransactionControl
+
+The Transaction Control Service defines three different scopes:
+
+* Unscoped - There is no scope associated with the current thread
+
+* _No Transaction Scope_ - There is a scope associated with the current thread, but no ongoing
transaction
+
+* _Transactional Scope_ - There is an ongoing transaction associated with the current thread
+
+Scoped resources have different behaviours in each of these three scopes:
+
+* Unscoped - The resource is generally not usable and will throw exceptions
+
+* _No Transaction_ Scope - The same physical resource will be used throughout the scope,

+and will be automatically tidied up at the end of the scope (e.g. closed or returned to a
pool)
+
+* _Transactional Scope_ - The same physical resource will be used throughout the scope, will
be 
+automatically committed or rolled back up at the end of the transaction, and then tidied
up afterwards
+
+###Starting and Finishing scopes
+
+A scope is defined using a piece of work wrapped in a <code>Callable</code>.
This means that it is lambda-friendly.
+
+    Integer result = txControl.required(() -> {
+            //Work goes in here
+            return 42;
+        });
+
+The scope starts immediately before the work is executed, and finishes immediately afterwards.
The 
+<code>required</code> and <code>requiresNew</code> methods can be
used to ensure that a 
+_Transactional_ scope has been started. The <code>supports</code> and <code>notSupported</code>
+methods can be used to ensure that a _No Transaction_ scope has been started.
+
+For more advanced scope control techniques look [here][1]
+
+##Accessing Resources
+
+A <code>ResourceProvider</code> is a generic factory for scoped resources. Typically
you will use a more 
+specific interface for type safety. For example the Transaction Control specification defines

+<code>JDBCConnectionProvider</code> and <code>JPAEntityManagerProvider</code>
interfaces. If
+needed you can [make your own ResourceProvider][2].
+
+To create your scoped resource you make one call to <code>getResource</code>
passing in the 
+<code>TransactionControl</code> service that the resource should integrate with.
The returned object
+is thread-safe, and can be cached for use in any scope.
+
+###Declarative Services Example
+
+The following component provides read and write access using JDBC to a list of messages created
by a user. 
+The transactionality and lifecycle of the database resources is automatically managed.
+
+    @Component
+    public class MyDaoImpl implements MyDao {
+
+        @Reference
+        TransactionControl control;
+
+        Connection dbConn;
+        
+        @Reference
+        void setResource(JDBCConnectionProvder provider) {
+            dbConn = provider.getResource(control);
+        }
+        
+        @Override
+        public void saveMessage(String user, String message) {
+            txControl.required(() -> {
+                    PreparedStatement ps = connection.prepareStatement(
+                            "Insert into MESSAGES values ( ?, ? )");
+                    ps.setString(1, user);
+                    ps.setString(2, message);
+                    return ps.executeUpdate();
+                });
+        }
+        
+        @Override
+        public void getMessagesForUser(String user) {
+            return txControl.supports(() -> {
+                    PreparedStatement ps = connection.prepareStatement(
+                            "Select MESSAGE FROM MESSAGES WHERE USER = ?");
+                    ps.setString(1, user);
+                    
+                    List<String> result = new ArrayList<>();
+
+                    ResultSet rs = ps.executeQuery();
+                    
+                    while(rs.next()) {
+                        result.add(rs.getString(1));
+                    }
+                    
+                    return result;
+                });
+        }
+    }
+
+  [1]: advancedScopes.html
+  [2]: advancedResourceProviders
\ No newline at end of file

Propchange: aries/site/trunk/content/modules/tx-control/quickstart.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message