CHAPTER 7 Connectors on JBoss - The JCA Configuration and Architecture

 

FIGURE 7-4. The file system RAR class diagram

We will build the adaptor, deploy it to the JBoss server and then run an example client against an EJB that uses the resource adaptor to demonstrate the basic steps in a complete context. We'll then take a look at the JBoss server log to see how the JBoss JCA framework interacts with the resource adaptor to help you better understand the components in the JCA system level contract.

To build the example and deploy the RAR to the JBoss server deploy/lib directory, execute the following ant command in the book examples directory:

[nr@toki]$ ant -Dchap=chap7 build-chap

Buildfile: build.xml

...

prepare:

[mkdir] Created dir: /Users/orb/Desktop/jboss/docs323/examples/output/chap7

 

chap7-ex1-rar:

[jar] Building jar: /Users/orb/Desktop/jboss/docs323/examples/output/chap7/ra.jar

[jar] Building jar: /Users/orb/Desktop/jboss/docs323/examples/output/chap7/chap7-ex1.rar

 

prepare:

 

chap7-ex1-jar:

[jar] Building jar: /Users/orb/Desktop/jboss/docs323/examples/output/chap7/chap7-ex1.jar

BUILD SUCCESSFUL

Total time: 6 seconds

The deployed files include a chap7-ex1.sar and a notxfs-service.xml service descriptor. The example resource adaptor deployment descriptor is shown in See The nontransactional file system resource adaptor deployment descriptor.. while the connection manager MBeans service descriptor is shown in See The notxfs-ds.xml resource adaptor MBeans service descriptor...

1. The nontransactional file system resource adaptor deployment descriptor.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE connector PUBLIC

"-//Sun Microsystems, Inc.//DTD Connector 1.0//EN"

"http://java.sun.com/dtd/connector_1_0.dtd">

<connector>

<display-name>File System Adapter</display-name>

<vendor-name>JBoss Group</vendor-name>

<spec-version>1.0</spec-version>

<version>1.0</version>

<eis-type>FileSystem</eis-type>

<license>

<description>LGPL</description>

<license-required>false</license-required>

</license>

<resourceadapter>

<managedconnectionfactory-class>org.jboss.chap7.ex1.ra.FSMangedConnectionFactory

</managedconnectionfactory-class>

<connectionfactory-interface>org.jboss.chap7.ex1.ra.DirContextFactory

</connectionfactory-interface>

<connectionfactory-impl-class>org.jboss.chap7.ex1.ra.DirContextFactoryImpl

</connectionfactory-impl-class>

<connection-interface>javax.naming.directory.DirContext

</connection-interface>

<connection-impl-class>org.jboss.chap7.ex1.ra.FSDirContext

</connection-impl-class>

<transaction-support>NoTransaction</transaction-support>

<config-property>

<config-property-name>FileSystemRootDir</config-property-name>

<config-property-type>java.lang.String</config-property-type>

<config-property-value>/tmp/db/fs_store</config-property-value>

</config-property>

<config-property>

<config-property-name>UserName</config-property-name>

<config-property-type>java.lang.String</config-property-type>

<config-property-value></config-property-value>

</config-property>

<config-property>

<config-property-name>Password</config-property-name>

<config-property-type>java.lang.String</config-property-type>

<config-property-value></config-property-value>

</config-property>

<authentication-mechanism>

<authentication-mechanism-type>BasicPassword</authentication-mechanism-type>

<credential-interface>javax.resource.security.PasswordCredential</credential-interface>

</authentication-mechanism>

<reauthentication-support>true</reauthentication-support>

<security-permission>

<description>Read/Write access is required to the contents of

the FileSystemRootDir</description>

<security-permission-spec>permission java.io.FilePermission

"/tmp/db/fs_store/*", "read,write";</security-permission-spec>

</security-permission>

</resourceadapter>

</connector>

1. The notxfs-ds.xml resource adaptor MBeans service descriptor.

<!-- The non-transaction FileSystem resource adaptor service configuration

-->

<connection-factories>

<no-tx-connection-factory>

<jndi-name>NoTransFS</jndi-name>

<adapter-display-name>File System Adapter</adapter-display-name>

<config-property name="FileSystemRootDir"

type="java.lang.String">/tmp/db/fs_store</config-property>

</no-tx-connection-factory>

</connection-factories>

The key items in the resource adaptor deployment descriptor are highlighted in bold. These define the classes of the resource adaptor, and the elements are:

• : Recall from our discussion of the connection manager factory MBeans that the association between the factory and the resource adaptor classes was done via a RARDeployment DynamicMBean located by name. The name was based on the display-name value found in the ra.xml descriptor. Here the name is "File System Adaptor" and we will use it in the connection manager service descriptor.
• : The implementation of the javax.resource.spi.ManagedConnectionFactory interface, org.jboss.chap7.ex1.ra.FSMangedConnectionFactory
• : The interface that clients will obtain when they lookup the connection factory instance from JNDI, here a proprietary resource adaptor value, org.jboss.chap7.ex1.ra.DirContextFactor y
• : The class that provides the implementation of the connectionfactory-interface, org.jboss.chap7.ex1.ra.DirContextFactoryImpl
• : The interface for the connections returned by the resource adpator connection factory, here the JNDI javax.naming.directory.DirContext interface.
• : The class that provides the connection-interface implementation, org.jboss.chap7.ex1.ra.FSDirContext
• : The level of transaction support, here defined as NoTransaction, meaning the file system resource adaptor does not do transactional work.

See the JCA 1.0 spec, or the book "J2EE Connector Architecture and Enterprise Application Integration" by Sharma, Stearns and Ng for the full details of the ra.xml descriptor elements.

The RAR classes and deployment descriptor only define a resource adaptor. To use the resource adaptor it must be integrated into the JBoss application server. As we have discussed this is done with a connection factory MBeans. As of 3.2, a simplified descriptor format is available for configuring the JCA services of the application server, and this is described below in Configuring Generic JCA Adaptors. The notxfs-ds.xml descriptor shown in See The notxfs-ds.xml resource adaptor MBeans service descriptor.., and the following notes apply.

• The jndi-name element is used to specify where the connection factory will be bound into JNDI. For this deployment that binding will be "java:/NoTransFS".
• The adapter-display-name element specifies the same value as the ra.xml display-name element. This is how the JCA layer knows how to associate which RAR which this connection factory configuration.
• ManagedConnectionFactoryProperties may be specified using config-property elements to provide non-default settings to the resource adaptor connection factory. Here the FileSystemRootDir of type java.lang.String attribute is being set to "/tmp/db/fs_store".

To deploy the RAR and connection manager configuration to the JBoss server, run the following:

[nr@toki examples]$ ant -Dchap=chap7 config

Buildfile: build.xml

...

config:

[copy] Copying 1 file to /tmp/jboss-3.2.3/server/default/deploy

[copy] Copying 1 file to /tmp/jboss-3.2.3/server/default/deploy

 

BUILD SUCCESSFUL

Total time: 1 second

The server console will display the following:

01:11:30,945 INFO [MainDeployer] Starting deployment of package: file:/private/tmp/jboss-3.2.3/server/default/deploy/chap7-ex1.rar

01:11:31,374 INFO [RARMetaData] License terms present. See deployment descriptor.

01:11:31,448 INFO [RARDeployer] nested deployment: file:/private/tmp/jboss-3.2.3/server/default/tmp/deploy/tmp35575chap7-ex1.rar-contents/ra.jar

01:11:31,496 INFO [MainDeployer] Deployed package: file:/private/tmp/jboss-3.2.3/server/default/deploy/chap7-ex1.rar

01:11:31,502 INFO [MainDeployer] Starting deployment of package: file:/private/tmp/jboss-3.2.3/server/default/deploy/notxfs-ds.xml

01:11:31,783 INFO [RARDeployment] Started jboss.jca:service=ManagedConnectionFactory,name=NoTransFS

01:11:31,792 INFO [JBossManagedConnectionPool] Started jboss.jca:service=ManagedConnectionPool,name=NoTransFS

01:11:31,848 INFO [NoTransFS] Bound connection factory for resource adapter for ConnectionManager 'jboss.jca:service=NoTxCM,name=NoTransFS to JNDI name 'java:/NoTransFS'

01:11:31,852 INFO [NoTxConnectionManager] Started jboss.jca:service=NoTxCM,name=NoTransFS

01:11:31,862 INFO [MainDeployer] Deployed package: file:/private/tmp/jboss-3.2.3/server/default/deploy/notxfs-ds.xml

This indicates that the resource adaptor has been successfully deployed and its connection factory has been bound into JNDI under the name "java:/NoTransFS". You can ignore the warning messages about the RARDeployment MBeans not implementing any Service methods. Its fine as they are not used as JBoss services, just standard MBeans.

Now we want to test access of the resource adaptor by a J2EE component. To do this we have created a trivial stateless session bean that has a single method called echo . Inside of the echo method the EJB accesses the resource adaptor connection factory, creates a connection, and then immediately closes the connection. The echo method code is shown in See The stateless session bean echo method code which shows the access of the resource adaptor connection factory...

1. The stateless session bean echo method code which shows the access of the resource adaptor connection factory.

public String echo(String arg)

{

log.debug("echo, arg="+arg);

try

{

InitialContext iniCtx = new InitialContext();

Context enc = (Context) iniCtx.lookup("java:comp/env");

Object ref = enc.lookup("ra/DirContextFactory");

log.debug("echo, ra/DirContextFactory="+ref);

DirContextFactory dcf = (DirContextFactory) ref;

log.debug("echo, found dcf="+dcf);

DirContext dc = dcf.getConnection();

log.debug("echo, lookup dc="+dc);

dc.close();

}

catch(NamingException e)

{

log.error("Failed during JNDI access", e);

}

return arg;

}

The EJB is not using the CCI interface to access the resource adaptor. Rather, it is using the resource adaptor specific API based on the proprietary DirContextFactory interface that returns a JNDI DirContext object as the connection object. The example EJB is simply exercising the system contract layer by looking up the resource adaptor connection factory, creating a connection to the resource and closing the connection. The EJB does not actually do anything with the connection, as this would only exercise the resource adaptor implementation since this is a non-transactional resource.

Run the test client which calls the EchoBean.echo method by running ant as follows from the examples directory:

[nr@toki examples]$ ant -Dchap=chap7 -Dex=1 run-example

Buildfile: build.xml

...

run-example1:

[copy] Copying 1 file to /tmp/jboss-3.2.3/server/default/deploy

[echo] Waiting for deploy...

[java] Created Echo

[java] Echo.echo('Hello') = Hello

 

BUILD SUCCESSFUL

Total time: 8 seconds

Now let's look at the output that has been logged by the resource adaptor to understand the interaction between the adaptor and the JBoss JCA layer. The output is in the server/default/log/server.log file of the JBoss server distribution. We'll summarize the events seen in the log using a sequence diagram.

Those are the steps involved with making the resource adaptor connection factory available to application server components. The remaining log messages are the result of the example client invoking the EchoBean.echo method and this method's interaction with the resource adaptor connection factory. See A sequence diagram illustrating the key interactions between the JBossCX framework and the example resource adaptor that result when the EchoBean accesses the resource adaptor connection factory.. is a sequence diagram that summarizes the events that occur when the EchoBean accesses the resource adaptor connection factory from JNDI and creates a connection.

FIGURE 7-5. A sequence diagram illustrating the key interactions between the JBossCX framework and the example resource adaptor that result when the EchoBean accesses the resource adaptor connection factory.

The starting point is the client's invocation of the EchoBean.echo method. For the sake of conciseness of the diagram, the client is shown directly invoking the EchoBean.echo method when in reality the JBoss EJB container handles the invocation. There are three distinct interactions between the EchoBean and the resource adaptor; the lookup of the connection factory, the creation of a connection, and the close of the connection.

The lookup of the resource adaptor connection factory is illustrated by the 1.1 sequences of events. The events are:

• 1, the echo method invokes the getConnection method on the resource adaptor connection factory obtained from the JNDI lookup on the "java:comp/env/ra/DirContextFactory" name which is a link to the "java:/NoTransFS" location.
• 1.1, the DirContextFactoryImpl class asks its associated ConnectionManager to allocate a connection. It passes in the ManagedConnectionFactory and FSRequestInfo that were associated with the DirContextFactoryImpl during its construction.
• 1.1.1, the ConnectionManager invokes its getManagedConnection method with the current Subject and FSRequestInfo .
• 1.1.1.1, the ConnectionManager asks its object pool for a connection object. The JBossManagedConnectionPool$BasePool is get the key for the connection and then asks the matching InternalPool for a connection.
• 1.1.1.1.1, Since no connections have been created the pool must create a new connection. This is done by requesting a new managed connection from the ManagedConnectionFactory . The Subject associated with the pool as well as the FSRequestInfo data are passed as arguments to the createManagedConnection method invocation.
• 1.1.1.1.1.1, the FSManagedConnectionFactory creates a new FSManagedConnection instance and passes in the Subject and FSRequestInfo data.
• 1.1.1.2, a javax.resource.spi.ConnectionListener instance is created. The type of listener created is based on the type of ConnectionManager. In this case it is an org.jboss.resource.connectionmgr.BaseConnectionManager2$NoTransactionListener instance.
• 1.1.1.2.1, the listener registers as a javax.resource.spi.ConnectionEventListener with the ManagedConnection instance created in 1.2.1.1.
• 1.1.2, the ManagedConnection is asked for the underlying resource manager connection. The Subject and FSRequestInfo data are passed as arguments to the getConnection method invocation.
• The resulting connection object is cast to a javax.naming.directory.DirContext instance since this is the public interface defined by the resource adaptor.
• After the EchoBean has obtained the DirContext for the resource adaptor, it simply closes the connection to indicate its interaction with the resource manager is complete.

This concludes the resource adaptor example. Our investigation into the interaction between the JBossCX layer and a trivial resource adaptor should give you sufficient understanding of the steps required to configure any resource adaptor. The example adaptor can also serve as a starting point for the creation of your own custom resource adaptors if you need to integrate non-JDBC resources into the JBoss server environment.

FIGURE 7-6. The simplified JCA DataSource configuration descriptor top-level schema elements

Multiple datasource configurations may be specified in a configuration deployment file. The child elements of the datasources root are:

• mbean: Any number mbean elements may be specified to define MBean services that should be included in the jboss-service.xml descriptor that results from the transformation. This may be used to configure services used by the datasources.
• no-tx-datasource: this element is used to specify the org.jboss.resource.connectionmanager.NoTxConnectionManager service configuration. NoTxConnectionManager is a JCA connection manager with no transaction support. The no-tx-datasource child element schema is given in See The non-transactional DataSource configuration schema..
• local-tx-datasource: this element is used to specify the org.jboss.resource.connectionmanager.LocalTxConnectionManager service configuration. LocalTxConnectionManager implements a ConnectionEventListener that implements XAResource to manage transactions through the transaction manager. To ensure that all work in a local transaction occurs over the same ManagedConnection , it includes a xid to ManagedConnection map. When a Connection is requested or a transaction started with a connection handle in use, it checks to see if a ManagedConnection already exists enrolled in the global transaction and uses it if found. Otherwise, a free ManagedConnection has its LocalTransaction started and is used. The local-tx-datasource child element schema is given in See The non-XA DataSource configuration schema..
• xa-datasource: this element is used to specify the org.jboss.resource.connectionmanager.XATxConnectionManager service configuration. XATxConnectionManager implements a ConnectionEventListener that obtains the XAResource to manage transactions through the transaction manager from the adaptor ManagedConnection . To ensure that all work in a local transaction occurs over the same ManagedConnection , it includes a xid to ManagedConnection map. When a Connection is requested or a transaction started with a connection handle in use, it checks to see if a ManagedConnection already exists enrolled in the global transaction and uses it if found. Otherwise, a free ManagedConnection has its LocalTransaction started and is used. The xa-datasource child element schema is given in See The XADataSource configuration schema..

 

FIGURE 7-7. The non-transactional DataSource configuration schema

 

FIGURE 7-8. The non-XA DataSource configuration schema

 

FIGURE 7-9. The XADataSource configuration schema

Elements that are common to all datasources include:

• jndi-name: The JNDI name under which the DataSource wrapper will be bound. Note that this name is relative to the "java:/" prefix. The full JNDI name of the DataSource will be "java:/" + jndi-name. DataSource wrappers are bound under the "java:/" prefix since they are not usable outside of the server VM.
• application-managed-security: Specifying this element indicates that application code supplied parameters, such as from getConnection(user, pw), are used to distinguish connections in the pool.
• security-domain: Specifying this element indicates that either application code supplied parameters, or JAAS Subject based information is to distinguish connections in the pool. The content of the security-domain is the name of the JAAS security manager that will handle authentication. This name correlates to the JAAS login-config.xml descriptor application-policy/name attribute.
• min-pool-size: This element specifies the minimum number of connections a pool should hold. These pool instances are not created until an initial request for a connection is made. This default to 0.
• max-pool-size: This element specifies the maximum number of connections for a pool. No more than the max-pool-size number of connections will be created in a pool. This defaults to 20.
• blocking-timeout-millis: This element specifies the maximum time in milliseconds to block while waiting for a connection before throwing an exception. Note that this blocks only while waiting for a permit for a connection, and will never throw an exception if creating a new connection takes an inordinately long time. The default is 5000.
• idle-timeout-minutes: This element specifies the maximum time in minutes a connection may be idle before being closed. The actual maximum time depends also on the IdleRemover scan time, which is 1/2 the smallest idle-timeout-minutes of any pool.
• depends: The depends element specifies the JMX ObjectName string of a service that the connection manager services depend on. The connection manager service will not be started until the dependent services have been started.

Additional common child elements for both no-tx-datasource and local-tx-datasource include:

• connection-url: The JDBC driver connection URL string, for example, "jdbc:hsqldb:hsql://localhost:1701".
• driver-class: The fully qualified name of the JDBC driver class, for example, "org.hsqldb.jdbcDriver".
• connection-property: The connection-property element allows you to pass in arbitrary connection properties to the java.sql.Driver.connect(url, props) method. Each connection-property specifies a string name/value pair with the property name coming from the name attribute and the value coming from the element content.
• user-name: This element specifies the default username used when creating a new connection. The actual username may be overridden by the application code getConnection parameters or the connection creation context JAAS Subject .
• password: This element specifies the default password used when creating a new connection. The actual password may be overridden by the application code getConnection parameters or the connection creation context JAAS Subject .

Elements in common to the local-tx-datasource and xa-datasource are:

• transaction-isolation: This element specifies the java.sql.Connection transaction isolation level to use. The constants defined in the Connection interface are the possible element content values and include:
• TRANSACTION_READ_UNCOMMITTED
• TRANSACTION_READ_COMMITTED
• TRANSACTION_REPEATABLE_READ
• TRANSACTION_SERIALIZABLE
• TRANSACTION_NONE
• new-connection-sql: A SQL statement that should be executed when a new connection is created. This can be used to configure a connection with database specific settings not configurable via connection properties.
• check-valid-connection-sql: A SQL statement that should be run on a connection before it is returned from the pool to test its validity. This allows for the dection of stale pool connections. An example statement could be "select count(*) from x".
• exception-sorter-class-name: This specifies a class that implements the org.jboss.resource.adapter.jdbc.ExceptionSorter interface to filter SQLExceptions as to whether or not a connection error event should be generated. Current implementations include:
• org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter
• org.jboss.resource.adapter.jdbc.vendor.SybaseExceptionSorter
• valid-connection-checker-class-name: This specifies a class that implements the org.jboss.resource.adapter.jdbc.ValidConnectionChecker interface to provide a SQLException isValidConnection(Connection e) method that is called with a connection that is to be returned from the pool to test its validity. This overrides the check-valid-connection-sql when present. Current implementations include:
• org.jboss.resource.adapter.jdbc.vendor.OracleValidConnectionChecker
• track-statements: This boolean element specifies whether to check for unclosed statements when a connection is returned to the pool. If true, a warning message is issued for each unclosed statement. If the log4j category org.jboss.resource.adapter.jdbc.WrappedConnection has trace level enabled, a stack trace of the connection close call is logged as well. This is a debug feature that can be turned off in production.
• prepared-statement-cache-size: This element specifies the number of prepared statements per connection in an LRU cache which is keyed by the sql query. Setting this to zero disables the cache.

The unique xa-datasource child elements are:

• track-connection-by-tx: Specifying a true value for this element makes the connection manager keep an xid to connection map and only put the connection back in the pool when the transaction completes and all the connection handles are closed or disassociated (by the method calls returning). As a side effect, we never suspend and resume the xid on the connection's XAResource . This is the same connection tracking behavior used for local transactions.

The XA spec implies that any connection may be enrolled in any transaction using any xid for that transaction at any time from any thread (suspending other transactions if necessary). The original JCA implementation assumed this and aggressively delisted connections and put them back in the pool as soon as control left the ejb they were used in or handles were closed. Since some other transaction could be using the connection the next time work needed to be done on the original transaction, there is no way to get the original connection back. It turns out that most XADataSource driver vendors do not support this, and require that all work done under a particular xid go through the same connection.

• xa-datasource-class: The fully qualified name of the javax.sql.XADataSource implementation class, for example, "com.informix.jdbcx.IfxXADataSource".
• xa-datasource-property: The xa-datasource-property element allows for specification of the properties to assign to the XADataSource implementation class. Each property is identified by the name attribute and the property value is given by the xa-datasource-property element content. The property is mapped onto the XADataSource implementation by looking for a JavaBeans style getter method for the property name. If found, the value of the property is set using the JavaBeans setter with the element text translated to the true property type using the java.beans.PropertyEditor for the type.
• isSameRM-override-value: A boolean flag that allows one to override the behavior of the javax.transaction.xa.XAResource.isSameRM(XAResource xaRes) method behavior on the XA managed connection. If specified, this value is used unconditionally as the isSameRM(xaRes) return value regardless of the xaRes parameter.
• no-tx-seperate-pools: The precense of this element indicates that two connection pools are required to isolate connections used with JTA transaction from thoses used without a JTA transaction. The pools are lazily constructed on first use. It's use case is for Oracle (and possibly other vendors) XA implementations that don't like using an XA connection with and without a JTA transaction.

FIGURE 7-10. The simplified JCA adaptor connection factory configuration descriptor top-level schema elements

Multiple connection factory configurations may be specified in a configuration deployment file. The child elements of the connection-factories root are:

• mbean: Any number mbean elements may be specified to define MBean services that should be included in the jboss-service.xml descriptor that results from the transformation. This may be used to configure services used by the adaptor.
• no-tx-connection-factory: this element is used to specify the org.jboss.resource.connectionmanager.NoTxConnectionManager service configuration. NoTxConnectionManager is a JCA connection manager with no transaction support. The no-tx-connection-factory child element schema is given in See The no-tx-connection-factory element schema..
• tx-connection-factory: this element is used to specify the org.jboss.resource.connectionmanager.TxConnectionManager service configuration. The tx-connection-factory child element schema is given in See The tx-connection-factory element schema..

 

FIGURE 7-11. The no-tx-connection-factory element schema

 

FIGURE 7-12. The tx-connection-factory element schema

The majority of the elements are the same as those of the datasources configuration. The element unique to the connection factory configuration include:

• adaptor-display-name: A human readable display name to assign to the connection manager MBean.
• config-property: Any number of properties to supply to the ManagedConnectionFactory (MCF) MBean service configuration. Each config-property element specifies the value of a MCF property. The config-property element has two required attributes:
• name: The name of the property
• type: The fully qualified type of the property

The content of the config-property element provides the string representation of the property value. This will be converted to the true property type using the associated type PropertyEditor .

• local-transaction | xa-transaction: These element specify whether the tx-connection-factory supports local transaction or XA transactions.