| |
This section describes the configuration changes necessary in order to use a resource adapter conforming to the J2EE Connector Architecture (JCA) in your application.
The JCA specifies how J2EE application components can access resources other than those explicitly specified in the J2EE 1.2 specification. It will be part of the J2EE 1.3 specification. You can read more about the JCA at its official home page
JBossCX is the name of the JBoss module that provides RAR deployment and connects a resource adapter to a connection manager to create a connection factory accessible by application components through JNDI.
| Concept | Description |
|---|---|
| Resource | an external system that provides some service to application components. Examples include JDBC databases and mainframe systems |
| Resource adapter Connector | an application component that implements access to a resource |
| Resource instance | a particular configuration of a resource, e.g. an Oracle database running on machine "foo" at port "1234" |
| Connection factory | an object, available through JNDI, that provides access to connections to a particular resource instance |
| Connection manager | an object that implements the javax.resource.spi.ConnectionManager interface - provides connection pooling, transaction association, security and other "quality of services" |
There are two steps that must be performed to provide access to a connection factory in JBoss:
Connection factories are created by the ConnectionFactoryLoader MBean, so an <mbean> section must be added to jboss.jcml for each connection factory that is required. The format for this entry is as follows.
<mbean code="org.jboss.resource.ConnectionFactoryLoader"
name="JCA:service=ConnectionFactoryLoader,name=name">
<!-- General attributes -->
<attribute name="name">value</attribute>
<!-- Security attributes -->
<attribute name="name">value</attribute>
</mbean>
Table 11.4. General Attributes
| Name | Description |
|---|---|
| FactoryName | The name of the connection factory. This is the name under which the connection factory will be bound in JNDI |
| RARDeployerName | The name of the MBean that will deploy the resource adapter that this connection factory relates to |
| ResourceAdapterName | The name of the resource adapter for which this connection factory will create connections. This is the name given in the resource adapter's <display-name> deployment descriptor element |
| Properties | The properties to set on the resource adapter to configure it to connect to a particular resource instance. This is in java.util.Properties.load format (essentially one property per line, name=value) |
| ConnectionManagerFactoryName | The name of the connection manager factory to use. This is the name given in a previously defined ConnectionManagerFactoryLoader MBean. Currently there are two choices: MinervaSharedLocalCMFactory and MinervaXACMFactory. The former should be used for resource adapters that support local transactions and the latter for those that support XA transactions. |
| ConnectionManagerProperties | The properties (in java.util.Properties.load 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 jboss.jcml shows the possible properties for the Minerva connection managers |
Table 11.5. Security Attributes
| Name | Description |
|---|---|
| PrincipalMappingClass | The name of the class that maps from the principal on behalf of whom the application component method is executing to the principal that will be used for access to the resource. This class must implement the org.jboss.resource.security.PrincipalMapping interface. |
| PrincipalMappingProperties | The properties (in java.util.Properties.load format) to pass to the principal mapping implementation specified above. |
Currently the J2EE deployer does not recognise resource adapters, so it is not possible to deploy them as part of an EAR. This functionality will be added at a later date.
However, the AutoDeployer service is configured to automatically deploy resource adapters whose RAR files are placed in the deploy directory. So, to deploy a resource adapter, simply place the RAR file containing it into the deploy directory, just as you would for an ejb-jar file.
Included with JBoss are two resource adapters, part of the Minerva project, that implement JDBC DataSources. These resource adpaters are installed in the deploy/lib directory and are therefore deployed when JBoss starts up.
In this example we will use the local transaction version of the resource adapter, minerva-jdbc-1.0b3.rar. 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.
In order to make a connection factory from this resource adapter available to application components, we need to add the ConnectionFactoryLoader MBean that will create the connection factory from the resource adapter when it is deployed. We will create a connection factory called MinervaDS that will appear in JNDI at java:/BlackBoxDS. Below is the MBean definition that we will use (this is taken from the default jboss.jcml).
<!-- Connection factory for the Minerva JDBC resource adapter. This
points at the same database as DefaultDS. -->
<mbean code="org.jboss.resource.ConnectionFactoryLoader"
name="JCA:service=ConnectionFactoryLoader,name=MinervaDS">
<attribute name="FactoryName">MinervaDS</attribute>
<attribute name="RARDeployerName">JCA:service=RARDeployer</attribute>
<attribute name="ResourceAdapterName">
Minerva JDBC LocalTransaction ResourceAdapter
</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="PrincipalMappingProperties">
userName=sa
password=
</attribute>
</mbean>
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.
Once jboss.jcml is set up with the desired connection factory loaders, start JBoss and the connection factory java:/MinervaDS should be created.
Assuming that the deployment was successful, you should now have a connection factory bound in JNDI at java:/MinervaDS that you can use just like a normal JDBC DataSource.
 | |