3.16.6 Specifying multiple connection definitions

When you use the resource adapters conforming to the Connector 1.5 specifications, you can specify multiple connection definitions for one resource adapter. You can specify the settings, such as those for the connection pool and log output, for each connection definition.

To identify a connection definition in a resource adapter, you use the connection definition identifier. The connection identifier is the value specified in <connectionfactory-interface> in the DD. The <connectionfactory-interface> value has a unique value for each connection definition in the resource adapter.

Note that you can check the connection definition identifier for each connection definition included in the resource adapter if you execute the following server management commands by specifying the -outbound option:

This subsection describes the elements that can be specified in the connection definitions and the locations for specifying these elements. This subsection also describes the points to remember when you specify multiple connection definitions.

Organization of this subsection
(1) Elements specifiable in the connection definitions and the location of specification
(2) Points to remember when using a connection pool
(3) Points to remember when a transaction is recovered
(4) Points to remember when a connection test is performed for resources
(5) Points to remember when the operation information and the information for resource depletion monitoring is output
(6) Points to remember when the resource adapter operation log is output

(1) Elements specifiable in the connection definitions and the location of specification

This section describes the elements that can be specified in the connection definitions and the locations for specifying these elements.

Location of specification in the DD and the elements that can be specified in the connection definition

You specify the connection definition beneath <connection-definition> in the DD complying with the Connector 1.5 specifications. The elements specified beneath <connection-definition> are as follows:

Mapping the hierarchical structure and connection definitions of the HITACHI Connector Property file

With the change in the hierarchical structure in the DD (ra.xml), a hierarchy corresponding to the connection definition is added in the property file as well.

For the resource adapters already imported into the J2EE server, you use the HITACHI Connector Property file to change the resource adapter properties. The values defined in the HITACHI Connector Property file are applied to the resource adapter on the J2EE server by using the server management commands. For details on the procedure for using the property file to specify properties, see 3.5 Specifying properties using property files in the uCosminexus Application Server Application Setup Guide.

Note that the resource adapter operation-related properties include items defined for each connection definition and items defined for the entire resource adapter. You specify the items defined for each connection definition beneath <outbound-resourceadapter>-<connection-definition> in the HITACHI Connector Property file. You specify the items defined for the entire resource adapter beneath <resourceadapter-runtime>-<property>.

For details on the method of specification, see 4.1.1 Content specified in the HITACHI Connector Property file in the uCosminexus Application Server Application and Resource Definition Reference Guide.

How to define link resolution in J2EE applications (method of specifying in <resource-ref>-<linked-to>, <cmp-map>-<datasource-name>, or mappedName)

With the J2EE applications that reference the resource adapters conforming to the Connector 1.5 specifications, you must define the connection definition that will be referenced by the J2EE application for link resolution.

Specify the definition using one of the following methods:

Specify a referenced resource containing a connection definition identifier in the following format:

resource-adapter-display-name!connection-definition-identifier

A description of the specified contents is as follows:

resource-adapter-display-name
The value of the <connector>-<display-name> element in the DD (ra.xml) of the referenced resource adapter.
connection-definition-identifier
The value of the <connector>-<resourceadapter>-<outbound-resourceadapter>-<connection-definition>-<connectionfactory-interface> element in the DD (ra.xml) of the referenced resource adapter.

Note that you can also check the resource adapter display name and connection definition identifier with the following server management commands:

(2) Points to remember when using a connection pool

With a resource adapter for which multiple connection definitions are specified, you can manage the connection pools for the connection definitions. You specify the connection pool definition with the elements beneath <outbound-resourceadapter>-<connection-definition>-<connector-runtime>-<property> in the HITACHI Connector Property file.

The points to remember when there are multiple connection pools are as follows:

Executing the commands for connection pools

When you execute the server management commands for connection pools, you must specify the connection pool that you want to target.

When you execute the following commands, you must specify the connection definition identifier. You specify the connection definition identifier in the options of these commands.

Processing for connection pool warming up

The processing for connection pool warming up is executed for each connection definition.

When you execute the processing for connection pool warming up, even if connection pool warming up fails for a specific connection definition, the warming up processing for the other connection pools continues.

(3) Points to remember when a transaction is recovered

You execute transaction recovery for each connection definition. Therefore, if multiple connection definitions are specified, a resource is registered for each connection definition in the OTS.

(4) Points to remember when a connection test is performed for resources

When you execute a connection test for a resource adapter, even if an error occurs in a connection test for a specific connection definition, the processing is not cancelled. The connection tests are executed for all the connection definitions. However, if an error occurs in one of the connection definitions, the return value of the command is a return value indicating an abnormal termination.

(5) Points to remember when the operation information and the information for resource depletion monitoring is output

When multiple connection definitions are specified, the operation information and the information for resource depletion monitoring are output as follows:

Operation information (information output to the operation information file)
Only the information for the first connection definition is output. The first connection definition is the connection definition that is defined first in the DD (ra.xml).
Operation information (information output by using the management commands)
This information cannot be output. If an attempt is made to output the operation information for the resource adapters conforming to the Connector 1.5 specifications, the output content is not guaranteed.
Information for resource depletion monitoring
The information for all the connection definitions specified in the resource adapter is output.

(6) Points to remember when the resource adapter operation log is output

When the operation log of the resource adapters conforming to the Connector 1.5 specifications is output, the name of the output file is in the following format:

resource-adapter-display-name_connection-definition-order_serial-number-of-log-file.log

The connection-definition-order corresponds to the order in which the corresponding <connection-definition> occurs (1, 2, ...) in the DD (ra.xml).