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
