| = Aries Transaction Control Service |
| |
| == OSGi Transaction Control Service |
| |
| This set of modules is an implementation of the proposed OSGi Transaction Control Service and related services, such as JDBC and JPA resource providers. |
| |
| 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. |
| |
| == Getting started |
| |
| The current released version of Transaction Control is 0.0.1, and it is available in https://mvnrepository.com/artifact/org.apache.aries.tx-control[Maven Central] |
| |
| If you're new to the Transaction Control service then we recommend that you read the xref:modules/tx-control/quickstart.adoc[quickstart documentation first]. |
| |
| More detailed documentation is available in the xref:modules/tx-control/index.adoc[Aries Transaction Control Project] |
| |
| == Why use the Transaction Control service? |
| |
| Simply put the Transaction Control service makes resource access easy! |
| There's no need to worry about transaction lifecycle or closing connections, and there's built in support for useful features like connection pooling. |
| |
| In addition to being simple the Transaction Control service also makes transaction management explicit. |
| As a result it is easier to follow the transactions flowing throughout your code, and it protects you from the xref:modules/tx-control/spring-tx.adoc[proxy problem] that declarative transaction strategies often suffer from. |
| |
| == Modules |
| |
| The following modules are available for use in OSGi |
| |
| . xref:modules/tx-control/localTransactions.adoc[tx-control-service-local] :- A purely local transaction control service implementation. |
| This can be used with any resource-local capable ResourceProvider |
| . xref:modules/tx-control/xaTransactions.adoc[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. |
| . xref:modules/tx-control/localJDBC.adoc[tx-control-provider-jdbc-local] :- A JDBC resource provider that provides connection pooling and 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 |
| . xref:modules/tx-control/xaJDBC.adoc[tx-control-provider-jdbc-xa] :- A JDBC resource provider that provides connection pooling and 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 |
| . xref:modules/tx-control/localJPA.adoc[tx-control-provider-jpa-local] :- A JPA resource provider that can integrate with local transactions. |
| The JPAEntityManagerProviderFactory service may be used directly, or a service may be configured using the _org.apache.aries.tx.control.jpa.local_ pid. |
| The implementation can also provide connection pooling if required |
| . xref:modules/tx-control/xaJPA.adoc[tx-control-provider-jpa-xa] :- A JDBC resource provider that integrates with XA transactions. |
| The JPAEntityManagerProviderFactory service may be used directly, or a service may be configured using the _org.apache.aries.tx.control.jpa.xa_ pid. |
| The implementation can also provide connection pooling if required |
| |
| === 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 or tx-control-provider-jpa-local bundles. |
| This will give transactional behaviour, but the result is _not guaranteed to be ACID if more than one resource is used_. |
| |
| If ACID behaviour is needed across multiple resources then the tx-control-service-xa _must_ be used. |
| This service also provides an XA enabled two-phase commit algorithm, and also allows for ACID behaviour when _one_ of the resources only supports local transactions by using the last participant gambit. |
| |
| When using the XA Transaction control service then the tx-control-provider-jdbc-xa or tx-control-provider-jpa-xa resource provider bundles should be used. |
| |
| *IT IS NOT RECOMMENDED* to use both tx-control-service-xa and tx-control-service-local at the same time. |
| This will be confusing, and may lead to problems if different parts of the application bind to different service implementations. |
| |
| *NOTE:* 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. |
| The same is *not* true of the JPA provider implementations. |
| |
| == Pre-release APIs |
| |
| As part of the Aries Transaction Control implementations pre-release versions of the OSGi Transaction Control API are provided. |
| Rather than putting the API into the wrong package namespace, or outputting them at the wrong version, they will be exported with a mandatory attribute of `api.status=aries.prerelease`. |
| |
| By setting this attribute on their API imports users accept that the API may change without a change to the package version(s). |
| These changes may, or may not, be binary compatible. |
| Once the specification is final the attribute will be removed from the export. |
