5 Work Management

This chapter, organized as follows, provides an overview of the J2CA work management contract and focuses on how to use the OC4J work management thread pool implementation:

• Overview of the Work Management Contract

• Using the OC4J Work Management Thread Pool

Overview of the Work Management Contract

This section discusses the basic essentials of the J2CA work management contract, covering the following topics:

• Understanding the Need for the Work Management Contract

• Introducing the Work Management Model and Key APIs

Understanding the Need for the Work Management Contract

While some resource adapters may be relatively simple, passively executing in the context of a single application thread, a typical resource adapter is multitasking and requires multiple threads to perform all its duties. These duties may include listening to a network endpoint or communicating with a network peer, in addition to performing internal work or calling application components.

It is possible for a resource adapter to create its own threads; however, because an application server is designed to manage all system resources and knows the overall state of the runtime environment, it is advantageous to allow the application server to create and manage the threads instead. This is the best way to ensure optimal system efficiency, manageability, and security. (For example, an application server may maintain a pool of threads to be shared by all deployed resource adapters.) In fact, an application server may prevent a resource manager from managing threads.

The purpose of the J2CA work management contract, between an application server and a resource adapter, is to provide a mechanism for resource adapters to use threads that are created and managed by the application server. Under the contract, a resource adapter submits work units to an application server for execution, and the application server work manager uses threads under its management to perform the work.

Introducing the Work Management Model and Key APIs

Interfaces and classes to implement the J2CA work management model are in the javax.resource.spi.work package.

A resource adapter implements the Work interface, instances of which represent units of work that the resource adapter submits to the application server for processing. The Work interface inherits a run() method, executed to perform the work, and specifies a release() method, which the application server may use to indicate that work should be completed as soon as possible.

An application server, such as OC4J, implements the WorkManager interface in order to manage work units. This interface specifies methods to do work (blocking until the work is completed), start work (blocking only until the work is started), and schedule work (returning as soon as the work unit has been accepted for processing). Each of these methods takes a Work instance as input. The doWork() method is for synchronous work, while the scheduleWork() method is for asynchronous work. The startWork() method guarantees first-in/first-out execution, and the work manager can optionally keep track of elapsed time between the acceptance and beginning of execution of a work unit.

A resource adapter obtains a WorkManager instance from the application server, creates Work instances for the units of work to be accomplished, and passes the Work instances to the WorkManager instance when it calls any of the methods to accomplish work. Optionally, a resource adapter may also pass the following to any of the WorkManager methods:

• An ExecutionContext instance, which models a context in which to execute the work unit, such as for transaction and security functionality.

• A WorkListener instance, which provides a callback event listener that is notified when work processing events occur. The notification mechanism includes methods, called by the application server, to indicate that work has been accepted, rejected, started, or completed.

The work manager may throw two types of work management exceptions: WorkCompletedException, indicating that a submitted Work instance completed but with an exception, or WorkRejectedException, indicating that a submitted Work instance was rejected. These exceptions can also be passed by the work manager to the resource adapter through the WorkListener mechanism, which is especially useful with asynchronous work submissions. Each of the WorkListener methods workAccepted(), workRejected(), workStarted(), and workCompleted() takes a WorkEvent instance as input. When a WorkEvent instance is created, it takes a Work instance and applicable work exception instance as input. (WorkCompletedException and WorkRejectedException are subclasses of WorkException, which is a subclass of javax.resource.ResourceException.)

The application server maintains a pool of threads to be used for work management. When a Work instance is submitted, it is picked up by a free thread for execution. The thread sets up an appropriate execution context and calls the run() method to perform the work. When work is complete, the application server is free to reuse the thread. Alternatively, depending on load circumstances, the application server may at any time call a Work instance release() method, from a separate thread, to try to reclaim the thread. This does not mandate any action by the resource adapter, but hints that it should release the active thread executing the work. The resource adapter should use threads carefully, monitor such hints, and perform any appropriate cleanup.

Each application server provides its own thread pool implementation, although all threads used in executing work units must be of the same priority level.

Using the OC4J Work Management Thread Pool

OC4J provides a configurable global thread pool specifically for use by deployed resource adapters. The following sections give an overview and discuss OC4J configuration and metrics features:

• Overview of the Work Management Thread Pool

• Configuring the Work Management Thread Pool

• Using Metrics for the Work Management Thread Pool

Overview of the Work Management Thread Pool

OC4J supports different types of thread pools, with one of them being specifically for use by resource adapters for work management. The work management thread pool operates independently of the others, but each pool supports the same basic set of features, being configurable for the following:

• Minimum number of threads that must exist in the pool

• Maximum number of threads that can execute simultaneously in the pool

• Maximum number of requests that can be in the queue waiting for a thread

• Time (in milliseconds) to keep a thread alive waiting for a request to service, after which the thread is destroyed

If the number of threads in the pool is under the minimum, OC4J will add a new thread rather than put a request in the queue. Otherwise, OC4J will queue the request rather than adding a new thread. OC4J generally attempts to keep the number of threads at or near the minimum, unless the queue is full.

See the Oracle Containers for J2EE Configuration and Administration Guide for more information about OC4J thread pools.

Configuring the Work Management Thread Pool

OC4J thread pools, including the thread pool for resource adapter work management, are configured in the OC4J server.xml file, through subelements of the top-level <application-server> element. You can configure the work management thread pool through the <work-manager-thread-pool> subelement or through Application Server Control.

In the Application Server Control Console, you can update attributes of the work management MBean, which is accessible through the System MBean Browser:

1. From the OC4J Home page, select the Administration tab.

2. From the Administration tab, under JMX, go to the System MBean Browser task.

   The System MBean Browser lists the system MBeans on the left and information about the selected MBean on the right.

3. Under ThreadPool in the left frame, select the WorkManager MBean; for example, WorkManager_0.

   The Attributes tab lists the attributes of the work management thread pool, with descriptions and values. You can edit the values of attributes that have RW (read/write) access.

4. Apply any changes.

Note: The Apply Changes button will be visible only if the browser page contains at least one attribute with a modifiable value.

Alternatively, you can use the <work-manager-thread-pool> subelement of <application-server> to configure the work management thread pool. (Other OC4J thread pools are configured through the <global-thread-pool> element.) The <work-manager-thread-pool> attributes are documented in Table 5-1.

Table 5-1 Configuration Attributes for Work Management Thread Pool

Parameter	Description	Default Value
min	Minimum number of threads to exist in the pool	1
max	Maximum number of threads to execute simultaneously in the pool	Integer.MAX_VALUE (essentially, no maximum)
queue	Maximum number of requests (Work instances) in the queue, waiting for a thread	0
keepAlive	Number of milliseconds to keep a thread alive while it waits for a request to service	600,000 (10 minutes)
debug	Flag to enable output of diagnostic information for the thread pool	false

The following example enables the debug flag and declares a thread pool with a minimum of 10 threads, a maximum of 100 executing threads, a queue size of 200 requests, and a keep-alive time of 60 seconds:

<application-server ... >
   ...
   <work-manager-thread-pool min="10" max="100" queue="200" 
                             keepAlive="60000" debug="true" />
   ...
</application-server>

See the Oracle Containers for J2EE Configuration and Administration Guide for more information about configuring OC4J thread pools in the server.xml file.

Using Metrics for the Work Management Thread Pool

Dynamic Monitoring Service (DMS) metrics for the resource adapter work management thread pool are under /oc4j/WorkManagementPool in the DMS hierarchy. There are two categories of metrics for the thread pool, one indicating thread pool configuration values as shown in Table 5-2, and the other indicating thread pool execution state as shown in Table 5-3.

Note: DMS adds performance-monitoring features to a number of Oracle Application Server components, including OC4J. The goal of DMS is to provide information about runtime behavior through built-in performance measurements so that users can diagnose, analyze, and debug any performance problems. DMS provides this information in a package that can be used at any time, including during live deployment. Data are published through HTTP and can be viewed with a browser. For general information about how to use DMS, the built-in DMS metrics that are available, and other OC4J performance considerations, refer to the Oracle Application Server Performance Guide.

Table 5-2 DMS Metrics for Work Management Thread Pool Configuration

Metric	Description
minPoolSize	Indicates the minimum number of threads to exist in the pool. This corresponds to the wm-min configuration attribute.
maxPoolSize	Indicates the maximum number of threads to execute simultaneously in the pool. This corresponds to the wm-max configuration attribute.
maxQueueSize	Indicates the maximum number of requests (Work instances) in the queue, waiting to be serviced by a thread. This corresponds to the wm-queue configuration attribute.
keepAlive	Indicates the number of milliseconds to keep a thread alive while it waits for a request to service. This corresponds to the wm-keepAlive configuration attribute.

Table 5-3 DMS Metrics for Work Management Thread Pool State

Metric	Description
totalThreadCount	Indicates the total number of threads in the pool.
idleThreadCount	Indicates the number of threads in the pool that are waiting for a request to service.
queueSize	Indicates the number of requests (Work instances) waiting in the queue for a thread to become available.
queueFullEvent	Indicates the number of times that a request was rejected due to a full queue.
workStartDuration	Measures the duration between when a request is accepted and when a thread is allocated to complete the work. (If a thread is readily available, this would measure the processing overhead of the thread pool in finding an available thread and setting up the proper execution context for processing the work. If all available threads are busy handling other requests, this time would also include the queuing time.) Three separate values are expressed for this metric—minimum duration, maximum duration, and average duration.

The following example shows sample DMS output for the work management thread pool:

<statistics>
  /oc4j [type=n/a]
   /oc4j/Work_Management_Pool [type=oc4j_workManagementPool]
    idleThreadCount.level:       NOTIFICATION    
    idleThreadCount.value:       4       threads
    keepAlive.level:     NOTIFICATION    
    keepAlive.value:     600000  milliseconds
    maxPoolSize.level:   NOTIFICATION    
    maxPoolSize.value:   20      threads
    maxQueueSize.level:  NOTIFICATION    
    maxQueueSize.value:  50      work_requests
    minPoolSize.level:   NOTIFICATION    
    minPoolSize.value:   5       threads
    queueFullEvent.count:        0       ops
    queueFullEvent.level:        NOTIFICATION    
    queueSize.level:     NOTIFICATION    
    queueSize.value:     0       work_requests
    totalThreadCount.level:      NOTIFICATION    
    totalThreadCount.value:      5       threads
    workStartDuration.avg:       6.900943396226415       msecs
    workStartDuration.completed: 424     ops
    workStartDuration.level:     NOTIFICATION    
    workStartDuration.maxTime:   34      msecs
    workStartDuration.minTime:   0       msecs
    workStartDuration.time:      2926    msecs
 </statistics>