Skip Headers

Oracle® Containers for J2EE Resource Adapter Administrator's Guide 10g Release 3 (10.1.3) B14436-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 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.

### Introduc ing 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

### Overvie w 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.

### Config uring 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)
deb ug | 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 Met rics 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>