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.4 contains a connector architecture (JCA) specification that allows for the integration of transacted and secure resource adaptors into a J2EE application server environment. 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.
Connection management: a contract that allows the application server to pool resource connections. The purpose of the pool management is to allow for scalability. Resource connections are typically expense objects to create and pooling them allows for more effective reuse and management.
Transaction Management: a contract that allows the application server transaction manager to manage transactions that engage resource managers.
Security Management: a contract that enables secured access to resource managers.
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.5 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.
There are three coupled MBeans that make up a RAR deployment. These are the org.jboss.resource.deployment.RARDeployment, org.jboss.resource.connectionmanager.RARDeployment, and org.jboss.resource.connectionmanager.BaseConnectionManager2. The org.jboss.resource.deployment.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 creathes the org.jboss.resource.deployment.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 NoTxConnectionManager, LocalTxConnectionManager and XATxConnectionManager. These correspond to resource adaptors 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:
ManagedConnectionPool: This specifies the ObjectName of the MBean representing the pool for this connection manager. The MBean must have an 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 below.
CachedConnectionManager: This specifies the ObjectName of the CachedConnectionManager MBean implementation used by the connection manager. Normally this is 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 of 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 has more information on the security settings.
JaasSecurityManagerService: This is the ObjectName of the security manager service. This should be set to the security manager MBean name as defined in the conf/jboss-service.xml descriptor, and currently this is jboss.security:service=JaasSecurityManager. This attribute will likely be removed in the future.
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:
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. The RARDeployer creates this when it deploys a RAR file. This attribute will likely be removed in the future.
ManagedConnectionFactoryProperties: 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 adaptor 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 of the JBoss server VM. In the future this restriction may be configurable.
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 setup a connection manager MBean you typically embed the pool configuration in the connection manager descriptor. The configurable attributes of the JBossManagedConnectionPool are:
ManagedConnectionFactoryName: This specifies the ObjectName of the MBean that creates javax.resource.spi.ManagedConnectionFactory instances. Normally this is configured as an embedded MBean in a depends element rather than 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 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 will never throw an exception if creating a new connection takes an inordinately long time.
IdleTiemoutMinutes: This attribute indicates the maximum time a connection may be idle before being closed. The actual maximum time depends also on the idle remover thread scan time, which is 1/2 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 the other inside a transaction. The actual pools are lazily constructed on first use. This is only relevant 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 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:
ByContainer: use Subject
ByApplication: use application supplied parameters only
ByContainerAndApplication: use both
ByNothing: all connections are equivalent, usually if adapter supports reauthentication
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 CachedConnectionInterceptor, JTA UserTransaction implementation and all BaseConnectionManager2 instances. The configurable attributes of the CachedConnectionManager MBean are:
SpecCompliant: Enable this boolean attribute for spec compliant non-shareable connections reconnect processing. This allows a connection to be opened in one call and used in another. Note that specifying this behavior disables connection close processing.
Debug: 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.
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 mapping from the required javax.resource.spi interfaces to the resource adaptor implementation is given in Figure 7.3, “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.
[examples]$ ant -Dchap=chap7 build-chap
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.”.
Example 7.1. The nontransactional 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 define the classes of the resource adaptor, and the elements are:
managedconnectionfactory-class: The implementation of the ManagedConnectionFactory interface, org.jboss.chap7.ex1.ra.FSManagedConnectionFactory
connectionfactory-interface: This is 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.DirContextFactory. This value will be needed when we create the JBoss ds.xml to use the resource.
connectionfactory-impl-class: This is the class that provides the implementation of the connectionfactory-interface, org.jboss.chap7.ex1.ra.DirContextFactoryImpl.
connection-interface: This is the interface for the connections returned by the resource adaptor connection factory, here the JNDI javax.naming.directory.DirContext interface.
connection-impl-class: This is he class that provides the connection-interface implementation, org.jboss.chap7.ex1.ra.FSDirContext.
transaction-support: The level of transaction support, here defined as NoTransaction, meaning the file system resource adaptor does not do transactional work.
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 using a ds.xml descriptor file. An example of this for the file system adaptor is shown in Example 7.2, “The notxfs-ds.xml resource adaptor MBeans service descriptor.”.
Example 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:
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 we 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. Here our 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. Here 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, 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 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 below.
Example 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 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:
[examples]$ ant -Dchap=chap7 -Dex=1 run-example
You'll see some output from the bean in the system console, but much more detailed logging output can be found 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, we'll summarize the events seen in the log using a sequence diagram. Figure 7.4, “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.4. 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 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 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.
Rather than configuring the connection manager factory related MBeans discussed in the previous section via a mbean services deployment descriptor, JBoss provides a simplified datasource centric descriptor. 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.5, “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 Figure 7.6, “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 Figure 7.7, “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 Figure 7.8, “The XA DataSource configuration schema”.
ha-local-tx-datasource: This element is identical to local-tx-datasource, with the addition of the experimental datasource failover capability allowing JBoss to failover to an alternate database in the event of a database failure.
ha-xa-datasource: This element is identical to xa-datasource, with the addition of the experimental datasource failover capability allowing JBoss to failover to an alternate database in the event of a database failure.
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:/ context, unless use-java-context is set to false. DataSource wrappers are not usable outside of the server VM, so they are normally bound under the java:/, which isn't shared outside the local VM.
use-java-context: If this is set to false the the datasource will be bound in the global JNDI context rather than the java: context.
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.
application-managed-security: Specifying this element indicates that connections in the pool should be distinguished by application code supplied parameters, such as from getConnection(user, pw).
security-domain: Specifying this element indicates that connections in the pool should be distinguished by JAAS Subject based information. 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.
security-domain-and-application: Specifying this element indicates that connections in the pool should be distinguished both by application code supplied parameters and JAAS Subject based information. 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.
new-connection-sql: This is 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: This is a SQL statement that should be run on a connection before it is returned from the pool to test its validity to test for 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 examine database exceptions to determine whether or not the exception indicates a connection error. Current implementations include:
org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter
org.jboss.resource.adapter.jdbc.vendor.MySQLExceptionSorter
org.jboss.resource.adapter.jdbc.vendor.SybaseExceptionSorter
org.jboss.resource.adapter.jdbc.vendor.InformixExceptionSorte
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. The only provided implementation is 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.
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.
type-mapping: This element declares a default type mapping for this datasource. The type mapping should match a type-mapping/name element from standardjbosscmp-jdbc.xml.
Additional common child elements for both no-tx-datasource and local-tx-datasource include:
connection-url: This is the JDBC driver connection URL string, for example, jdbc:hsqldb:hsql://localhost:1701.
driver-class: This is 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.
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
no-tx-separate-pools: The presence of this element indicates that two connection pools are required to isolate connections used with JTA transaction from those used without a JTA transaction. The pools are lazily constructed on first use. 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.
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.
The failover options common to ha-xa-datasource and ha-local-tx-datasource are:
url-delimeter: This element specifies a character used to separate multiple JDBC URLs.
url-property: In the case of XA datasources, this property specifies the name of the xa-datasource-property that contains the list of JDBC URLs to use.
Example configurations for many third-party JDBC drivers are included in the JBOSS_DIST/docs/examples/jca directory. Current example configurations include:
asapxcess-jb3.2-ds.xml
cicsr9s-service.xml
db2-ds.xml
db2-xa-ds.xml
facets-ds.xml
fast-objects-jboss32-ds.xml
firebird-ds.xml
firstsql-ds.xml
firstsql-xa-ds.xml
generic-ds.xml
hsqldb-ds.xml
informix-ds.xml
informix-xa-ds.xml
jdatastore-ds.xml
jms-ds.xml
jsql-ds.xml
lido-versant-service.xml
mimer-ds.xml
mimer-xa-ds.xml
msaccess-ds.xml
mssql-ds.xml
mssql-xa-ds.xml
mysql-ds.xml
oracle-ds.xml
oracle-xa-ds.xml
postgres-ds.xml
sapdb-ds.xml
sapr3-ds.xml
solid-ds.xml
sybase-ds.xml
The XSLSubDeployer also supports the deployment of arbitrary non-JDBC JCA resource adaptors. The schema for the top-level connection factory elements of the *-ds.xml configuration deployment file is shown in Figure 7.11, “The simplified JCA adaptor connection factory configuration descriptor top-level schema elements”.
Figure 7.11. 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 additional 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 Figure 7.12, “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 Figure 7.13, “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.
local-transaction: This element specifies that the tx-connection-factory supports local transactions.
xa-transaction: This element specifies that the tx-connection-factory supports XA transactions.
track-connection-by-tx: This element specifies that a connection should be used only on a single transaction and that a transaction should only be associated with one connection.
rar-name: This is the name of the RAR file that contains the definition for the resource we want to provide. For nested RAR files, the name would look like myapplication.ear#my.rar.
connection-definition: This is the connection factory interface class. It should match the connectionfactory-interface in the ra.xml file.
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.