User: allsopp
Date: 01/02/03 23:50:14
Modified: documentation jca_config.html
Log:
Updated the documentation to be consistent with the current JCA
implementation.
Revision Changes Path
1.5 +112 -111 newsite/documentation/jca_config.html
Index: jca_config.html
===================================================================
RCS file: /products/cvs/ejboss/newsite/documentation/jca_config.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- jca_config.html 2001/01/18 07:44:25 1.4
+++ jca_config.html 2001/02/04 07:50:14 1.5
@@ -57,6 +57,12 @@
<dt>Connection factory</dt>
<dd>an object, available through JNDI, that provides access to
connections to a particular resource instance</dd>
+
+ <dt>Connection manager</dt>
+ <dd>an object that implements the
+ <code>javax.resource.spi.ConnectionManager</code>
+ interface - provides connection pooling, transaction
+ association, security and other "quality of services"</dd>
</dl>
</div>
@@ -82,15 +88,12 @@
<div class="code">
<mbean code="org.jboss.resource.ConnectionFactoryLoader"
- name="J2EE:service=ConnectionFactoryLoader">
+ name="JCA:service=ConnectionFactoryLoader,name=name">
<!-- General attributes -->
<attribute name="name">value</attribute>
<!-- Security attributes -->
<attribute name="name">value</attribute>
-
- <!-- Connection pooling attributes -->
- <attribute name="name">value</attribute>
</mbean>
</div>
@@ -137,6 +140,28 @@
format (essentially one property per
line, name=value).</td>
</tr>
+ <tr>
+ <td>ConnectionManagerFactoryName</td>
+ <td>The name of the connection manager factory to use. This
+ is the name given in a previously defined
+ <code>ConnectionManagerFactoryLoader</code>
+ MBean. Currently there are two choices:
+ <code>MinervaSharedLocalCMFactory</code> and
+ <code>MinervaXACMFactory</code>. The former should be
+ used for resource adapters that support local
+ transactions and the latter for those that support XA
+ transactions.</td>
+ </tr>
+ <tr>
+ <td>ConnectionManagerProperties</td>
+ <td>The properties (in
+ <code>java.util.Properties.load</code> format) to set on
+ the connection manager for this connection
+ factory. These properties control things such as
+ connection pooling parameters. The example connection
+ factory in <code>jboss.jcml</code> shows the possible
+ properties for the Minerva connection managers.</td>
+ </tr>
</tbody>
</table>
</div>
@@ -145,10 +170,6 @@
<div class="para">TBD - no interesting options yet</div>
- <h4>Connection Pooling Attributes</h4>
-
- <div class="para">TBD - mostly the same as for JDBC connection pools</div>
-
<h3>Deploying the Resource Adapter</h3>
<div class="para">
@@ -168,140 +189,116 @@
file.
</div>
+ <div class="para">
+ The easiest way to invoke operations on MBeans is using the HTML
+ adapter that is, by default, accessible on port 8082, i.e. point
+ a browser at <a
+ href="http://localhost:8082">http://localhost:8082</a> if
+ running the browser on the machine running JBoss. Then find the
+ RARDeployer MBean and it should be self explanatory from there.
+ </div>
+
<h2><a name="example">Example - Black Box Example Adapter from Sun</a></h2>
<div class="para">
For this example you will need Sun's example resource adapter,
- available <a href="blackbox-xa.rar">here</a>. The <a
+ available <a href="blackbox-tx.rar">here</a>. The <a
href="connector-1_0-ea-src.zip">source code</a> for this
resource adapter is also available - this is useful if writing
your own adapter.
</div>
<div class="para">
- This resource adapter access a JDBC 2.0 standard extension
- compliant database. The advantage of this is that you don't need
- any weird or wacky resource to access and that you can compare
- the behaviour with a straight JDBC connection pool.
+ This resource adapter accesses a JDBC 2.0 compliant
+ database. The advantage of this is that you don't need any weird
+ or wacky resource to access and that you can compare the
+ behaviour with a straight JDBC connection pool.
</div>
<div class="para">
- The Black Box resource adapter uses an XA-compliant data source
- (<code>javax.sql.XADataSource</code>) to access the JDBC
- database, and it needs to access this data source through
- JNDI. In order to make this available, the MBean
- <code>RawXADataSourceLoader</code> can be used (the name
- <code>XADataSourceLoader</code> is already taken by the JDBC
- connection pools). This MBean is set up by an entry like the
- following in <code>jboss.jcml</code>.
- </div>
-
- <div class="code">
-<mbean code="org.jboss.jdbc.RawXADataSourceLoader"
- name="DefaultDomain:service=RawXADataSourceLoader,name=BlackBoxXADS">
- <attribute name="PoolName">BlackBoxXADS</attribute>
- <attribute
-
name="DataSourceClass">org.jboss.minerva.xa.XADataSourceImpl</attribute>
- <attribute name="Properties">
- URL=jdbc:HypersonicSQL:hsql://localhost:1476
- </attribute>
-</mbean>
- </div>
-
- <div class="para">
- The <code>RawXADataSourceLoader</code> MBean is very similar to
- set up to the <code>XADataSourceImpl</code> MBean, but the
- properties setting is slightly different.
- </div>
-
- <div class="para">
- <table class="attributes">
- <caption><code>RawXADataSourceLoader</code> attributes</caption>
- <thead>
- <tr><th>Name</th><th>Description</th></tr>
- </thead>
- <tbody>
- <tr>
- <td>PoolName</td> <td>The name of this XA data source. The
- data source will be bound in JNDI
- under this name, in the
- <code>java:</code> namespace.</td>
- </tr>
- <tr>
- <td>DataSourceClass</td> <td>The name of the class that
- implements
- <code>javax.sql.XADataSource</code>.
- </td>
- </tr>
- <tr>
- <td>Properties</td> <td>A collection of name=value pairs,
- one on each line, that specifies
- the attributes to set on the
- <code>XADataSource</code>
- instance. For each pair
- <code>Name=Value</code>, the
- method <code>setName(Value)</code>
- will be called on the
- <code>XADataSource</code>
- instance. At the moment it is only
- possible to set
- <code>String</code>
- attributes.<td>
- </tr>
- </tbody>
- </table>
- </div>
-
- <div class="para">
- Once the <code>XADataSource</code> is set up, we need to add the
+ In order to make a connection factory from this resource adapter
+ available to application components, we need to add the
<code>ConnectionFactoryLoader</code> MBean that will create the
connection factory from the resource adapter when it is
deployed. We will create a connection factory called
<code>BlackBoxDS</code> that will appear in JNDI at
<code>java:/BlackBoxDS</code>. Below is the MBean definition
- that we will use.
+ that we will use (this is taken from the default
+ <code>jboss.jcml</code>.
</div>
<div class="code">
+<!-- Example connection factory for the example "Black Box" resource
+ adapter. This points at the same database as DefaultDS. -->
<mbean code="org.jboss.resource.ConnectionFactoryLoader"
- name="J2EE:service=ConnectionFactoryLoader">
+ name="JCA:service=ConnectionFactoryLoader,name=BlackBoxDS">
<attribute name="FactoryName">BlackBoxDS</attribute>
- <attribute name="RARDeployerName">J2EE:service=RARDeployer</attribute>
- <attribute name="ResourceAdapterName">Black Box XA Adapter</attribute>
- <attribute
name="Properties">XADataSourceName=java:/BlackBoxXADS</attribute>
+ <attribute name="RARDeployerName">JCA:service=RARDeployer</attribute>
+ <attribute name="ResourceAdapterName">Black Box LocalTx
Adapter</attribute>
+ <attribute name="Properties">
+ ConnectionURL=jdbc:HypersonicSQL:hsql://localhost:1476
+ </attribute>
+ <attribute
name="ConnectionManagerFactoryName">MinervaSharedLocalCMFactory</attribute>
+ <!-- See the documentation for the specific connection manager
+ implementation you are using for the properties you can set -->
+ <attribute name="ConnectionManagerProperties">
+ # Pool type - uncomment to force, otherwise it is the default
+ #PoolConfiguration=per-factory
+
+ # Connection pooling properties - see
+ # org.opentools.minerva.pool.PoolParameters
+ MinSize=0
+ MaxSize=10
+ Blocking=true
+ GCEnabled=false
+ IdleTimeoutEnabled=false
+ InvalidateOnError=false
+ TrackLastUsed=false
+ GCIntervalMillis=120000
+ GCMinIdleMillis=1200000
+ IdleTimeoutMillis=1800000
+ MaxIdleTimeoutPercent=1.0
+ </attribute>
+
<!-- Principal mapping configuration -->
- <attribute
name="PrincipalMappingClass">org.jboss.resource.security.ManyToOnePrincipalMapping</attribute>
+ <attribute name="PrincipalMappingClass"
+ >org.jboss.resource.security.ManyToOnePrincipalMapping</attribute>
<attribute name="PrincipalMappingProperties">
userName=sa
password=
</attribute>
-
- <!-- Pool strategy - uncomment to force, otherwise it is automatic
- <attribute name="PoolStrategy">Single</attribute>
- -->
-
- <!-- Connection pooling properties - see
- org.jboss.minerva.pools.ObjectPool -->
- <attribute name="MinSize">0</attribute>
- <attribute name="MaxSize">10</attribute>
- <attribute name="GCMinIdleTime">1200000</attribute>
- <attribute name="GCEnabled">false</attribute>
- <attribute name="InvalidateOnError">false</attribute>
- <attribute name="TimestampUsed">false</attribute>
- <attribute name="Blocking">true</attribute>
- <attribute name="GCInterval">120000</attribute>
- <attribute name="IdleTimeout">1800000</attribute>
- <attribute name="IdleTimeoutEnabled">false</attribute>
- <attribute name="LoggingEnabled">false</attribute>
- <attribute name="MaxIdleTimeoutPercent">1.0</attribute>
</mbean>
</div>
+ <div class="para">
+ Note that the connection manager we have chosen is the Minerva
+ local transaction connection manager. It is important to choose
+ the connection manager that matches the capabilities of the
+ resource adapter. This choice should be automated in the future.
+ </div>
+
<div class="para">
- The general attributes should be self explanatory.
+ Once <code>jboss.jcml</code> is set up with the desired
+ connection factory loaders, start JBoss and bring up the HTML
+ JMX connector which lives on port 8082 by default. If your
+ browser is running on the same box as JBoss then you can just go
+ to <a
+ href="http://localhost:8082">http://localhost:8082</a>. Then
+ find the <code>RARDeployer</code> MBean and invoke the
+ <code>deploy</code> operation, passing it the URL to the
+ resource adapter you want to deploy. In this case it is the path
+ to <code>blackbox-tx.rar</code> which you should save somewhere
+ local.
</div>
+ <div class="para">
+ Assuming that the deployment was successful, you should now have
+ a connection factory bound in JNDI at
+ <code>java:/BlackBoxDS</code> that you can use just like a
+ normal JDBC <code>DataSource</code>.
+ </div>
+
<h2><a name="status">Implementation Status</a></h2>
<div class="para">
@@ -314,20 +311,24 @@
<h3>Unimplemented Features</h3>
<ul>
- <li>Local transaction optimisation</li>
+ <li>Automatic connection manager selection based on resource
+ adapter capabilities.</li>
+
+ <li>Mapping to more than one resource principal per connection
+ factory.</li>
</ul>
<h3>Limitations</h3>
<ul>
<li>Transaction association doesn't work properly unless the
- transaction is started <strong>before</strong> the connection
- is obtained.</li>
+ transaction is started <strong>before</strong> the
+ connection is obtained.</li>
</ul>
<div class="footer">
Author: <a href="mailto:[EMAIL PROTECTED]">Toby Allsopp</a><br/>
- Revision: $Id: jca_config.html,v 1.4 2001/01/18 07:44:25 allsopp Exp $
+ Revision: $Id: jca_config.html,v 1.5 2001/02/04 07:50:14 allsopp Exp $
</div>
</div></body>
</html>
