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
+
