Author: timothyjward
Date: Thu Apr 28 15:38:34 2016
New Revision: 1741462
URL: http://svn.apache.org/viewvc?rev=1741462&view=rev
Log:
Add Documentation for the JDBC Provider implementations
Added:
aries/site/trunk/content/modules/tx-control/localJDBC.mdtext (with props)
aries/site/trunk/content/modules/tx-control/xaJDBC.mdtext (with props)
Modified:
aries/site/trunk/content/modules/transactioncontrol.mdtext
aries/site/trunk/content/modules/tx-control/index.mdtext
Modified: aries/site/trunk/content/modules/transactioncontrol.mdtext
URL:
http://svn.apache.org/viewvc/aries/site/trunk/content/modules/transactioncontrol.mdtext?rev=1741462&r1=1741461&r2=1741462&view=diff
==============================================================================
--- aries/site/trunk/content/modules/transactioncontrol.mdtext (original)
+++ aries/site/trunk/content/modules/transactioncontrol.mdtext Thu Apr 28
15:38:34 2016
@@ -1,4 +1,4 @@
-Title: TransactionsProject
+Title: Aries Transaction Control Service
OSGi Transaction Control Service
---------------------------------
Modified: aries/site/trunk/content/modules/tx-control/index.mdtext
URL:
http://svn.apache.org/viewvc/aries/site/trunk/content/modules/tx-control/index.mdtext?rev=1741462&r1=1741461&r2=1741462&view=diff
==============================================================================
--- aries/site/trunk/content/modules/tx-control/index.mdtext (original)
+++ aries/site/trunk/content/modules/tx-control/index.mdtext Thu Apr 28
15:38:34 2016
@@ -28,8 +28,8 @@ first.
###Configuring JDBC access
-* TODO With Local Transactions
-* TODO With XA Transactions
+* [JDBC with Local Transactions][4]
+* [JDBC with XA Transactions][5]
###Configuring JPA access
@@ -38,12 +38,14 @@ first.
###Advanced topics
-* [Custom Resource Providers][4]
-* [Advanced Scope control][5]
+* [Custom Resource Providers][6]
+* [Advanced Scope control][7]
[1]: quickstart.html
[2]: localTransactions.html
[3]: xaTransactions
- [4]: advancedResourceProviders.html
- [5]: advancedScopes.html
\ No newline at end of file
+ [4]: localJDBC.html
+ [5]: xaJDBC.html
+ [6]: advancedResourceProviders.html
+ [7]: advancedScopes.html
\ No newline at end of file
Added: aries/site/trunk/content/modules/tx-control/localJDBC.mdtext
URL:
http://svn.apache.org/viewvc/aries/site/trunk/content/modules/tx-control/localJDBC.mdtext?rev=1741462&view=auto
==============================================================================
--- aries/site/trunk/content/modules/tx-control/localJDBC.mdtext (added)
+++ aries/site/trunk/content/modules/tx-control/localJDBC.mdtext Thu Apr 28
15:38:34 2016
@@ -0,0 +1,201 @@
+Title: Local JDBC Configuration Provider
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+#Aries OSGi Transaction Control JDBC Provider (Local)
+
+The Aries Local JDBC provider implementation is available at the following
maven coordinates:
+
+ <dependency>
+ <groupId>org.apache.aries.tx-control</groupId>
+ <artifactId>tx-control-provider-jdbc-local</artifactId>
+ <version>${aries.tx.control.version}</version>
+ </dependency>
+
+This module is a prototype implementation of the OSGi Transaction Control JDBC
resource provider.
+It supports Local transactions only.
+
+## 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 Aries Local Transaction Control service bundle.
+
+If two-phase commit is needed across multiple resources then an XA capable
Resource Provider should be
+used instead if possible.
+
+##Quick Start
+
+A configured JDBCConnectionProvider can be created quickly using Configuration
Admin and the
+OSGi JDBC Service.
+
+1. Find and install a JDBC Service implementation for your chosen database
(e.g. the org.h2 bundle for H2)
+1. Create a factory configuration using the factory pid
<code>org.apache.aries.tx.control.jdbc.local</code>
+ and add the following properties:
+ * *osgi.jdbc.driver.class* :- The driver class name (e.g. org.h2.Driver)
+ * *url* :- The JDBC URL to use to connect to the database
+
+When the DataSourceFactory for the named <code>osgi.jdbc.driver.class</code>
becomes available
+the Local JDBC Resource Provider will create a JDBCConnectionProvider and
register it in the OSGi
+service registry. All configuration properties (apart from the database
password) will be registered as
+properties of the JDBCConnectionProvider service. These properties can be used
to select a
+ResourceProvider if more than one is present in the Service Registry.
+
+
+# Using the Local JDBC Provider bundle (details)
+
+This Resource Provider is used in conjunction with a TransactionControl
service to provide scoped
+access to a JDBC connection with support for Local Transactions.
+
+## Creating a resource programmatically
+
+Preparing a resource for use is very simple. Create a
<code>JDBCConnectionProvider</code> using the
+<code>JDBCConnectionProviderFactory</code> service from the service registry,
then connect that
+provider to a <code>TransactionControl</code> 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).
+
+###Declarative Services Example
+
+ @Component
+ public class TransactionalJDBCComponent {
+ @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 a 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 <code>JDBCConnectionProviderFactory</code> 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
+<code>JDBCConnectionProvider</code>. These properties may therefore be used in
filters to select
+a particular provider.
+
+
+###Declarative Services Example
+
+ @Component
+ public class TransactionalJDBCComponent {
+
+ @Reference
+ TransactionControl control;
+
+ Connection conn;
+
+ @Reference(target="(dataSourceName=myDataSource)")
+ void setProvider(JDBCConnectionProvider provider) {
+ conn = provider.getResource(control);
+ }
+
+ public void findUserName(String id) {
+ control.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
+
+* *url* : The JDBC url to use (often used instead of other properties such as
*serverName*, *portNumber* and *databaseName*).
+
+* *user* : The JDBC user
+
+* *password* : The JDBC password
\ No newline at end of file
Propchange: aries/site/trunk/content/modules/tx-control/localJDBC.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
Added: aries/site/trunk/content/modules/tx-control/xaJDBC.mdtext
URL:
http://svn.apache.org/viewvc/aries/site/trunk/content/modules/tx-control/xaJDBC.mdtext?rev=1741462&view=auto
==============================================================================
--- aries/site/trunk/content/modules/tx-control/xaJDBC.mdtext (added)
+++ aries/site/trunk/content/modules/tx-control/xaJDBC.mdtext Thu Apr 28
15:38:34 2016
@@ -0,0 +1,202 @@
+Title: Aries OSGi Transaction Control JDBC Provider (XA)
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+#Aries OSGi Transaction Control JDBC Provider (XA)
+
+The Aries Local JDBC provider implementation is available at the following
maven coordinates:
+
+ <dependency>
+ <groupId>org.apache.aries.tx-control</groupId>
+ <artifactId>tx-control-provider-jdbc-xa</artifactId>
+ <version>${aries.tx.control.version}</version>
+ </dependency>
+
+This module is a prototype implementation of the OSGi Transaction Control JDBC
resource provider.
+It supports XA transactions and Local Transactions.
+
+## 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 can be
used instead.
+
+##Quick Start
+
+A configured JDBCConnectionProvider can be created quickly using Configuration
Admin and the
+OSGi JDBC Service.
+
+1. Find and install a JDBC Service implementation for your chosen database
(e.g. the org.h2 bundle for H2)
+1. Create a factory configuration using the factory pid
<code>org.apache.aries.tx.control.jdbc.xa</code>
+ and add the following properties:
+ * *osgi.jdbc.driver.class* :- The driver class name (e.g. org.h2.Driver)
+ * *url* :- The JDBC URL to use to connect to the database
+
+When the DataSourceFactory for the named <code>osgi.jdbc.driver.class</code>
becomes available
+the Local JDBC Resource Provider will create a JDBCConnectionProvider and
register it in the OSGi
+service registry. All configuration properties (apart from the database
password) will be registered as
+properties of the JDBCConnectionProvider service. These properties can be used
to select a
+ResourceProvider if more than one is present in the Service Registry.
+
+
+# Using the XA JDBC Provider bundle (details)
+
+This Resource Provider is used in conjunction with a TransactionControl
service to provide scoped
+access to a JDBC connection with support for XA Transactions and Local
Transactions.
+
+## Creating a resource programmatically
+
+Preparing a resource for use is very simple. Create a
<code>JDBCConnectionProvider</code> using the
+<code>JDBCConnectionProviderFactory</code> service from the service registry,
then connect that
+provider to a <code>TransactionControl</code> service. This will return a
thread-safe JDBC connection
+that can then be used in any ongoing scoped work. The
JDBCConnectionProviderFactory service is registered
+with the <code>osgi.xa.enabled</code> property set to <code>true</code>.
+
+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).
+
+###Declarative Services Example
+
+ @Component
+ public class TransactionalJDBCComponent {
+ @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 a 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 <code>JDBCConnectionProviderFactory</code> 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
+<code>JDBCConnectionProvider</code>. These properties may therefore be used in
filters to select
+a particular provider.
+
+
+###Declarative Services Example
+
+ @Component
+ public class TransactionalJDBCComponent {
+
+ @Reference
+ TransactionControl control;
+
+ Connection conn;
+
+ @Reference(target="(dataSourceName=myDataSource)")
+ void setProvider(JDBCConnectionProvider provider) {
+ conn = provider.getResource(control);
+ }
+
+ public void findUserName(String id) {
+ control.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
+
+* *url* : The JDBC url to use (often used instead of other properties such as
*serverName*, *portNumber* and *databaseName*).
+
+* *user* : The JDBC user
+
+* *password* : The JDBC password
Propchange: aries/site/trunk/content/modules/tx-control/xaJDBC.mdtext
------------------------------------------------------------------------------
svn:eol-style = native
