You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@aries.apache.org by ti...@apache.org on 2016/03/14 17:50:29 UTC

svn commit: r1734959 - in /aries/trunk/tx-control: README tx-control-provider-jdbc-local/README tx-control-provider-jdbc-xa/README

Author: timothyjward
Date: Mon Mar 14 16:50:28 2016
New Revision: 1734959

URL: http://svn.apache.org/viewvc?rev=1734959&view=rev
Log:
[tx-control] Add README documentation to various tx-control projects

Added:
    aries/trunk/tx-control/tx-control-provider-jdbc-local/README
    aries/trunk/tx-control/tx-control-provider-jdbc-xa/README
Modified:
    aries/trunk/tx-control/README

Modified: aries/trunk/tx-control/README
URL: http://svn.apache.org/viewvc/aries/trunk/tx-control/README?rev=1734959&r1=1734958&r2=1734959&view=diff
==============================================================================
--- aries/trunk/tx-control/README (original)
+++ aries/trunk/tx-control/README Mon Mar 14 16:50:28 2016
@@ -7,3 +7,119 @@ The Transaction Control Service (RFC-221
 
 Given that the RFC is non-final the OSGi API declared in this project is subject to change at any time up to its official release. Also the behaviour of this implementation may not always be up-to-date with the latest wording in the RFC. The project maintainers will, however try to keep pace with the RFC, and to ensure that the implementations are compliant with any OSGi specifications that result from the RFC.
 
+# Modules
+
+The following modules are available for use in OSGi
+
+1. tx-control-service-local :- A purely local transaction control service implementation. This can be used with any resource-local capable ResourceProvider
+2. tx-control-service-xa :- An XA-capable transaction control service implementation based on the Geronimo Transaction Manager. This can be used with XA capable resources, or with local resources. Local resources will make use of the last-participant gambit.
+3. tx-control-provider-jdbc-local := A JDBC resource provider that can integrate with local transactions. The JDBCConnectionProviderFactory service may be used directly, or a service may be configured using the _org.apache.aries.tx.control.jdbc.local_ pid
+4. tx-control-provider-jdbc-xa := A JDBC resource provider that can integrate with local or XA transactions. The JDBCConnectionProviderFactory service may be used directly, or a service may be configured using the _org.apache.aries.tx.control.jdbc.xa_ pid
+
+
+## Which modules should I use?
+
+If you wish to use entirely lightweight, resource-local transactions then it is best to pair the tx-control-service-local and tx-control-provider-jdbc-local bundles.
+
+If two-phase commit is needed across multiple resources then the tx-control-service-xa and tx-control-provider-jdbc-xa bundles should be used.
+
+DO NOT use both tx-control-service-xa and tx-control-service-local at the same time. This will be confusing, and will lead to problems if different parts of the runtime bind to different service implementations.
+
+There is also no reason to use the tx-control-provider-jdbc-local in addition to the tx-control-provider-jdbc-xa service. Using both together is not typically harmful, however the tx-control-provider-jdbc-xa bundle supports all of the same features as the tx-control-provider-jdbc-local bundle.
+
+# Using the Transaction Control Service
+
+The Transaction Control service is used in conjunction with one or more ResourceProvider services to provide scoped resource access.
+
+## Creating a resource
+
+Preparing a resource for use is very simple. Connect the ResourceProvider to a TransactionControl, and the thread-safe created resource can then be used in any ongoing scoped work.
+
+    @Reference
+    TransactionControl txControl;
+
+    @Reference
+    ResourceProvider<MyResource> provider;
+
+    MyResource resource;
+
+    @Activate
+    void start() {
+        resource = provider.getResource(txControl);
+    }
+
+    /**
+     * Persists data inside a transaction
+     */
+    public void persistData(MyData data) {
+        txControl.required(() -> resource.persist(data));
+    } 
+
+
+### Specialised resource interfaces
+
+The OSGi service registry does not natively handle genericized types, so the Transaction Control RFC defines specialised interface types for common resource types, for example the JDBCConnectionProvider.
+
+    @Reference
+    TransactionControl txControl;
+
+    @Reference
+    JDBCConnectionProvider provider;
+
+    Connection conn;
+
+    @Activate
+    void start() {
+        conn = provider.getResource(txControl);
+    }
+
+    public void findUserName(String id) {
+        txControl.required(() -> {
+                // Use the connection in here
+            });
+    } 
+
+## Controlling the transaction lifecycle
+
+When using the Transaction Control service your code is running in one of three scopes:
+
+1. Unscoped :- In this case there is no scope associated with the thread. Resources cannot be used and will throw Exceptions.
+2. No Transaction Scope :- Resources may be used in this scope, but there is no transaction associated with the thread. This means that resources will be cleaned up at the end of the scope but no work will be committed. Changes in this scope may not be atomic.
+3. Transaction Scope := In this case there is an active transaction and resources will participate in it. Updates and reads will be atomic, and will all roll back in the event of a failure.
+
+
+### Starting a Transaction
+
+To start a transaction simply pass a Callable to the required method of the TransactionControl service. The Callable will be run scoped in a transaction
+
+    txControl.required(() -> {
+            // Use the connection in here
+        });
+
+Transactions may be nested:
+
+    txControl.required(() -> {
+    
+            // Use the connection in here
+    
+            txControl.required(() -> {
+                    // Nested transaction in here
+                });
+
+        });
+
+Transactions may be or suspended:
+
+    txControl.required(() -> {
+    
+            // Use the connection in here
+    
+            txControl.notSupported(() -> {
+                    // Nested transaction in here
+                });
+
+        });
+
+### Advanced usage
+
+For more advanced usage see the API JavaDoc, and read the RFC (https://github.com/osgi/design/blob/master/rfcs/rfc0221/rfc-0221-TransactionControl.pdf)
\ No newline at end of file

Added: aries/trunk/tx-control/tx-control-provider-jdbc-local/README
URL: http://svn.apache.org/viewvc/aries/trunk/tx-control/tx-control-provider-jdbc-local/README?rev=1734959&view=auto
==============================================================================
--- aries/trunk/tx-control/tx-control-provider-jdbc-local/README (added)
+++ aries/trunk/tx-control/tx-control-provider-jdbc-local/README Mon Mar 14 16:50:28 2016
@@ -0,0 +1,120 @@
+Sample OSGi Transaction Control JDBC Provider (Local)
+-----------------------------------------------------
+
+This module is a prototype implementation of the OSGi Transaction Control JDBC resource provider. It supports Local transactions only.
+
+The Transaction Control Service (RFC-221) is an in-progress RFC publicly available from the OSGi Alliance: https://github.com/osgi/design/blob/master/rfcs/rfc0221/rfc-0221-TransactionControl.pdf
+
+Given that the RFC is non-final the OSGi API declared in this project is subject to change at any time up to its official release. Also the behaviour of this implementation may not always be up-to-date with the latest wording in the RFC. The project maintainers will, however try to keep pace with the RFC, and to ensure that the implementations are compliant with any OSGi specifications that result from the RFC.
+
+# When should I use this module?
+
+If you wish to use entirely lightweight, resource-local transactions then it is best to pair this module with the tx-control-service-local bundle.
+
+If two-phase commit is needed across multiple resources then the tx-control-service-xa and tx-control-provider-jdbc-xa bundles should be used instead of this bundle
+
+# Using the JDBC Provider bundle
+
+This Resource Provider is used in conjunction with a TransactionControl service to provide scoped access to JDBC.
+
+## Creating a resource programmatically
+
+Preparing a resource for use is very simple. Create a JDBCConnectionProvider using the the JDBCConnectionProviderFactory, then connect the provider to a TransactionControl service. This will return a thread-safe JDBC connection that can then be used in any ongoing scoped work.
+
+The normal inputs to a JDBCConnectionProviderFactory are a DataSourceFactory, some jdbc properties to connect to the database with, and some properties to control the resource provider (such as connection pooling)
+
+
+    @Reference
+    TransactionControl txControl;
+
+    @Reference
+    DataSourceFactory dsf;
+
+    @Reference
+    JDBCConnectionProviderFactory providerFactory;
+
+    Connection conn;
+
+    @Activate
+    void start(Config config) {
+
+        Properties jdbcProps = new Properties();
+        jdbcProps.put(JDBC_URL, config.url());
+        jdbcProps.put(JDBC_USER, config.user());
+        jdbcProps.put(JDBC_PASSWORD, config._password());
+
+        Map<String, Object> providerProps = new HashMap<>();
+        providerProps.put(MAX_POOL_SIZE, 8);
+
+        conn = providerFactory.getProviderFor(dsf, 
+                   jdbcProps, providerProps).getResource(txControl);
+    }
+
+    public void findUserName(String id) {
+        txControl.required(() -> {
+                // Use the connection in here
+            });
+    } 
+
+If the JDBC DataSource/Driver is already configured then it can be passed in to the JDBCConnectionProviderFactory instead of a DataSourceFactory and JDBC configuration.
+
+
+## Creating a resource using a factory configuration
+
+Whilst it is simple to use a JDBCConnectionProviderFactory it does require some lifecycle code to be written. It is therefore possible to directly create JDBC resources using factory configurations. When created, the factory service will listen for an applicable DataSourceFactory. Once a suitable DataSourceFactory is available then a JDBCConnectionProvider service will be published. 
+
+Configuration properties (except the JDBC password) are set as service properties for the registered JDBCConnectionProvider. These properties may therefore be used in filters to select a particular provider.
+
+    @Reference
+    TransactionControl txControl;
+
+    @Reference(target="(dataSourceName=myDataSource)")
+    JDBCConnectionProvider provider;
+
+    Connection conn;
+
+    @Activate
+    void start(Config config) {
+        conn = provider.getResource(txControl);
+    }
+
+    public void findUserName(String id) {
+        txControl.required(() -> {
+                // Use the connection in here
+            });
+    } 
+
+
+
+The factory pid is _org.apache.aries.tx.control.jdbc.local_ and it may use the following properties (all optional):
+
+### Resource Provider properties
+
+*aries.dsf.target.filter* : The target filter to use when searching for a DataSourceFactory. If not specified then *osgi.jdbc.driver.class* must be specified.
+*aries.jdbc.property.names* : The names of the properties to pass to the DataSourceFactory when creating the JDBC resources
+*osgi.jdbc.driver.class* : Used to locate the DataSourceFactory service if the *aries.dsf.target.filter* is not set.
+*osgi.local.enabled* : Defaults to true. If false then resource creation will fail
+*osgi.xa.enabled* : Defaults to false. If true then resource creation will fail
+*osgi.connection.pooling.enabled* : Defaults to true. If true then the Database connections will be pooled.
+*osgi.connection.max* : Defaults to 10. The maximum number of connections that should be kept in the pool
+*osgi.connection.min* : Defaults to 10. The minimum number of connections that should be kept in the pool
+*osgi.connection.timeout* : Defaults to 30,000 (30 seconds). The maximum time in milliseconds to block when waiting for a database connection
+*osgi.idle.timeout* : Defaults to 180,000 (3 minutes). The time in milliseconds before an idle connection is eligible to be closed.
+*osgi.connection.timeout* : Defaults to 10,800,000 (3 hours). The maximum time in milliseconds that a connection may remain open before being closed.
+*osgi.use.driver* : Defaults to false. If true then use the createDriver method to connect to the database.
+
+
+### JDBC properties
+
+The following properties will automatically be passed to the DataSourceFactory if they are present. The list of properties may be overridden using the *aries.jdbc.property.names* property if necessary.
+
+*databaseName* : The name of the database
+*dataSourceName* : The name of the dataSource that will be created
+*description* : A description of the dataSource being created
+*networkProtocol* : The network protocol to use.
+*portNumber* : The port number to use
+*roleName* : The name of the JDBC role
+*serverName* : The name of the database server
+*user* : The JDBC user
+*password* : The JDBC password
+

Added: aries/trunk/tx-control/tx-control-provider-jdbc-xa/README
URL: http://svn.apache.org/viewvc/aries/trunk/tx-control/tx-control-provider-jdbc-xa/README?rev=1734959&view=auto
==============================================================================
--- aries/trunk/tx-control/tx-control-provider-jdbc-xa/README (added)
+++ aries/trunk/tx-control/tx-control-provider-jdbc-xa/README Mon Mar 14 16:50:28 2016
@@ -0,0 +1,120 @@
+Sample OSGi Transaction Control JDBC Provider (XA)
+--------------------------------------------------
+
+This module is a prototype implementation of the OSGi Transaction Control JDBC resource provider. It supports XA and Local transactions.
+
+The Transaction Control Service (RFC-221) is an in-progress RFC publicly available from the OSGi Alliance: https://github.com/osgi/design/blob/master/rfcs/rfc0221/rfc-0221-TransactionControl.pdf
+
+Given that the RFC is non-final the OSGi API declared in this project is subject to change at any time up to its official release. Also the behaviour of this implementation may not always be up-to-date with the latest wording in the RFC. The project maintainers will, however try to keep pace with the RFC, and to ensure that the implementations are compliant with any OSGi specifications that result from the RFC.
+
+# When should I use this module?
+
+If two-phase commit is needed across multiple resources then it is best to pair this module with the tx-control-service-xa bundle.
+
+If you wish to use entirely lightweight, resource-local transactions then then the tx-control-service-local and tx-control-provider-jdbc-local bundles should be used instead of this bundle
+
+# Using the JDBC Provider bundle
+
+This Resource Provider is used in conjunction with a TransactionControl service to provide scoped access to JDBC.
+
+## Creating a resource programmatically
+
+Preparing a resource for use is very simple. Create a JDBCConnectionProvider using the the JDBCConnectionProviderFactory, then connect the provider to a TransactionControl service. This will return a thread-safe JDBC connection that can then be used in any ongoing scoped work.
+
+The normal inputs to a JDBCConnectionProviderFactory are a DataSourceFactory, some jdbc properties to connect to the database with, and some properties to control the resource provider (such as connection pooling)
+
+
+    @Reference
+    TransactionControl txControl;
+
+    @Reference
+    DataSourceFactory dsf;
+
+    @Reference
+    JDBCConnectionProviderFactory providerFactory;
+
+    Connection conn;
+
+    @Activate
+    void start(Config config) {
+
+        Properties jdbcProps = new Properties();
+        jdbcProps.put(JDBC_URL, config.url());
+        jdbcProps.put(JDBC_USER, config.user());
+        jdbcProps.put(JDBC_PASSWORD, config._password());
+
+        Map<String, Object> providerProps = new HashMap<>();
+        providerProps.put(MAX_POOL_SIZE, 8);
+
+        conn = providerFactory.getProviderFor(dsf, 
+                   jdbcProps, providerProps).getResource(txControl);
+    }
+
+    public void findUserName(String id) {
+        txControl.required(() -> {
+                // Use the connection in here
+            });
+    } 
+
+If the JDBC DataSource/Driver is already configured then it can be passed in to the JDBCConnectionProviderFactory instead of a DataSourceFactory and JDBC configuration.
+
+
+## Creating a resource using a factory configuration
+
+Whilst it is simple to use a JDBCConnectionProviderFactory it does require some lifecycle code to be written. It is therefore possible to directly create JDBC resources using factory configurations. When created, the factory service will listen for an applicable DataSourceFactory. Once a suitable DataSourceFactory is available then a JDBCConnectionProvider service will be published. 
+
+Configuration properties (except the JDBC password) are set as service properties for the registered JDBCConnectionProvider. These properties may therefore be used in filters to select a particular provider.
+
+    @Reference
+    TransactionControl txControl;
+
+    @Reference(target="(dataSourceName=myDataSource)")
+    JDBCConnectionProvider provider;
+
+    Connection conn;
+
+    @Activate
+    void start(Config config) {
+        conn = provider.getResource(txControl);
+    }
+
+    public void findUserName(String id) {
+        txControl.required(() -> {
+                // Use the connection in here
+            });
+    } 
+
+
+
+The factory pid is _org.apache.aries.tx.control.jdbc.xa_ and it may use the following properties (all optional):
+
+### Resource Provider properties
+
+*aries.dsf.target.filter* : The target filter to use when searching for a DataSourceFactory. If not specified then *osgi.jdbc.driver.class* must be specified.
+*aries.jdbc.property.names* : The names of the properties to pass to the DataSourceFactory when creating the JDBC resources
+*osgi.jdbc.driver.class* : Used to locate the DataSourceFactory service if the *aries.dsf.target.filter* is not set.
+*osgi.local.enabled* : Defaults to true. If false then this resource will not participate in local transactions, and will fail if used within one. One of *osgi.local.enabled* and *osgi.xa.enabled* must be true.
+*osgi.xa.enabled* : Defaults to true. If false then this resource will not participate in xa transactions, and will fail if used within one. One of *osgi.local.enabled* and *osgi.xa.enabled* must be true.
+*osgi.connection.pooling.enabled* : Defaults to true. If true then the Database connections will be pooled.
+*osgi.connection.max* : Defaults to 10. The maximum number of connections that should be kept in the pool
+*osgi.connection.min* : Defaults to 10. The minimum number of connections that should be kept in the pool
+*osgi.connection.timeout* : Defaults to 30,000 (30 seconds). The maximum time in milliseconds to block when waiting for a database connection
+*osgi.idle.timeout* : Defaults to 180,000 (3 minutes). The time in milliseconds before an idle connection is eligible to be closed.
+*osgi.connection.timeout* : Defaults to 10,800,000 (3 hours). The maximum time in milliseconds that a connection may remain open before being closed.
+*osgi.use.driver* : Defaults to false. If true then use the createDriver method to connect to the database. Cannot be true if *osgi.xa.enabled* is true.
+
+
+### JDBC properties
+
+The following properties will automatically be passed to the DataSourceFactory if they are present. The list of properties may be overridden using the *aries.jdbc.property.names* property if necessary.
+
+*databaseName* : The name of the database
+*dataSourceName* : The name of the dataSource that will be created
+*description* : A description of the dataSource being created
+*networkProtocol* : The network protocol to use.
+*portNumber* : The port number to use
+*roleName* : The name of the JDBC role
+*serverName* : The name of the database server
+*user* : The JDBC user
+*password* : The JDBC password
+