An application can request a Connection Factory, and then obtain a Connection from the Factory. This is the same as the method for looking up a data source to obtain a JDBC connection, and then obtaining a connection from the data source.

The following is an example of connection request pattern of an application.

// obtain the initial JNDI Naming context
Context initctx = new InitialContext();
// perform JNDI lookup to obtain the connection factory
javax.resource.cci.ConnectionFactory connectionFactory = 
  (javax.resource.cci.ConnectionFactory)initctx.lookup(“java:comp/env/eis/sampleEIS”);
javax.resource.cci.Connection conn = connectionFactory.getConnection();
try {
   // do some works
} finally {
   conn.close();
}

Assuming that the application above is an EJB, the annotation or <resource-ref> in the ejb-jar.xml file should be configured as follows:

<ejb-jar>
. . .

<enterprise-beans>
    . . .
    <session>
        . . .
        <resource-ref>
            <res-ref-name>eis/sampleEIS</res-ref-name>
            <res-type>
                javax.resource.cci.ConnectionFactory
            </res-type>
            <res-auth>Container</res-auth>
            <res-sharing-scope>Shareable</res-sharing-scope>
        </resource-ref>
        . . .

In jeus-ejb-dd.xml, a JNDI name to which 'eis/sampleEIS' is to be mapped should be specified.

In the following example, 'sampleConnectionPool', is the JNDI name of the connection pool that is specified in jeus-connector-dd.xml when deploying a resource adapter.

<jeus-ejb-dd>
    . . .
    <beanlist>
        <jeus-bean>
            . . .
            <res-ref>
                <jndi-info>
                    <ref-name>eis/sampleEIS</ref-name>
                    <export-name>sampleConnectionPool</export-name>
                </jndi-info>
            </res-ref>
    . . .

If an application requests a Connection Factory through JNDI, JEUS requests a resource adapter to create the Connection Factory.

To do so, JEUS passes a connection manager to the resource adapter. The implementation entity of the connection manager is the JEUS Connection Pool.

The resource adapter will pass the created Connection Factory to JEUS, and JEUS will pass it to the application. If the application requests the Connection Factory to create a Connection, the resource adapter requests the Connection Manager for a Connection. The JEUS connection manager then takes a physical connection (or ManagedConnection) from the connection pool to create a connection handle, and returns it to the resource adapter. The resource adapter passes it to the application. A physical connection and connection handle are defined in the JCA standard.

If a connection is no longer needed, the application has to return it. This is called 'closing the connection.' If the application does not properly close a connection, there will be a connection leak.

It is the resource adapter's choice to use the connection manager passed from JEUS. If a resource adapter creates a connection internally without using a connection manager, JEUS is not involved in connection management and communication between an application and EIS.

The functions of JEUS connection pool provided by JCA are similar to those of DB connection pool but have the following advantages.

JEUS connection pool can be configured in the jeus-connector-dd.xml file when deploying a resource adapter.

JCA connection pool is automatically created without being configured. In order for an application to use a connection pool, a JNDI name is required, which is automatically created according to the rule set by JEUS. In order for a user to specify a JNDI name, it should be set in jeus-connector-dd.xml file. A connection pool can be configured inside the <jeus-connector-dd> tag, which is inside the <connection-pool> tag, in jeus-connector-dd.xml file. For information about how to include the jeus-connector-dd.xml file in RAR, refer to "Chapter 4. Resource Adapter".

By the JCA standard, multiple connection pools can be configured to one resource adapter. A connection pool is based on <connection-definition> element in ra.xml file, and its sub-element, <connectionfactory-interface>. For example, if five separate <connection-definition> elements are specified, five connection pools are created in JEUS.

Each tag is explained as follows. For examples related to configuration of each, refer to "2.3. Example of Connection Pool Configuration".

A connection pool can examine the validity of connections, and handle connection leaks.

Connection Validity Check

When an application requests a connection, a connection pool can request a resource adapter to check validity of a connection. This is useful for checking disconnection caused by an internal error of the connection, or socket disconnection caused by the firewall. If validity check fails, a new physical connection is created and returned to the application.

If validity check is performed too often incurring overhead, configure the <non-validation-interval> setting. If the gap between the last time the connection was used and the start time of the validity check is less than the specified value, the validity check is not performed since the connection is considered valid in this case.

For example, if an interval is set to 5 seconds (5,000 ms), and less than five seconds have passed since the connection was last used, the connection is assumed to be valid.

The following is an example of the <non-validation-interval> element.

<non-validation-interval>5000</non-validation-interval>

If validity check fails, the user can specify a destroy policy for the other connections in the connection pool. The policy is described in the following table.

The following is an example of setting the Destroy policy for connections in the pool when the validity check fails.

<destroy-policy-on-validation>AllConnections</destroy-policy-on-validation>

Handling Connection Leak

JEUS can specify an action to handle connection leaks in each connection pool or server.

For components such as servlet/JSP, stateless session beans, and message driven bean, whose start and end are clear, it is easy to check if a used connection was returned properly. If a connection has not been returned, it is possible to set an action to force the connection to be closed, or record logs through the Invocation Manager. However, a JCA connection throws an exception for the automatic return (AutoClose) action of the Invocation Manager.

Since from the JCA connection pool it is not possible to know which method closes a connection, the pool cannot directly close the connection. However, if the <connection-interface> element inside the <connection-definition> element in resource adapter's ra.xml file is configured as the following, the pool is able to close the connection. This is because, in this case, the pool already knows the structure of the 'close' method and the method has no parameters.

The following are the exception handling methods for the AutoClose action of JCA Connection's Invocation Manager.

If the previous <connection-interface> element is not configured, it is difficult to directly close a connection. However, after calling the cleanup method defined in javax.resource.spi.ManagedConnection, the connection is forced to be returned to the pool.

In the 'cleanup' method, the resource adapter's role is defined as follows:

The cleanup should invalidate all connection handles
that had been created using this ManagedConnection instance.

Since a local transaction is a transaction between an application and resource adapter, JEUS cannot request a resource adapter for a connection unless it's for a global transaction.

When using a local transaction type connection pool for a global transaction, javax.resource.spi.LocalTransaction instance obtained from the ManagedConnection instance of a resource adapter can be emulated as an XAResource object.

Even if a resource adapter does not support global transactions(XA), if it supports local transactions, at most one resource can participate in a global transaction(XA). This works like the connection pool data source that uses the XA emulation function.

Connection sharing means that the same connection is always used for a particular resource within the same global transaction(XA). JEUS supports connection sharing, and connections can be shared without any settings.

To disable the connection sharing function, for each application, configure the <resource-ref> element as Unsharable.

Set the following in the ejb-jar.xml and web.xml files.

<resource-ref>
    <res-ref-name>jca/pool</res-ref-name>
    <res-type>javax.resource.cci.ConnectionFactory</res-type>
    <res-sharing-scope>Unshareable</res-sharing-scope>
<resource-ref>

The following is an example of the ra.xml file that contains javax.resource.cci.ConnectionFactory interface as the Connection Factory element. In most cases, there is only one Connection Factory specified as shown in the following.

<?xml version="1.0" encoding="UTF-8"?>
<connector xmlns="http://java.sun.com/xml/ns/j2ee" version="1.5"
           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">
    <display-name>ConnectionManagementSample1</display-name>
    <vendor-name>TmaxSoft</vendor-name>
    <eis-type>TestResource</eis-type>
    <resourceadapter-version>2.0</resourceadapter-version>
    <license>
        <license-required>false</license-required>
    </license>
    <resourceadapter>
        <outbound-resourceadapter>
            <connection-definition>
                <managedconnectionfactory-class>
                    com.tmax.SampleManagedConnectionFactory
                </managedconnectionfactory-class>
                <connectionfactory-interface>
                    javax.resource.cci.ConnectionFactory
                </connectionfactory-interface>
                <connectionfactory-impl-class>
                    com.tmax.SampleConnectionFactory
                </connectionfactory-impl-class>
                <connection-interface>
                    javax.resource.cci.Connection
                </connection-interface>
                <connection-impl-class>
                    com.tmax.SampleConnection
                </connection-impl-class>
            </connection-definition>
            <transaction-support>
                LocalTransaction
            </transaction-support>
            <authentication-mechanism>
                <authentication-mechanism-type>
                    BasicPassword
                </authentication-mechanism-type>
                <credential-interface>
                    javax.resource.spi.security.PasswordCredential
                </credential-interface>
            </authentication-mechanism>
            <reauthentication-support>
                false
            </reauthentication-support>
        </outbound-resourceadapter>
    </resourceadapter>
</connector>

If the jeus-connector-dd.xml file is not configured, it is not possible to create a connection pool corresponding to the <connection-definition> setting in the ra.xml file. Therefore, you must configure the <export-name> element in the jeus-connector-dd.xml file.

The following is an example of the jeus-connector-dd.xml file. Refer to "2.1.4. Connection Pool Configuration" for more information about each tag.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<jeus-connector-dd xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
    <connection-pool>
        <export-name>jcapool</export-name>
        <pool-management>
            <min>10</min>
            <max>50</max>
            <period>600000</period> <!-- 10 minutes -->
            <wait-connection>
                <wait-connection>true</wait-connection>
                <wait-timeout>30000</wait-timeout>
            </wait-connection>
            <action-on-connection-leak>Warning</action-on-connection-leak>
        </pool-management>
    </connection-pool>
</jeus-connector-dd>

The following is an example of the ra.xml file that configures javax.sql.DataSource and javax.resource.cci.ConnectionFactory interfaces as Connection Factory settings.

<?xml version="1.0" encoding="UTF-8"?>
<connector xmlns="http://java.sun.com/xml/ns/j2ee" version="1.5"
           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">
    <display-name>ConnectionManagementSample1</display-name>
    <vendor-name>TmaxSoft</vendor-name>
    <eis-type>TestResource</eis-type>
    <resourceadapter-version>2.0</resourceadapter-version>
    <license>
        <license-required>false</license-required>
    </license>
    <resourceadapter>
        <outbound-resourceadapter>
            <connection-definition>
                <managedconnectionfactory-class>
                    com.tmax.DataSourceManagedConnectionFactory
                </managedconnectionfactory-class>
                <connectionfactory-interface>
                    javax.sql.DataSource
                </connectionfactory-interface>
                <connectionfactory-impl-class>
                    com.tmax.JeusDataSource
                </connectionfactory-impl-class>
                <connection-interface>
                    java.sql.Connection
                </connection-interface>
                <connection-impl-class>
                    com.tmax.JeusConnection
                </connection-impl-class>
            </connection-definition>
            <connection-definition>
                <managedconnectionfactory-class>
                    com.tmax.SampleManagedConnectionFactory
                </managedconnectionfactory-class>
                <connectionfactory-interface>
                    javax.resource.cci.ConnectionFactory
                </connectionfactory-interface>
                <connectionfactory-impl-class>
                    com.tmax.SampleConnectionFactory
                </connectionfactory-impl-class>
                <connection-interface>
                    javax.resource.cci.Connection
                </connection-interface>
                <connection-impl-class>
                    com.tmax.SampleConnection
                </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>
                false
            </reauthentication-support>
        </outbound-resourceadapter>
    </resourceadapter>
</connector>

As shown in the following, you must configure the <connectionfactory-interface> element in order to create a connection pool through the jeus-connector-dd.xml file according to the <connection-definition> setting of the ra.xml file. Otherwise, an error, that a connection pool cannot be created, will occur during deployment.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<jeus-connector-dd xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
    <connection-pool>
        <export-name>jdbcpool</export-name>
        <connectionfactory-interface>
           javax.sql.DataSource
        </connectionfactory-interface>
        <pool-management>
            <min>5</min>
            <max>20</max>
        </pool-management>
    </connection-pool>
    <connection-pool>
        <export-name>ccipool</export-name>
        <connectionfactory-interface>
           javax.resource.cci.ConnectionFactory
        </connectionfactory-interface>
        <pool-management>
            <min>1</min>
            <max>10</max>
        </pool-management>
    </connection-pool>
</jeus-connector-dd>

The following shows how to control connection pools using WebAdmin.

The following shows how to monitor connection pools using WebAdmin.