Add initial documentation page for the Transaction Control service
git-svn-id: https://svn.apache.org/repos/asf/aries/site/trunk/content@1741064 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/modules/transactioncontrol.mdtext b/modules/transactioncontrol.mdtext
new file mode 100644
index 0000000..f2f9766
--- /dev/null
+++ b/modules/transactioncontrol.mdtext
@@ -0,0 +1,30 @@
+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.
+
+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.
+
+# 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 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.
\ No newline at end of file
