This chapter discusses the JBoss server implementation of the J2EE Connector Architecture (JCA). JCA is a resource manager integration API whose goal is to standardize access to non-relational resources in the same way the JDBC API standardized access to relational data. The purpose of this chapter is to introduce the utility of the JCA APIs and then describe the architecture of JCA in JBoss
J2EE 1.3 contains a connector architecture (JCA) specification that allows for the integration of transacted and secure resource adaptors into a J2EE application server environment. The full JCA specification is available from the JCA home page, http://java.sun.com/j2ee/connector/. The JCA specification describes the notion of such resource managers as Enterprise Information Systems (EIS). Examples of EIS systems include enterprise resource planning packages, mainframe transaction processing, non-Java legacy applications, etc.
The reason for focusing on EIS is primarily because the notions of transactions, security, and scalability are requirements in enterprise software systems. However, the JCA is applicable to any resource that needs to integrate into JBoss in a secure, scalable and transacted manner. In this introduction we will focus on resource adapters as a generic notion rather than something specific to the EIS environment.
The connector architecture defines a standard SPI (Service Provider Interface) for integrating the transaction, security and connection management facilities of an application server with those of a resource manager. The SPI defines the system level contract between the resource adaptor and the application server.
The connector architecture also defines a Common Client Interface (CCI) for accessing resources. The CCI is targeted at EIS development tools and other sophisticated users of integrated resources. The CCI provides a way to minimize the EIS specific code required by such tools. Typically J2EE developers will access a resource using such a tool, or a resource specific interface rather than using CCI directly. The reason is that the CCI is not a type specific API. To be used effectively it must be used in conjunction with metadata that describes how to map from the generic CCI API to the resource manager specific data types used internally by the resource manager.
The purpose of the connector architecture is to enable a resource vendor to provide a standard adaptor for its product. A resource adaptor is a system-level software driver that is used by a Java application to connect to resource. The resource adaptor plugs into an application server and provides connectivity between the resource manager, the application server, and the enterprise application. A resource vendor need only implement a JCA compliant adaptor once to allow use of the resource manager in any JCA capable application server.
An application server vendor extends its architecture once to support the connector architecture and is then assured of seamless connectivity to multiple resource managers. Likewise, a resource manager vendor provides one standard resource adaptor and it has the capability to plug in to any application server that supports the connector architecture.
Figure 7.1, “The relationship between a J2EE application server and a JCA resource adaptor” illustrates that the application server is extended to provide support for the JCA SPI to allow a resource adaptor to integrate with the server connection pooling, transaction management and security management facilities. This integration API defines a three part system contract.
The resource adaptor implements the resource manager side of the system contract. This entails using the application server connection pooling, providing transaction resource information and using the security integration information. The resource adaptor also exposes the resource manager to the application server components. This can be done using the CCI and/or a resource adaptor specific API.
The application component integrates into the application server using a standard J2EE container to component contract. For an EJB component this contract is defined by the EJB specification. The application component interacts with the resource adaptor in the same way as it would with any other standard resource factory, for example, a javax.sql.DataSource JDBC resource factory. The only difference with a JCA resource adaptor is that the client has the option of using the resource adaptor independent CCI API if the resource adaptor supports this.
Figure 7.2, “The JCA 1.0 specification class diagram for the connection management architecture.” (from the JCA 1.0 specification) illustrates the relationship between the JCA architecture participants in terms of how they relate to the JCA SPI, CCI and JTA packages.
The JBossCX architecture provides the implementation of the application server specific classes. Figure 7.2, “The JCA 1.0 specification class diagram for the connection management architecture.” shows that this comes down to the implementation of the javax.resource.spi.ConnectionManager and javax.resource.spi.ConnectionEventListener interfaces. The key aspects of this implementation are discussed in the following section on 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 along with a number of MBeans for loading resource adaptors into the JBoss server. Figure 7.3, “The JBoss JCA implementation components” expands the generic view given by Figure 7.2, “The JCA 1.0 specification class diagram for the connection management architecture.” to illustrate how the JBoss JCA layer implements the application server specific extension along with an example file system resource adaptor that we will look at latter in this chapter.
There are three coupled MBeans that make up a RAR deployment. These are the org.jboss.resource.RARDeployment, org.jboss.resource.connectionmanager.RARDeployment, and org.jboss.resource.connectionmanager.BaseConnectionManager2. The 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 archives files containing resource adaptors (RARs). It creates the org.jboss.resource.RARDeployment MBeans 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. This task performed using a JBoss service descriptor that sets up a org.jboss.resource.connectionmanager.BaseConnectionManager2 MBean implementation with a org.jboss.resource.connectionmgr.RARDeployment dependent.
The org.jboss.resource.connectionmanager.BaseConnectionManager2 MBean is a base class for the various types of connection managers required by the JCA spec. Subclasses include (org.jboss.resource.connectionmanager) NoTxConnectionManager, LocalTxConnectionManager and XATxConnectionManager. These correspond to resource adapators that support no transactions, local transaction and XA transaction respectively. You choose which subclass to use based on the type of transaction semantics you want, provided the JCA resource adaptor supports the corresponding transaction capability.
The common attributes supported by the BaseConnectionManager2 MBean are:
The org.jboss.resource.connectionmanager.RARDeployment MBean manages configuration and instantiation ManagedConnectionFactory instance. It does this using the resource adaptor metadata settings from the RAR META-INF/ra.xml descriptor along with the RARDeployment attributes. The configurable attributes are:
ManagedConenctionFactoryProperties: This is a collection of (name, type, value) tripples 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.
The org.jboss.resource.connectionmanager.JBossManagedConnectionPool MBean is a connection pooling MBean. It is typically used as the embedded MBean value of the BaseConnectionManger2 ManagedConnectionPool attribute. When you setup a connection manager MBean you typically embed the pool configuration in the connection manager descriptor. The configurable attributes of the JBossManagedConnectionPool are:
Criteria: This attribute indicates if the JAAS javax.security.auth.Subject from security domain associated with the connection, or app supplied parameters (such as from getConnection(user, pw)) are used to distinguish connections in the pool. The allowed values are:
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 only be one such MBean, and this is configured in the core jboss-service.xml descriptor. It is used by org.jboss.resource.connectionmanager.CachedConnectionInterceptor, JTA javax.transaction.UserTransaction implementation, and all BaseConnectionManager2 instances. The configurable attributes of the CachedConnectionManager MBean are:
To conclude our discussion of the JBoss JCA framework we will 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. We will not discuss the details of the requirements of a resource adaptor provider as these are discussed in detail in the JCA specification. The purpose of the adaptor is to demonstrate the steps required to create and deploy a RAR in JBoss, and to see how JBoss interacts with the adaptor.
The adaptor we will create could be used as the starting point for a non-transacted file system adaptor. The source to the example adaptor can be found in the src/main/org/jboss/chap7/ex1 directory of the book examples. A class diagram that shows the the mapping from the required javax.resource.spi interfaces to the resource adaptor implementation is given in 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/proj/jboss/education/books/admin-devel/examples/output/chap7 chap7-ex1-rar: [jar] Building jar: /Users/orb/proj/jboss/education/books/admin-devel/examples/output/chap7/ra.jar [jar] Building jar: /Users/orb/proj/jboss/education/books/admin-devel/examples/output/chap7/chap7-ex1.rar prepare: chap7-ex1-jar: [jar] Building jar: /Users/orb/proj/jboss/education/books/admin-devel/examples/output/chap7/chap7-ex1.jar BUILD SUCCESSFUL
The deployed files include a chap7-ex1.sar and a notxfs-service.xml service descriptor. The example resource adaptor deployment descriptor is shown in Example 7.1, “The nontransactional file system resource adaptor deployment descriptor.” while the connection manager MBeans service descriptor is shown in Example 7.2, “The notxfs-ds.xml resource adaptor MBeans service descriptor.”.
Example 7.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> <config-property> <config-property-name>Password</config-property-name> <config-property-type>java.lang.String</config-property-type> <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>
Example 7.2. 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:
You can 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. A simplified descriptor format is available for configuring the JCA services of the application server, and this is described below in Section 7.3.2, “Configuring Generic JCA Adaptors”. The notxfs-ds.xml descriptor shown in Example 7.2, “The notxfs-ds.xml resource adaptor MBeans service descriptor.”, and the following notes apply.
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.6/server/default/deploy [copy] Copying 1 file to /tmp/jboss-3.2.6/server/default/deploy BUILD SUCCESSFUL
The server console will display some logging output indicating that the resource adaptor has been deployed.
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 Example 7.3, “The stateless session bean echo method code which shows the access of the resource adaptor connection factory.”.
Example 7.3. 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.6/server/default/deploy [echo] Waiting for deploy... [java] Created Echo [java] Echo.echo('Hello') = Hello BUILD SUCCESSFUL
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. 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.” 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:
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.
Configuration of the JCA resource adaptors may be done by configuring the JBoss JCA services along with the JCA resource adaptor as shown in the previous section. JBoss 3.2 provides an alternate simplified schema that avoids having to specify so much redundant configuration information.
The syntax for configuring JCA JDBC connection factories has been simplified in 3.2. Rather than configuring the connection manager factory related MBeans discussed in the previous section via a mbean services deployment descriptor, an abbreviated datasource centric descriptor is used. This is transformed into the standard jboss-service.xml MBean services deployment descriptor using a XSL transform applied by the org.jboss.deployment.XSLSubDeployer included in the jboss-jca.sar deployment. The simplified configuration descriptor is deployed the same as other deployable components. The descriptor must be named using a *-ds.xml pattern in order to be recognized by the XSLSubDeployer.
The schema for the top-level datasource elements of the *-ds.xml configuration deployment file is shown in 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:
Elements that are common to all datasources include:
Additional common child elements for both no-tx-datasource and local-tx-datasource include:
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:
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:
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:
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.
The XSLSubDeployer also supports the deployment of arbitrary non-JDBC JCA resource adaptors using an alternate abbreviated syntax. The schema for the top-level connection factory elements of the *-ds.xml configuration deployment file is shown in Figure 7.10, “The simplified JCA adaptor connection factory configuration descriptor top-level schema elements”.
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:
The majority of the elements are the same as those of the datasources configuration. The element unique to the connection factory configuration include:
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:
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.
Example configurations of many third-party JDBC drivers is included in the JBOSS_DIST/docs/examples/jca directory. Current example configurations include: