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.
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.
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.
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.
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
The following points describe the procedure shown in the figure:
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
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
Method | Return timing |
---|---|
scheduleWork | Registers Work and returns immediately. |
startWork | Returns when a thread is allocated to Work. |
doWork | Returns when the processing of Work is completed. |
Figure 3-43 Time at which the scheduleWork method is returned
Figure 3-44 Time at which the startWork method is returned
Figure 3-45 Time at which the doWork method is returned
The thread pooling functionality manages the threads allocated to work in a thread pool.
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.
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 3-47 Lifecycle of a thread (when there are free threads in the thread pool)
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)
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.
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 adapter | Operation |
---|---|
MaxTPoolSize > maximum number of instances in the Message-driven Bean instance pool | The 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 pool | The 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 pool | The 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. |
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:
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.
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.