Author: timothyjward
Date: Thu Apr 28 11:14:48 2016
New Revision: 1741413
URL: http://svn.apache.org/viewvc?rev=1741413&view=rev
Log:
Document the provisional nature of the OSGi API
Modified:
aries/site/trunk/content/modules/transactioncontrol.mdtext
Modified: aries/site/trunk/content/modules/transactioncontrol.mdtext
URL:
http://svn.apache.org/viewvc/aries/site/trunk/content/modules/transactioncontrol.mdtext?rev=1741413&r1=1741412&r2=1741413&view=diff
==============================================================================
--- aries/site/trunk/content/modules/transactioncontrol.mdtext (original)
+++ aries/site/trunk/content/modules/transactioncontrol.mdtext Thu Apr 28
11:14:48 2016
@@ -3,38 +3,76 @@ Title: TransactionsProject
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.
+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
+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][1]
-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.
+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
-If you're new to the Transaction Control service then we recommend that you
read the [quickstart documentation first][1].
+If you're new to the Transaction Control service then we recommend that you
read the [quickstart documentation first][2].
-More detailed documentation is available in the [Aries Transaction Control
Project][2]
+More detailed documentation is available in the [Aries Transaction Control
Project][3]
## 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
+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
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 two-phase commit is needed across multiple resources then the
tx-control-service-xa *must* be used. and tx-control-provider-jdbc-xa or
tx-control-provider-jpa-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.
+### Which modules should I use?
- [1]: tx-control/quickstart.html
- [2]: tx-control/index.html
\ No newline at end of file
+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.
+
+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.
+
+##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
<code>api.status=aries.prerelease</code>.
+
+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.
+
+ [1]:
https://github.com/osgi/design/blob/master/rfcs/rfc0221/rfc-0221-TransactionControl.pdf
+ [2]: tx-control/quickstart.html
+ [3]: tx-control/index.html
\ No newline at end of file
