3.16.2 Managing the resource adapter work

When you use the resource adapters conforming to the Connector 1.5 specifications, you can manage the threads used by the resource adapters through the J2EE server.

Resource adapter work management is a functionality for using the threads appropriately when a resource adapter is operated by multithreading. The J2EE server manages the threads in a pool, and allocates the threads to the necessary resource adapters.

Note
The J2EE application execution time is not monitored for the thread that executes Work for which work is to be managed.
For details on monitoring the J2EE application execution time, see 5.3 Monitoring and cancelling the J2EE application execution time in the uCosminexus Application Server Operation, Monitoring, and Linkage Guide.
Organization of this subsection
(1) Preconditions
(2) Classes used for work management
(3) Procedure for work management
(4) Thread pooling
(5) Work management start and termination processing
(6) Notes on using the work management functionality

(1) Preconditions

The resource adapter work management functionality is available when the lifecycle of the resource adapter is being managed. For details on the resource adapter lifecycle management, see 3.16.1 Managing the resource adapter lifecycle.

(2) Classes used for work management

This section describes the classes used for managing the resource adapter work. The classes to be used include the classes that must be implemented in the resource adapter and the classes provided by the J2EE servers. Note that the classes provided by the J2EE servers are the same as the classes used for the lifecycle management. See 3.16.1(2) Classes used for lifecycle management.

Classes that must be implemented in the resource adapter

The following class must be implemented with the resource adapter:

Note that if you want to use a resource adapter to manage the timing for work registration, allocation of work to threads, and work termination, execute the implementation class of the javax.resource.spi.work.WorkListener interface as well.

(3) Procedure for work management

This section describes the procedure for work management.

The following figure shows gives an overview of work management.

Figure 3-41 Overview of work management

[Figure]

The following points describe the procedure shown in the figure:

  1. Registering Work
    The resource adapter generates Work (implementation class of the javax.resource.spi.work.Work interface) and registers Work in WorkManager.
    At this time, the WorkManager instance is passed to the resource adapter via BootstrapContext. For details on WorkManager, see 3.16.1 Managing the resource adapter lifecycle.
    If you also register WorkListener (javax.resource.spi.work.WorkListener) in WorkManager at the same time as registering Work, thereafter, when the registration of Work is complete (when 1 is executed), when a thread is allocated to Work (when 2 is executed), and when the processing of Work is complete (when 3 is executed), you can obtain each event (implementation class of the javax.resource.spi.work.WorkEvent interface).
  2. Allocating work to a free thread
    The J2EE server allocates a free thread to Work registered in WorkManager, and executes the run method implemented in Work.
  3. Terminating Work and calling back the threads
    The J2EE server calls back the thread, which was allocated to the processed Work, to the thread pool.
    The called back thread returns to the pool and waits or is released according to the settings for thread pooling.

Note that if an exception occurs in the methods of the javax.resource.spi.work.Work interface or javax.resource.spi.work.WorkListener interface during this procedure, the KDJE48592-E or KDJE48593-E message is output respectively.

The following figure shows the transition in the state of Work registered in WorkManager.

Figure 3-42 Transition of Work state

[Figure]

Note that the time at which a method is returned varies according to the method used for registering Work in WorkManager. The following table and figure show the times at which each method is returned. Note that apart from the time at which the method is returned, there is no difference in the processing of these methods.

Table 3-65 Times at which the methods are returned

MethodReturn timing
scheduleWorkRegisters Work and returns immediately.
startWorkReturns when a thread is allocated to Work.
doWorkReturns when the processing of Work is completed.

Figure 3-43 Time at which the scheduleWork method is returned

[Figure]

Figure 3-44 Time at which the startWork method is returned

[Figure]

Figure 3-45 Time at which the doWork method is returned

[Figure]

(4) Thread pooling

The thread pooling functionality manages the threads allocated to work in a thread pool.

Settings for thread pooling

After you import the resource adapter into the J2EE server, you specify the settings for thread pooling in the <hitachi-connector-property>-<resourceadapter-runtime>-<property> tag of the HITACHI Connector Property file and set up as the property of each resource adapter. For details on the procedure for specifying the settings, see 5.4 Resource adapter property definition in the uCosminexus Application Server Application Setup Guide.

The following table describes the values that can be set in the thread pool.

Table 3-66 Values that can be set in the thread pool

Value that can be set (Property name)Explanation
Maximum number of threads executed concurrently (MaxTPoolSize)Specifies the maximum number of threads executed concurrently in WorkManager.
If there are no free threads when Work is registered, new threads are generated and allocated to Work if the number of threads running in WorkManager is less than this value.
If the number of running threads is equal to this value or more, Work is not accepted and javax.resource.spi.work.WorkRejectedException is thrown.
Minimum number of threads in the thread pool (MinTPoolSize)Specifies the minimum number of threads pooled in the thread pool.
Even if no Work is registered in WorkManager, threads equal to this value are always pooled.
Also, if 0 is specified in this value, threads are not generated until Work is registered.
Maximum survival period until the thread to which no Work is allocated is released [unit: seconds] (TPoolKeepalive)Specifies the period until the threads to which no Work is allocated are released from the thread pool, in seconds.
If no Work is allocated even after the lapse of TPoolKeepalive seconds since the thread became free, that thread is released.
However, the thread is not released if the number of threads existing in the thread pool is only up to the MinTPoolSize value.

For details on the specification method and the specifiable values, see 4.1 HITACHI Connector Property file in the uCosminexus Application Server Application and Resource Definition Reference Guide.

Note that if the lifecycle management functionality is not enabled (when <resourceadapter-class> is not specified in the DD (ra.xml) of the resource adapter), the value of the property that specifies thread pooling is ignored.

Lifecycle of the threads used for work management

The following figure shows the lifecycle of the threads used by the work management functionality.

The lifecycle of a thread varies according to the state of the thread pool and the running threads.

Figure 3-46 Lifecycle of a thread (when there are no free threads in the thread pool and the number of running threads is less than MaxTPoolSize)

[Figure]

Figure 3-47 Lifecycle of a thread (when there are free threads in the thread pool)

[Figure]

Figure 3-48 Lifecycle of a thread (when there are no free threads in the thread pool and the number of running threads has reached MaxTPoolSize)

[Figure]

A thread is generated when the resource adapter invokes the scheduleWork method, startWork method, or doWork method and both the following states are applicable:

When the processing of Work is complete, the thread is in the waiting state in the thread pool. When the next Work is registered, the thread is again in the execution state.

In the thread pool, a thread is released if Work is not allocated even after the lapse of the seconds specified in TPoolKeepalive. However, by releasing that thread, if the number of threads in the thread pool becomes less than MinTPoolSize, the thread is not released.

Relationship between the Message-driven Bean instance pool and thread pooling

The operation when the resource adapter uses Work to invoke the Message-driven Beans varies according to the relationship between the maximum number of instances in the Message-driven Bean instance pool and MaxTPoolSize of the resource adapter.

The following table describes the operations for each relationship between the maximum number of instances in the Message-driven Bean instance pool and MaxTPoolSize of the resource adapter. This operation is executed when one Message-driven Bean is invoked from one resource adapter.

Table 3-67 Operations when the resource adapter invokes the Message-driven Beans using Work

Relationship between the maximum number of instances in the Message-driven Bean instance pool and MaxTPoolSize of the resource adapterOperation
MaxTPoolSize > maximum number of instances in the Message-driven Bean instance poolThe Message-driven Beans can be executed from Work until the maximum number of instances in the Message-driven Bean instance pool is reached.
The Work count exceeding the maximum number of instances in the Message-driven Bean instance pool enters a state of waiting to obtain a Message-driven Bean instance.
MaxTPoolSize = maximum number of instances in the Message-driven Bean instance poolThe Message-driven Beans can be executed from Work until the maximum number of instances in the Message-driven Bean instance pool is reached.
The javax.resource.spi.work.WorkRejectedException exception is thrown for the Work count exceeding the maximum number of instances in the Message-driven Bean instance pool. The state does not change to waiting to obtain instances.
MaxTPoolSize < maximum number of instances in the Message-driven Bean instance poolThe number of concurrently available Message-driven Bean instances becomes the number of MaxTPoolSize. The Message-driven Beans can be executed from Work until the running Work count reaches MaxTPoolSize.
The javax.resource.spi.work.WorkRejectedException exception is thrown for the Work count exceeding MaxTPoolSize. The state does not change to pending.
Hint
You specify the thread pooling of the work management functionality for the resource adapters. On the other hand, you set up the Message-driven Bean instance pool for the Message-driven Beans.
When the resource adapter invokes multiple Message-driven Beans, in the MaxTPoolSize of the resource adapter, you set up the total value considering the number of threads required for each Message-driven Bean.

(5) Work management start and termination processing

The work management start and termination processing is executed when the start and termination processing of the lifecycle management functionality is executed.

The operations executed in each processing are as follows:

Start processing

With the work management start processing, threads are generated according to the settings for thread pooling. If MinTPoolSize is 1 or more, the threads are generated for the value in MinTPoolSize and are stored in the thread pool as free threads.

Termination processing

Some of the content executed in the termination processing differs for a normal termination and for an abnormal or forced termination. Note that abnormal termination occurs when an exception is thrown during the execution of the stop method of the ResourceAdapter interface. Also, forced termination is the termination processing executed by extending the execution of the cjstopapp -force command or cjstopapp -cancel command.

Reference note
When you execute the cjstopsv -f command, the J2EE server is stopped without executing the resource adapter termination processing. Therefore, the processing described here is not executed.
  1. The stop method of the ResourceAdapter interface is invoked for the resource adapter from the J2EE server, and the stop processing is instructed.
    Also, the release method of Work is invoked by extending this processing, and Work is released.
  2. The resource adapter stops accepting new Work.
    This is after the processing in 1 is executed, so normally there is no Work registration request. If there is a Work registration request, javax.resource.spi.work.WorkRejectedException is thrown as an exception.
  3. The system waits until the processing of the Work is completed.
    The system waits until the entire execution of the run method of the running Work is completed.
    Hint
    • If method cancellation is executed for a Message-driven Bean invoked from Work, the Message-driven Bean is terminated forcefully. However, in that case, the processing of the running Work does not stop.
    • If a Message-driven Bean is invoked from Work, the Message-driven Bean is terminated before the resource adapter. If you invoke a Message-driven Bean from Work after the Message-driven Bean is terminated, and if you invoke the createEndpoint method of javax.resource.spi.endpoint.MessageEndpointFactory, an exception is thrown.
      For details, see 3.16.3 Message inflow.

(6) Notes on using the work management functionality