An Overview of the JBossCX Architecture

The JBossCX framework provides the application server architecture extension required for the use of JCA resource adaptors. This is primarily a connection-pooling and management extension, and it includes a number of MBeans for loading resource adaptors into the JBoss server. Figure 7.3 expands the generic view given by Figure 7.2 to illustrate how the JBoss JCA layer implements the application server-specific extension, along with an example of a file system resource adaptor that is discussed later in this chapter.

Figure 7.3. The JBoss JCA implementation components.

Three coupled MBeans make up a RAR deployment: org.jboss.resource.RARDeployment, org.jboss.resource.connectionmanager.RARDeployment, and org.jboss.resource.connectionmanager.BaseConnectionManager2. org.jboss.resource.RARDeployment is simply an encapsulation of the metadata of a RAR META-INF/ra.xml descriptor. It exposes this information as a DynamicMBean simply to make it available to the org.jboss.resource.connectionmanager.RARDeployment MBean.

The RARDeployer service handles the deployment of archive files that contain resource adaptors (RARs). It creates the org.jboss.resource.RARDeployment MBean when a RAR file is deployed. Deploying the RAR file is the first step in making the resource adaptor available to application components. For each deployed RAR, one or more connection factories must be configured and bound into JNDI. You perform this task by using a JBoss service descriptor that sets up an org.jboss.resource.connectionmanager.BaseConnectionManager2 MBean implementation with an org.jboss.resource.connectionmgr.RARDeployment.

The BaseConnectionManager2 MBean

The org.jboss.resource.connectionmanager.BaseConnectionManager2 MBean is a base class for the various types of connection managers required by the JCA specification. Subclasses include NoTxConnectionManager, LocalTx-ConnectionManager, and XATxConnectionManager. These correspond to resource adaptors that support no transactions, local transactions, and XA transactions, respectively. You choose which subclass to use based on the type of transaction semantics you want, provided that the JCA resource adaptor supports the corresponding transaction capability.

The BaseConnectionManager2 MBean supports the following common attributes:

• ManagedConnectionPool This specifies the ObjectName of the MBean that represents the pool for this connection manager. The MBean must have a ManagedConnectionPool attribute that is an implementation of the org.jboss.resource.connectionmanager.ManagedConnectionPool interface. Normally, it will be an embedded MBean in a depends tag rather than an ObjectName reference to an existing MBean. The default MBean for use is the org.jboss.resource.connectionmanager.JBossManagedConnectionPool. Its configurable attributes are discussed later in this chapter.

• CachedConnectionManager This specifies the ObjectName of the CachedConnectionManager MBean implementation used by the connection manager. Normally, this will be specified using a depends tag with the ObjectName of the unique CachedConnectionManager for the server. The name jboss.jca:service=CachedConnectionManager is the standard setting to use.

• SecurityDomainJndiName This specifies the JNDI name of the security domain to use for authentication and authorization of resource connections. This is typically in the form java:/jaas/<domain>, where the <domain> value is the name of an entry in the conf/login-config.xml JAAS login module configuration file. This defines which JAAS login modules execute to perform authentication. Chapter 8, "Security on JBoss," provides more information on the security settings.

• JaasSecurityManagerService This is the ObjectName of the security manager service. You should set this to the security manager MBean name, as defined in the conf/jboss-service.xml descriptor, which currently is jboss.security:service=JaasSecurityManager. This attribute will likely be removed in the future.

The RARDeployment MBean

The org.jboss.resource.connectionmanager.RARDeployment MBean manages configuration and instantiation ManagedConnectionFactory instances. It does this by using the resource adaptor metadata settings from the RAR META-INF/ra.xml descriptor, along with the RARDeployment attributes. These are the configurable attributes:

• OldRarDeployment This is the ObjectName of the org.jboss.resource.RarDeployment MBean that contains the resource adaptor metadata. The form of this name is jboss.jca:service=RARDeployment,name= <ra-display-name>, where the <ra-display-name> is the ra.xml descriptor display-name attribute value. RARDeployer creates this when it deploys a RAR file. This attribute will likely be removed in the future.

• ManagedConenctionFactoryProperties This is a collection of (name, type, value) triples that define attributes of the ManagedConnectionFactory instance. Therefore, the names of the attributes depend on the resource adaptor ManagedConnectionFactory instance. The following example shows the structure of the content of this attribute:

   <properties>     <config-property>         <config-property-name>Attr0Name</config-property-name>         <config-property-type>Attr0Type</config-property-type>         <config-property-value>Attr0Value</config-property-value>     </config-property>     <config-property>         <config-property-name>Attr1Name</config-property-name>         <config-property-type>Attr2Type</config-property-type>         <config-property-value>Attr2Value</config-property-value>     </config-property>     ... </properties> 

  
  

  AttrXName is the Xth attribute name, AttrXType is the fully qualified Java type of the attribute, and AttrXValue is the string representation of the value. The conversion from string to AttrXType is done using the java.beans.PropertyEditor class for the AttrXType.

• JndiName This is the JNDI name under which the resource will be made available. Clients of the resource adaptor use this name to obtain either the javax.resource.cci.ConnectionFactory or resource adaptor-specific connection factory. The full JNDI name will be java:/<JndiName>, meaning that the JndiName attribute value will be prefixed with java:/. This prevents use of the connection factory outside the JBoss server VM. In the future this restriction may be configurable.

The JBossManagedConnectionPool MBean

The org.jboss.resource.connectionmanager.JBossManagedConnectionPool MBean is a connection-pooling MBean. It is typically used as the embedded MBean value of the BaseConnectionManager2 ManagedConnectionPool attribute. When you set up a connection manager MBean, you typically embed the pool configuration in the connection manager descriptor. The following are the configurable attributes of JBossManagedConnectionPool:

• ManagedConnectionFactoryName This specifies the ObjectName of the MBean that creates javax.resource.spi.ManagedConnectionFactory instances. Normally, you configure this as an embedded MBean in a depends element rather than as a separate MBean reference, using the RARDeployment MBean. The MBean must provide an appropriate startManagedConnectionFactory operation.

• MinSize This attribute indicates the minimum number of connections this pool should hold. These connections are not created until a Subject is known from a request for a connection. MinSize connections will be created for each sub-pool.

• MaxSize This attribute indicates the maximum number of connections for a pool. No more than MaxSize connections will be created in each sub-pool.

• BlockingTimeoutMillis This attribute indicates the maximum time 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 it will never throw an exception if creating a new connection takes an inordinately long time.

• IdleTimeoutMinutes This attribute indicates the maximum time a connection may be idle before being closed. The actual maximum time also depends on the idle remover thread scan time, which is half the smallest idle timeout of any pool.

• NoTxSeparatePools Setting this to TRue doubles the available pools. One pool is for connections used outside a transaction, and the other is for connections inside a transaction. The actual pools are lazily constructed on first use. This is relevant only when setting the pool parameters associated with the LocalTxConnectionManager and XATxConnectionManager. Its 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.

• Criteria This attribute indicates whether the JAAS javax.security.auth.Subject from the security domain associated with the connection or application-supplied parameters (such as from getConnection(user,pw)) are used to distinguish connections in the pool. These are the allowed values:

  • ByContainer Use Subject.

  • ByApplication Use application-supplied parameters only.

  • ByContainerAndApplication Use both.

  • ByNothing All connections are equivalent, which is usually the case if an adapter supports re-authentication.

The CachedConnectionManager MBean

The org.jboss.resource.connectionmanager.CachedConnectionManager MBean manages associations between meta-aware objects (those accessed through interceptor chains) and connection handles, as well as between user transactions and connection handles. Normally there should be only one such MBean, and this is configured in the core jboss-service.xml descriptor. It is used by CachedConnectionInterceptor, the JTA UserTransaction implementation, and all BaseConnectionManager2 instances. These are the configurable attributes of the CachedConnectionManager MBean:

• SpecCompliant You enable this Boolean attribute for reconnect processing of specification-compliant non-shareable connections. This allows a connection to be opened in one call and used in another. Note that specifying this behavior disables connection close processing.

• Debug You enable this Boolean property for connection close processing. At the completion of an EJB method invocation, unclosed connections are registered with a transaction synchronization. If the transaction ends without the connection being closed, an error is reported, and JBoss closes the connection. This is a development feature that should be turned off in production for optimal performance.

• TRansactionManagerServiceName This attribute specifies the JMX ObjectName of the JTA transaction manager service. Connection close processing is now synchronized with the transaction manager, and this attribute specifies the transaction manager to use.

A Sample Skeleton of a JCA Resource Adaptor

To conclude our discussion of the JBoss JCA framework, let's create and deploy a single non-transacted resource adaptor that simply provides a skeleton implementation that stubs out the required interfaces and logs all method calls. This section does not discuss the details of the requirements of a resource adaptor provider because they are discussed in detail in the JCA specification. The purposes of the adaptor are to demonstrate the steps required to create and deploy a RAR in JBoss and to show how JBoss interacts with the adaptor.

The adaptor described in this section could be used as the starting point for a non-transacted file system adaptor. You can find the source for the example adaptor in the src/main/org/jboss/chap7/ex1 directory of the book examples. Figure 7.4 shows a class diagram of the mapping from the required javax.resource.spi interfaces to the resource adaptor implementation.

Figure 7.4. The file system RAR class diagram.

In this section you will build the adaptor, deploy it to the JBoss server, and then run an example of the client against an EJB that uses the resource adaptor to demonstrate the basic steps in a complete context. You'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, you need to execute the following Ant command in the book examples directory:

 [examples]$ ant -Dchap=chap7 build-chap 

The deployed files include a chap7-ex1.sar file and a notxfs-service.xml service descriptor. Listing 7.1 shows an example of the resource adaptor deployment descriptor.

Listing 7.1. A Non-transactional File System Resource Adaptor Deployment Descriptor

 <?xml version="1.0" encoding="UTF-8"?> <connector xmlns="http://java.sun.com/xml/ns/j2ee"     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"     xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee                         http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd" version="1.5">     <display-name>File System Adapter</display-name>     <vendor-name>JBoss</vendor-name>     <eis-type>FileSystem</eis-type>     <resourceadapter-version>1.0</resourceadapter-version>     <license>         <description>LGPL</description>         <license-required>false</license-required>     </license>     <resourceadapter>         <resourceadapter-class>             org.jboss.resource.deployment.DummyResourceAdapter         </resourceadapter-class>         <outbound-resourceadapter>             <connection-definition>                 <managedconnectionfactory-class>                     org.jboss.chap7.ex1.ra.FSManagedConnectionFactory                 </managedconnectionfactory-class>                 <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>                 <config-property>                    <config-property-name>Password</config-property-name>                    <config-property-type>java.lang.String</config-property-type>                    <config-property-value/>                 </config-property>                 <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>             </connection-definition>             <transaction-support>NoTransaction</transaction-support>             <authentication-mechanism>                 <authentication-mechanism-type>BasicPassword</authentication-mechanism-type>                 <credential-interface>                     javax.resource.spi.security.PasswordCredential                 </credential-interface>             </authentication-mechanism>             <reauthentication-support>true</reauthentication-support>         </outbound-resourceadapter>         <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> 

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

• managedconnectionfactory-class This is the implementation of the ManagedConnectionFactory interface, org.jboss.chap7.ex1.ra.FSManagedConnectionFactory.

• connectionfactory-interface This is the interface that clients will obtain when they look up the connection factory instance from JNDI, which in this case is a proprietary resource adaptor value, org.jboss.chap7.ex1.ra.DirContextFactory. This value will be needed when you create the JBoss ds.xml to use the resource.

• connectionfactory-impl-class This is the class that provides the implementation of connectionfactoryinterface, org.jboss.chap7.ex1.ra.DirContextFactoryImpl.

• connection-interface This is the interface for the connections returned by the resource adaptor connection factory, which in this case is the JNDI javax.naming.directory.DirContext interface.

• connection-impl-class This is the class that provides the connection-interface implementation, org.jboss.chap7.ex1.ra.FSDirContext.

• transaction-support This is the level of transaction support, which in this case is defined as NoTransaction, meaning the file system resource adaptor does not do transactional work.

The RAR classes and deployment descriptor define only a resource adaptor. Before you can use the resource adaptor, it must be integrated into the JBoss application server, using a ds.xml descriptor file. An example of this file for the file system adaptor is shown in Listing 7.2.

Listing 7.2. The notxfs-ds.xml Resource Adaptor MBeans Service Descriptor

 <!DOCTYPE connection-factories PUBLIC           "-//JBoss//DTD JBOSS JCA Config 1.5//EN"           "http://www.jboss.org/j2ee/dtd/jboss-ds_1_5.dtd"> <!--        The non-transaction FileSystem resource adaptor service configuration --> <connection-factories>     <no-tx-connection-factory>         <jndi-name>NoTransFS</jndi-name>         <rar-name>chap7-ex1.rar</rar-name>         <connection-definition>              org.jboss.chap7.ex1.ra.DirContextFactory         </connection-definition>         <config-property name="FileSystemRootDir"                          type="java.lang.String">/tmp/db/fs_store</config-property>     </no-tx-connection-factory> </connection-factories> 

The main attributes are as follows:

• jndi-name This specifies where the connection factory will be bound into JNDI. For this deployment, that binding will be java:/NoTransFS.

• rar-name This is the name of the RAR file that contains the definition for the resource you want to provide. For nested RAR files, the name would look like myapplication.ear#my.rar. In this example, it is simply chap7-ex1.rar.

• connection-definition This is the connection factory interface class. It should match the connectionfactory-interface in the ra.xml file. In this case, the connection factory interface is org.jboss.chap7.ex1.ra.DirContextFactory.

• config-property This can be used to provide non-default settings to the resource adaptor connection factory. In this case, the FileSystemRootDir is being set to /tmp/db/fs_store. This overrides the default value in the ra.xml file.

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

 [examples]$ ant -Dchap=chap7 config 

The server console will display some logging output, indicating that the resource adaptor has been deployed.

Now you need to test access of the resource adaptor by a J2EE component. To do this, you can create a trivial stateless session bean that has a single method called echo. Inside 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 Listing 7.3.

Listing 7.3. The Stateless Session Bean echo Method Code That Shows the Access of the Resource Adaptor Connection Factory

 public String echo(String arg) {     log.info("echo, arg="+arg);     try {         InitialContext ctx = new InitialContext();         Object         ref = ctx.lookup("java:comp/env/ra/DirContextFactory");         log.info("echo, ra/DirContextFactory=" + ref);         DirContextFactory dcf = (DirContextFactory) ref;         log.info("echo, found dcf=" + dcf);         DirContext dc = dcf.getConnection();         log.info("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 EJB in the example 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 that would only exercise the resource adaptor implementation because this is a non-transactional resource.

You run the test client, which calls the EchoBean.echo method, by running Ant as follows from the examples directory:

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

You'll see some output from the bean in the system console, but you can find much more detailed logging output in the server/default/log/server.log file. Don't worry if you see exceptions. They are just stack traces to highlight the call path into parts of the adaptor.

To help understand the interaction between the adaptor and the JBoss JCA layer, the sequence diagram shown in Figure 7.5 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 that illustrates how 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, which are as follows.:

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 JBossManagedConnection-Pool$BasePool gets the key for the connection and then asks the matching InternalPool for a connection.
1.1.1.1.1.	Because 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 ConnectionFactory 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 because that 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 that its interaction with the resource manager is complete.

This concludes the resource adaptor example. This 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 adaptor in this example 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.