3.16.1 Managing the resource adapter lifecycle

When you use the resource adapters conforming to the Connector 1.5 specifications, you can use the J2EE server to manage the lifecycle of the resource adapters.

Resource adapter lifecycle management is functionality that manages the start and stop processing of the resource adapters with the J2EE servers.

Organization of this subsection
(1) Preconditions
(2) Classes used for lifecycle management
(3) Controlling lifecycle management
(4) Notes on using the lifecycle management functionality

(1) Preconditions

Resource adapter lifecycle management is enabled when the resource adapter satisfies the following conditions:

Note that if <connector>-<resourceadapter>-<resourceadapter-class> is not specified in the DD, the resource adapter lifecycle is not managed.

(2) Classes used for lifecycle management

This section describes the classes used for resource adapter lifecycle management. The classes to be used include the classes that must be implemented in the resource adapter and the classes provided by the J2EE servers.

Classes that must be implemented in the resource adapter

The following classes must be implemented with the resource adapter. Note that the Connector 1.5 specifications define that these classes be implemented as JavaBeans.

For the detailed implementation, see the Connector 1.5 specifications.

Classes provided by the J2EE servers

The J2EE server provides the following classes:

(3) Controlling lifecycle management

This section describes the controlling of the start and stop processing of the resource adapters whose lifecycles are to be managed.

The start and stop processing of a resource adapter is executed at the following times:

Control procedure when the resource adapter start processing is executed

The following figure shows the control procedure when the resource adapter start processing is executed.

Figure 3-38 Control procedure when the resource adapter start processing is executed

[Figure]

The following points describe the control executed by the resource adapter start processing. Note that the item numbers correspond to the numbers in the figure.

  1. WorkManager (implementation class of the javax.resource.spi.work.WorkManager interface) is generated.
  2. BootstrapContext (implementation class of the javax.resource.spi.BootstrapContext interface) is generated.
  3. ResourceAdapterJavaBean (implementation class of the javax.resource.spi.ResourceAdapter interface) is generated.
    The implementation class generated as ResourceAdapterJavaBean is the class specified in <connector>-<resourceadapter>-<resourceadapter-class> in the DD (ra.xml) of the resource adapter.
    If the class specified in this tag cannot be instantiated, the resource adapter fails to start#. In this case, the KDJE48589-E message is output.
  4. The properties are set up in ResourceAdapterJavaBean.
    The value specified in <connector>-<resourceadapter>-<config-property> in the DD (ra.xml) is set up in ResourceAdapterJavaBean that was generated in 3. The settings are executed with the setter method complying with the JavaBean specifications. If an exception occurs during the invocation of the setter method, the KDJE48594-W message is output. However, the processing continues.
  5. The start method of the javax.resource.spi.ResourceAdapter interface is invoked and the resource adapter is started.
    If the invocation of this method throws an exception, the resource adapter fails to start#. In this case, the KDJE48590-E message is output.
  6. ResourceAdapterJavaBean and ManagedConnectionFactoryJavaBean are associated (for Outbound).
    When you use the lifecycle management functionality, the implementation class of the javax.resource.spi.ManagedConnectionFactory interface implements the javax.resource.spi.ResourceAdapterAssociation interface. ResourceAdapterJavaBean and ManagedConnectionFactory are associated using the setResourceAdapter(ResourceAdapter) method of the javax.resource.spi.ResourceAdapterAssociation interface.
    Also, in the following cases, the resource adapter fails to start#. In this case, KDJE48591-E is output.
    • When the javax.resource.spi.ResourceAdapterAssociation interface is not implemented for ManagedConnectionFactoryJavaBean
    • When an exception is thrown for the invocation of the setResourceAdapter method
  7. AdminObjectJavaBean (Administered object) is generated and the properties are set up.
    The implementation class generated as AdminObjectJavaBean is the class specified in <connector>-<resourceadapter>-<adminobject>-<adminobject-class> in the DD (ra.xml) of the resource adapter. If the class specified in this tag cannot be instantiated, the resource adapter fails to start #. In this case, the KDJE48597-E message is output.
    Also, the value specified in <connector>-<resourceadapter>-<adminobject>-<config-property> in the DD (ra.xml) is set up in AdminObjectJavaBean. The settings are executed with the setter method complying with the JavaBean specifications. If an exception occurs during the invocation of the setter method of AdminObjectJavaBean, the KDJE48598-W message is output. However, the processing continues.
#
For the resource adapters included in an application, when the resource adapter fails to start, the start processing of the application containing that resource adapter also fails.
Control procedure when the resource adapter stop processing is executed

The following figure shows the control procedure when the resource adapter stop processing is executed.

Figure 3-39 Control procedure when the resource adapter stop processing is executed

[Figure]

The following points describe the control executed by the resource adapter stop processing. Note that the item numbers correspond to the numbers in the figure.

  1. A check is executed to confirm that all the EJBs, servlets, and Message-driven Beans, referencing the resource adapter to be stopped, are stopped.
    Make sure that the following elements are not being used:
    • Inbound resource adapter
    • Connection factory
    • Administered object
    If these elements are being used, the resource adapter stop processing is cancelled.
  2. AdminObjectJavaBean (Administered object) is destroyed.
  3. The stop method of the javax.resource.spi.ResourceAdapter interface is invoked and the resource adapter stops.
    If the invocation of this method throws an exception, the KDJE48590-E message is output and the resource adapter stop processing fails.
  4. ResourceAdapterJavaBean is destroyed.
Transition of the resource adapter state

The state of the resource adapter changes to Started or Stopped when the resource adapter start or stop processing is executed.

The following figure shows the transition of the resource adapter state.

Figure 3-40 Transition of the resource adapter state

[Figure]

(4) Notes on using the lifecycle management functionality

Note the following points when you use the lifecycle management functionality: