commit | 46d053bebe986281c687ab65e8eb78baa49b07d5 | [log] [tgz] |
---|---|---|
author | timothyjward <timothyjward@13f79535-47bb-0310-9956-ffa450edef68> | Fri May 27 18:10:18 2016 +0000 |
committer | timothyjward <timothyjward@13f79535-47bb-0310-9956-ffa450edef68> | Fri May 27 18:10:18 2016 +0000 |
tree | 5d3d51d46d368095399e9ba7bf31ab7977d95b75 | |
parent | 78d13bad76177784ec599d58e7df4be7a5c19527 [diff] |
[tx-control] Tidy up JavaDoc for Transaction Control API git-svn-id: https://svn.apache.org/repos/asf/aries/trunk/tx-control@1745797 13f79535-47bb-0310-9956-ffa450edef68
This set of modules is a prototype implementation of the OSGi Transaction Control Service and related services, such as JDBC resource provision.
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.
The following modules are available for use in OSGi
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.
The Transaction Control service is used in conjunction with one or more ResourceProvider services to provide scoped resource access.
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)); }
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 }); }
When using the Transaction Control service your code is running in one of three scopes:
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 }); });
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)