3.16.8 Settings for using the resource adapters conforming to the Connector 1.5 specifications

This subsection describes the J2EE application and resource adapter settings for using the resource adapters conforming to the Connector 1.5 specifications.

You specify the settings in the HITACHI Application Integrated Property File# and HITACHI Connector Property file respectively.

#
The description in this section is entirely based on the use of HITACHI Application Integrated Property File. If you use the cjgetappprop command to obtain the Message-driven Bean property file, you can specify the settings in the Message-driven Bean property file. If you are using the Message-driven Bean property file, read "beneath the <hitachi-connector-property> tag in HITACHI Application Integrated Property File" as "Message-driven Bean property file".
Organization of this subsection
(1) Items that can be set up
(2) Setting up the Administered objects
(3) Settings for mapping the Message-driven Beans and resource adapters
(4) Setting up the interfaces used by the Message-driven Beans
(5) ActivationSpec settings

(1) Items that can be set up

This section describes the items that can be set up when you use the resource adapters conforming to the Connector 1.5 specifications.

(a) J2EE application settings

The following table describes the content that can be set up in a J2EE application.

Table 3-69 J2EE application settings (for using the resource adapters conforming to the Connector 1.5 specifications)

FunctionalityItemTargetSettings
Looking up Administered objectsInformation used for looking up Administered objectsWAR, Session Bean, Entity Bean, and Message-driven BeanSpecify the settings in the following tags beneath the <resource-env-ref> tag:
  • In the <resource-env-ref-name> tag, specify the name to be used for lookup.
  • In the <resource-env-ref-type> tag, specify the type of the Administered object.
  • In the <linked-adminobject>-<resourceadapter-name> tag, specify the display name of the resource adapter in which the Administered object is included.
  • In the <linked-adminobject>-<adminobject-name> tag, specify the object name of the Administered object.
Message inflow#Mapping with the resource adapterMessage-driven BeanIn the <resource-adapter> tag beneath the <message-ref>-<connection-destination> tag, specify the mapped resource adapter display name.
Interfaces used by the Message-driven BeansMessage-driven BeanIn the <messaging-type> tag, specify the interfaces implemented by the Message-driven Beans.
ActivationSpec settingsMessage-driven BeanIn the <activation-config-property-name> tag and <activation-config-property-value> tag beneath the <activation-config>-<activation-config-property> tag, specify the properties to be set for ActivationSpec.

#: Some of the set values must match the values set for the resource adapter to be used.


(b) Resource adapter settings

From among the items specified as the resource adapter properties, this section describes the main items that can be set up for the resource adapters conforming to the Connector 1.5 specifications and how to set up these items. Note that this section describes content specific to the resource adapters conforming to the Connector 1.5 specifications.

The following table describes the content that can be set up as the properties of the resource adapters conforming to the Connector 1.5 specifications.

Table 3-70 Content that can be set up in the property definitions of the resource adapters conforming to the Connector 1.5 specifications

CategoryItemSettings
Administered objectAdministered object names #1In the <adminobject>-<adminobject-name> tag #2, specify the object name to be used for lookup. Make sure you specify this item when you want to look up an Administered object. You cannot include continuous underscores "__" in the object name.
Note that you must also specify the J2EE application settings to look up an Administered object. See (a) J2EE application settings.
InterfacesIn the <adminobject>-<adminobject-interface> tag, specify the interface to be used. Specify items such as javax.jms.Queue or javax.jms.Topic.
Implementation classes and propertiesIn the <adminobject-class> tag, specify the implementation class.
Specify the Administered object properties beneath the <config-property> tag.

#1: This need not be specified for the Administered objects used with message inflow.

#2: This tag does not exist in the DD (ra.xml).


(2) Setting up the Administered objects

You code the settings for the Administered objects to be used with the message inflow in the HITACHI Connector Property file.

The content set up for the Administered object depends on the resource adapter. See the documentation for the resource adapter in use.

You map the Administered objects to the Message-driven Beans. For details on the mapping, see (5) ActivationSpec settings.

(3) Settings for mapping the Message-driven Beans and resource adapters

You specify the mapping between the Message-driven Beans and resource adapters in the <resource-adapter> tag of HITACHI Application Integrated Property File. Specify the resource adapter display name.

The hierarchy of <resource-adapter> is as follows:

<hitachi-message-bean-property>
<message-ref>
<connection-destination>
<resource-adapter>

These tags are elements that do not exist in the DD (ejb-jar.xml). However, <hitachi-message-bean-property> corresponds to <message-driven> in the DD.

The mapping with the resource adapters is executed when you start the J2EE applications containing the Message-driven Beans. Note that the J2EE applications containing the Message-driven Beans fail to start in the following cases. In this case, the KDJE42359-E message is output:

The Message-driven Beans must be mapped to the Administered objects as well. For details on the mapping, see (5) ActivationSpec settings.

Reference note
You cannot specify the information of the <message-driven>-<message-destination-link> tag with Application Server.

(4) Setting up the interfaces used by the Message-driven Beans

You code the interfaces used by the Message-driven Beans in the <messaging-type> tag of HITACHI Application Integrated Property File. Specify the names of the interfaces implemented by the Message-driven Beans.

The hierarchy of <messaging-type> is as follows:

<hitachi-message-bean-property>
<messaging-type>

The <hitachi-message-bean-property> tag corresponds to <message-driven> in the DD (ejb-jar.xml).

You must specify the interfaces supported by the resource adapter as the interfaces used by the Message-driven Beans. The interfaces supported by the resource adapter are specified in the <messagelistener-type> tag of the DD (ra.xml) for the resource adapter. If you specify an interface other than that specified in this tag, the J2EE application containing the Message-driven Beans fails to start. In this case, the KDJE43167-E message is output.

You can also check the interfaces supported by the resource adapter with the following server management commands. Execute these commands by specifying -resname and -inbound in the arguments.

Note that if no value is specified in the <messaging-type> tag, the javax.jms.MessageListener interface is used as the default value.

Reference note
The javax.jms.MessageListener interface was used as a specific message listener interface until EJB 2.0.

(5) ActivationSpec settings

ActivationSpec is a JavaBean that contains settings required for activating the Message-driven Beans. ActivationSpec contains properties that must be set up according to the resource adapter settings.

(a) Overview of the ActivationSpec settings

You code the values to be set up for ActivationSpec beneath the <activation-config> tag of HITACHI Application Integrated Property File. Specify the property name and the property value. You can specify multiple values.

The hierarchy of <activation-config> is as follows:

<hitachi-message-bean-property>
<activation-config>
<activation-config-property>
<activation-config-property-name>
<activation-config-property-value>

You can specify the default ActivationSpec settings in the DD (ra.xml) for the resource adapter. The value set in the <resourceadapter>-<config-property> tag is used as the default value. When the default value is mentioned and if you set the ActivationSpec value in HITACHI Application Integrated Property File, the value is overwritten by the value specified beneath the <hitachi-message-bean-property> tag.

The properties that you must set up as the ActivationSpec properties are described in (b) Properties that must be set up.

(b) Properties that must be set up

With the ActivationSpec settings, you must set up the values of the properties specified in the <activationspec>-<required-config-property> tag in the DD (ra.xml) for the resource adapter. You can also use the following server management commands to check the properties that must be set up. Execute these commands by specifying -resname and -listenertype in the arguments:

The other properties that can be set up for ActivationSpec depend on the resource adapter. See the documentation for the resource adapter in use.

(c) Properties that must be set up when a message listener supporting the JMS is used

When you use a message listener (message listener that uses the javax.jms.MessageListener interface) that supports the JMS, the following properties must be specified in ActivationSpec. Specify the properties beneath the <activation-config> tag.

Note that Application Server does not check whether these properties are specified. You check whether the property settings are appropriate with the ActivationSpec#validate method provided by the resource adapter.

Reference note
The following items specified as elements beneath the <message-driven> tag in EJB 2.0 have been deleted in EJB version 2.1 and later:
  • <message-selector>
  • <acknowledge-mode>
  • <message-driven-destination>-<subscription-durability>
The Connector 1.5 specifications recommend that these elements can be specified as properties beneath the <activation-config>. However, whether these elements can be specified depends on the resource adapter in use.

For details on the ActivationSpec specifications when you use a message listener that supports the JMS, see the documentation for the Connector 1.5 specifications.

(d) Errors that occur during ActivationSpec generation and setup

When you generate and set up ActivationSpec, errors occur when the states described in the following table are reached. If an error occurs, the J2EE application fails to start.

The following table describes the cases in which errors occur and the messages that are output.

Table 3-71 Mapping the cases in which errors occur and the output messages

Cases in which errors occurOutput messages
An attempt to generate an instance of the ActivationSpec implementation class failsKDJE43168-E
If the javax.resource.spi.ActivationSpec interface is not implemented for a class specified in ActivationSpecKDJE43172-E
If the setter method of the property corresponding to the <activation-config-property-name> tag does not exist in ActivationSpecKDJE43169-E
If an exception is thrown in the invocation of the method that checks whether the settings are appropriate (ActivationSpec#validate method), after the properties are set up in ActivationSpecKDJE43170-E
If the settings corresponding to the property <required-config-property> tag specified in the DD (ra.xml) for the resource adapter are not coded as the <activation-config> tag of HITACHI Application Integrated Property FileKDJE43171-E
If an exception is thrown in the setResourceAdapter method of ActivationSpec #KDJE43173-E

#: The setResourceAdapter method is a method defined in the javax.resource.spi.ResourceAdapterAssociation interface. The javax.resource.spi.ResourceAdapterAssociation interface is a super interface of the javax.resource.spi.ActivationSpec interface.