Chapter 2. Outbound Management

Table of Contents

2.1. Management of Connection Pool and Connection
2.1.1. Connection Request Pattern of an Application
2.1.2. Relationship between Resource Adapter and Connection Pool
2.1.3. Strength of Connection Pool
2.1.4. Connection Pool Configuration
2.1.5. Features of Connection Pool
2.2. Transaction Management
2.2.1. Local Transaction Resource Participating in Global Transaction(XA)
2.2.2. Global Transaction(XA) and Connection Sharing
2.3. Example of Connection Pool Configuration
2.3.1. If there is one connection factory
2.3.2. If there are two connection factories
2.4. Monitoring and Controlling Connection Pools
2.4.1. Controlling Connection Pools
2.4.2. Monitoring Connection Pools

This chapter describes roles and functions of JEUS in an outbound communication from an application to EIS, based on interoperation with a connection pool and transaction.

A Connection is required for an application, in an outbound communication, to send a request to EIS and receive a response. JEUS provides the Connection Pool for an application to efficiently use the Connection.

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();
}

Note

In the example, CCI (Common Client Interface) is used, but a connection factory does not actually have a specified interface. It is defined by a resource adapter and used by an application.

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


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.


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.

Note

1. For information about connection manager, refer to javax.resource.spi.ConnectionManager, Javadoc of javax.resource.spi.ManagedConnectionFactory, and JCA standards.

2. For further information about physical connection and connection handle, refer to "Chapter 6. Connection Management" of the JCA standards.

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.

Caution

<connectionfactory-interface> defined in ra.xml file cannot be repeated. If the same value is repeated in ra.xml file, the validity check will fail, and deployment will also fail.

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

Note

For more information about Connection Match and Lazy Transaction Enlistment, refer to the JCA standard.

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>

Caution

To execute the validity check, the resource adapter has to first implement the javax.resource.spi.ValidatingManagedConnectionFactory interface. Sometimes, when validity check is requested to a resource adapter, there may be no response. Since WAS does not currently have a solution for this, a timeout option should be provided by the resource adapters.

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.

PolicyDescription
FailedConnectionOnlyOnly discards a connection for which validity check failed. (Default value)
AllConnectionsDiscards all the other connections along with the failed connection. Before discarding all the connections after the validity check fails, another check is attempted. If it fails again, all connections in the pool are discarded.

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.

  • java.sql.Connection

  • javax.resource.cci.Connection

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.

This section describes how JEUS manges a connection pool whose transaction type is either local or global.

One outbound resource adapter can be used to configure one or more outbound connections.

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.

[Example 2.3] Connection pool configuration when there is one connection factory: <<ra.xml>>


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.


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.

[Example 2.5] Connection pool configuration when there are two connection factories: <<ra.xml>>

<?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.


The JEUS console tool (jeusadmin) or WebAdmin can be used to monitor or control the JCA Connection Pool. To do so, resource adapter modules must be deployed.

The examples in this section assume that a resource adapter module, whose JNDI export name of JCA connection pool is 'my_rar_cp,' has already been deployed. Refer to "2.1.4. Connection Pool Configuration" for JNDI export name configuration of JCA connection pool. Refer to "JEUS Applications & Deployment Guide" for more information about how to deploy resource adapter modules.

Note

This section describes monitoring and controlling methods using WebAdmin. Refer to JEUS Reference Book. "4.2.11. Connection Pool Controlling and Monitoring Commands" for monitoring and controlling methods using the console tool.

The following shows how to monitor connection pools using WebAdmin.

  1. Selecting [Monitoring] > [Connection Pools] from the left menu will take you to the Connection Pools screen. If you select the server, where a resource adapter module was deployed, connection pools that are set for the resource adapter module are displayed.


    The monitored information is listed with the connection pools. The following is a list of connection pool items.

    ItemDescription
    Connection Pool IDSame as the JNDI export name for JCA connection pools.
    JNDI Export NameThe JNDI Repository registration name of the connection pool.
    MinThe minimum number of connections allowed for the connection pool.
    MaxThe maximum number of connections allowed for the connection pool.
    ActiveThe number of connections in use.
    IdleThe number of available idle connections.
    DisposableThe number of disposable connections that are used when there are no idle connections in the connection pool. The disposable connections are created only when the Wait column is set to false.
    TotalThe total number connections that are active, idle, or disposable.
    WaitDetermines whether to create disposable connections if there are no available idle connections in the connection pool.
    EnabledDetermines whether to activate the connection pool.

  2. If you select a connection pool, the details of the connections in the connection pool are displayed.


    The following are descriptions of connection pool items.

    ItemDescription
    Connection IDConnection identifier.
    State

    Connection state.

    • idle : Available.

    • active : In use.

    State TimeTime for maintaining the state.
    Use CountThe number of times the connection was used.
    Type

    Shows if the connection is disposable or not.

    • disposable : Disposable connection.

    • pooled : Non-disposable connection.