JBossCX Configuration

Toby Allsopp


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.



Table 11.3. Terminology

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"

JBoss Configuration

There are two steps that must be performed to provide access to a connection factory in JBoss:

  1. Configure a connection factory in jboss.jcml

  2. Deploy the resource adapter

Connection Factory Configuration

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"
  <!-- General attributes -->
  <attribute name="name">value</attribute>

  <!-- Security attributes -->
  <attribute name="name">value</attribute>

Table 11.4. General Attributes

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

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.

Deploying the Resource Adapter

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.

Example - Minerva JDBC Resource Adapter

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"
  <attribute name="FactoryName">MinervaDS</attribute>
  <attribute name="RARDeployerName">JCA:service=RARDeployer</attribute>
  <attribute name="ResourceAdapterName">
    Minerva JDBC LocalTransaction ResourceAdapter
  <attribute name="Properties">

  <attribute name="ConnectionManagerFactoryName">
  <!-- 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

    # Connection pooling properties - see
    # org.opentools.minerva.pool.PoolParameters

  <!-- Principal mapping configuration -->
  <attribute name="PrincipalMappingClass">
  <attribute name="PrincipalMappingProperties">

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.

Implementation Status

See the JBossCX project page on jboss.org