aries-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From timothyjw...@apache.org
Subject svn commit: r1734959 - in /aries/trunk/tx-control: README tx-control-provider-jdbc-local/README tx-control-provider-jdbc-xa/README
Date Mon, 14 Mar 2016 16:50:29 GMT
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
+



Mime
View raw message