Table of Contents
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();
}
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.
For more information about jeus-connector-dd.xml, refer to "Chapter 4. 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.
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.
The functions of JEUS connection pool provided by JCA are similar to those of DB connection pool but have the following advantages.
High performance
In general, a process for creating a connection to a database or external resource is slow. However, since a physical connection in the connection pool can be reused without having to recreate it each time, overhead for creating a connection can be reduced. The overhead for disconnecting can also be reduced, as a connection closed by an application is not actually disconnected, but returned to the pool.
Simultaneous connection management
The number of clients sending requests to a resource can be controlled. This prevents too many requests from being sent to the resource and causing an outage.
For information about DB connection pool, refer to JEUS Server Guide. "Chapter 6. DB Connection Pool and JDBC".
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.
<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".
If ra.xml file contains two or more <connection-definition> elements, <connectionfactory-interface> element should be specified. Otherwise, it is impossible to create a connection pool, and a deployment error will occur.
Specify a value for the <connectionfactory-interface> element specified inside each <connection-definition> element in ra.xml file. For details about <connectionfactory-interface>, refer to "Chapter 4. Resource Adapter".
JNDI name of a connection pool.
The name should be unique within the server, and it is required.
Specify a transaction type supported by the connection pool. The specified value overrides the configuration in ra.xml file.
NoTransaction
LocalTransaction
XATransaction
User ID sent to the connection pool to create a Connection.
Password sent to the connection pool to create a Connection.
To store an encrypted password, configure it as follows:
{algorithm}ciphertext
Ex)
{DES}FQrLbQ/D8O1lDVS71L28rw==
<use-lazy-transaction-enlistment>
Determines whether to use the "Lazy Transaction Enlistment" option, which is one of the transaction optimization functions stated in the JCA standard. (Default value: false)
Main options of a connection pool exist inside the <pool-management> sub-element of the <connection-pool> element.
<min>: Initial value for the number of connections (Default value: 2)
<max>: The maximum number of connections allowed in a connection pool (Default value: 10)
<step>: The number of connections added when it needs to be increased. (Default value: 1)
<period>: Sets the size of a connection pool to the minimum value at specified intervals. If there is no idle connection in the pool, the size is not reduced to the minimum value. The unit is in milliseconds. This setting replaces the <pooled-timeout> value. (Default value: 10 minutes, Unit: ms)
<wait-connection>: Determines how to process a connection request that is issued when there is no idle connection and the size of the connection pool reaches the maximum value.
Tag | Description |
---|---|
<wait-connection> |
|
<wait-timeout> | Only valid when <wait-connection> is set to true. Specifies how long a user should wait for a connection. If no connection is available for the user during the time period, an exception occurs. (Default value: 10 seconds, Unit: ms) |
<use-match-connection>: Determines whether to use Connection Match. (Default value: false)
<allow-disposable-connection-when-match-failed>: Determines whether to use a disposable connection if Connection Match fails. If Connection Match is not set, this setting is not used. (Default value: false)
<connection-validation>: Sets a validity check for a connection.
Tag | Description |
---|---|
<enabled> | Determines whether to use the connection validity check function. Even if this tag is set to true, the resource adapter must implement the javax.resource.spi.ValidatingManagedConnectionFactory interface to use this setting. |
<period> | Specifies an interval for the connection validity check. Checks the validity of idle connections at specified intervals. (Unit: ms) |
<non-validation-interval> | If the gap between the last time the connection was used and the start time of the validity check is smaller than the specified value, validity check is not performed. This setting can reduce the overhead of the check. (Unit: ms) |
<validation-retrial-count> | When the destroy policy is set to FailedConnectionOnly, the validity check is performed only once. When the policy is set to AllConnections, the check is performed twice for each connection, and another one if the first one fails. If more validity checks are needed, the number can be increased using this setting. |
<destroy-policy-on-validation> | Determines how to process connections in the connection pool when the connection validity check fails.
|
<action-on-connection-leak>: Sets logging or return action for connections used by a component (Mainly stateless components- servlet/JSP, stateless session beans, and MDB). If not set, the default setting for Action On Resource Leak configured in the server will be performed. (Default value: Warning)
<connection-trace>: Option to monitor connections. The default setting is that the stack trace during getConnection is displayed in order to show which applications are using the connections. Such information is also displayed when Action On Resource Leak configured in the server is processed.
Option | Description |
---|---|
enabled | Turn the connection trace function on/off. |
get-connection-trace | Stores stack trace information when an application obtains a connection (calling getConnection). (Default value: true) |
local-transaction-trace | Determines whether to trace information about local transactions between an application and a resource adapter. When used with the <get-connection-trace> setting, it is helpful for tracing an application that did not properly commit or roll back a local transaction. |
<max-use-count>: A connection can be used as many times as the specified value, and after that, it is closed and a new connection is created. (Default value: 0, meaning that the connections will continue to be used without being replaced).
<pool-destroy-timeout>: Waiting time to destroy a connection pool. A connection pool is destroyed when undeploying the resource adapter. Doing network communication with the resource while closing connections may cause the system to hang. If destruction is not executed during the specified waiting time, undeploy will continue to be processed ignoring the setting. (Default value: 10 seconds)
Adds a property to be applied to ManagedConnectionFactory. Used to replace or add a value specified in the ra.xml file.
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.
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>
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.
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>
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.
For more information about the Invocation Manager, refer to JEUS Server Guide. "2.3.1.2. Action On Resource Leak".
This section describes how JEUS manges a connection pool whose transaction type is either local or global.
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.
For further information about data sources, refer to JEUS Server Guide. "6.4. Data Source Configuration".
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>
1. For details about connection sharing, refer to the section "7.9 Connection Sharing" of the JCA standard 1.6.
2. DB connection pool also supports connection sharing. Refer to JEUS Server Guide. "6.11. Global Transaction (XA) and Connection Sharing".
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>>
<?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.
[Example 2.4] Connection pool configuration when there is one connection factory: <<jeus-connector-dd.xml>>
<?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.
[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.
[Example 2.6] Connection pool configuration when there are two connection factories: <<jeus-connector-dd.xml>>
<?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 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.
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 control connection pools using WebAdmin.
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.
If you click a connection pool, detailed information and the control buttons of the connection pool will appear. A connection pool has not been created yet, so click the [create] button to create a new connection pool.
The following describes the buttons for managing connection pools.
Button | Description |
---|---|
[enable] | Activates the connection pool. |
[disable] | Inactivates the connection pool. |
[shrink] | Adjusts the number of connections in the connection pool to the minimum value. |
[refresh] | Replaces connections of the connection pool with new connections. |
Clicking the [create] button will create a connection pool as follows:
The following shows how to monitor connection pools using WebAdmin.
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.
Item | Description |
---|---|
Connection Pool ID | Same as the JNDI export name for JCA connection pools. |
JNDI Export Name | The JNDI Repository registration name of the connection pool. |
Min | The minimum number of connections allowed for the connection pool. |
Max | The maximum number of connections allowed for the connection pool. |
Active | The number of connections in use. |
Idle | The number of available idle connections. |
Disposable | The 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. |
Total | The total number connections that are active, idle, or disposable. |
Wait | Determines whether to create disposable connections if there are no available idle connections in the connection pool. |
Enabled | Determines whether to activate the connection pool. |
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.
Item | Description |
---|---|
Connection ID | Connection identifier. |
State | Connection state.
|
State Time | Time for maintaining the state. |
Use Count | The number of times the connection was used. |
Type | Shows if the connection is disposable or not.
|