com.ibm.websphere.asynchbeans

Interface WorkManager

All Superinterfaces:

AsynchScopeManager, EventSource

public interface WorkManager
extends AsynchScopeManager

The WorkManager is the abstraction for dispatching and monitoring asynchronous work and is a factory for asynchronous beans. This can generate events. The events which can be generated are documented in the WorkManagerEvents interface. Implement the Events interface and add an instance of this object using the WorkManager.addListener method.

WorkManagers are created by the administrator. The screen for managing WorkManagers can be found by clicking on the Resources/WorkManagers tab in the administrative console. The administrative console, WSADMIN utility and the Config Service API allow administrators to create one or more WorkManagers, each with an associated JNDI name. The administrator can specify information such as the minimum and maximum number of threads for each WorkManager.

An application that requires a WorkManager should declare a resource-ref in the EJB or web application that needs the WorkManager. Tools such as the Application Assembly Toolkit or WebSphere Application Developer can be used to bind this resource-ref to a physical WorkManager at deploy or development time. An EJB or servlet can then get a reference to a WorkManager by looking up the resource-ref name in JNDI and then casting it.

For example, if the resource-ref was called wm/WorkManager:

 <resource-ref>
   <res-ref-name>wm/WorkManager</res-ref-name>
   <res-type>com.ibm.websphere.asynchbeans.WorkManager</res-type>
   <res-auth>Container</res-auth>
   <res-sharing-scope>Shareable</res-sharing-scope>
 </resource-ref>
 

The Java code to look this up would look like:

   InitialContext ic = new InitialContext();
   WorkManager wm = (WorkManager)ic.lookup("java:comp/env/wm/WorkManager");
 

The EJB or servlet can then use the WorkManager as it needs to.

When non-daemon Work is submitted to the WorkManager using one of the start methods, the Work will be submitted to a thread pool. The size of the thread pool is governed by the Min Threads and Max Threads parameters in the WorkManager configuration. The Work Manager configuration supports two custom properties that allow configuring the size of the associated thread pool input buffer and the behavior of the thread pool when it is full. The default behavior of the thread pool is to block all input requests until a thread has been freed. This means that the start() method will not return until a thread has been made available.

See the WebSphere InfoCenter for details on configuring a WorkManager for more details on changing the default behaviors.

See Also:

WorkManagerEvents, AsynchScope, Work

Field Summary

Fields

Modifier and Type	Field and Description
static int	IMMEDIATE This constant can be used as a timeout for the join method.
static long	INDEFINITE This constant can be used as a timeout for either the join method or the startWork methods.
static boolean	JOIN_AND This constant is used for the ANDOR parameter of the join method to indicate that the join method should wait for all work items in the list to complete.
static boolean	JOIN_OR This constant is used for the ANDOR parameter of the join method to indicate that the join method should wait for one of the work items in the list to complete.

Fields inherited from interface com.ibm.websphere.asynchbeans.EventSource

APPLICATION_NOTIFICATION_EVENT_SOURCE, MAX_LISTENER_SEQUENCE_VALUE, MIN_LISTENER_SEQUENCE_VALUE

Method Summary

Methods

Modifier and Type	Method and Description
WorkWithExecutionContext	create(Work r) This returns a Work wrapped with the J2EE context of the caller.
EventSource	createEventSource() This creates a new EventSource.
void	doWork(Work e) Runs a Work object synchronously on the current thread.
void	doWork(WorkWithExecutionContext e) Runs a WorkWithExecutionContext object synchronously on the current thread.
void	doWork(WorkWithExecutionContext e, WorkListener wl) Runs a WorkWithExecutionContext object synchronously on the current thread with an optional WorkListener callback.
void	doWork(Work e, WorkListener wl) Runs a Work object synchronously on the current thread with an optional WorkListener callback.
boolean	join(java.util.ArrayList workItems, boolean ANDOR, int timeout_ms) This returns true if all or one of the the input ArrayList of WorkItem threads has finished.
WorkItem	startWork(Work e) Submits a Work object to run on a thread pool.
WorkItem	startWork(Work e, boolean isDaemon) Optionally executes a Work as a daemon thread.
WorkItem	startWork(Work e, long startTimeOut_ms, WorkListener wl) Submits a Work object to a thread pool with an optional start timeout and a WorkListener callback.
WorkItem	startWork(Work e, long startTimeOut_ms, WorkListener wl, boolean isDaemon) Optionally executes a WorkWithExecutionContext as a daemon thread with an optional start timeout and WorkListener callback.
WorkItem	startWork(WorkWithExecutionContext e) Submits a WorkWithExecutionContext object to run on a thread pool.
WorkItem	startWork(WorkWithExecutionContext e, boolean isDaemon) Optionally executes a WorkWithExecutionContext as a daemon thread.
WorkItem	startWork(WorkWithExecutionContext e, long startTimeOut_ms, WorkListener wl) Submits a WorkWithExecutionContext object to a thread pool with an optional start timeout and a WorkListener callback.
WorkItem	startWork(WorkWithExecutionContext e, long startTimeOut_ms, WorkListener wl, boolean isDaemon) Optionally executes a WorkWithExecutionContext as a daemon thread with an optional start timeout and WorkListener callback.

Methods inherited from interface com.ibm.websphere.asynchbeans.AsynchScopeManager

createAsynchScope, findAsynchScope, findOrCreateAsynchScope

Methods inherited from interface com.ibm.websphere.asynchbeans.EventSource

addListener, addListener, getEventTrigger, getEventTrigger, removeListener

Field Detail

IMMEDIATE

static final int IMMEDIATE

This constant can be used as a timeout for the join method. It indicates a peek action, i.e. return immediately.

See Also:

Constant Field Values

INDEFINITE

static final long INDEFINITE

This constant can be used as a timeout for either the join method or the startWork methods. It indicates a block forever intention when used with join and indicates a start when-ever when used as a start timeout on the startWork method.

See Also:

Constant Field Values

JOIN_AND

static final boolean JOIN_AND

This constant is used for the ANDOR parameter of the join method to indicate that the join method should wait for all work items in the list to complete.

See Also:

Constant Field Values

JOIN_OR

static final boolean JOIN_OR

This constant is used for the ANDOR parameter of the join method to indicate that the join method should wait for one of the work items in the list to complete.

See Also:

Constant Field Values

Method Detail

startWork

WorkItem startWork(WorkWithExecutionContext e)
                   throws WorkException

Submits a WorkWithExecutionContext object to run on a thread pool. The method will normally block until the thread is placed into the thread pool (depending on how the WorkManager is configured) and then will return. The submitted Work will then execute asynchronously.

The WorkWithExecutionContext contains the Work to execute and the J2EE context to execute the work with. This allows delaying execution or propagating context between processes.

At-most-once semantics are implied. If the server fails then the Work will not be executed on restart.

Parameters:

e - the J2EE context and the Work to execute.

Returns:

the WorkItem representing the asynchronous work.

Throws:

WorkException - thrown when the WorkManager is unable to submit the work to the thread pool queue.

startWork

WorkItem startWork(WorkWithExecutionContext e,
                 boolean isDaemon)
                   throws WorkException

Optionally executes a WorkWithExecutionContext as a daemon thread. Daemon threads are desired over pooled threads when they will run for a long time (hours and days versus seconds or minutes). See startWork(WorkWithExecutionContext) for more information.

The life cycle of a Daemon Work is tied to the application that starts it. When the application is stopped, the Daemon Work's release method will be invoked if it is still running. The release method on these should be idempotent. Successive calls to the release method need to be handled since it can be called more than once.

Parameters:

e - the J2EE context and the Work to execute.

isDaemon - If true, this Work is expected to run a long time and will not use a pooled thread.

Returns:

the WorkItem representing the asynchronous work.

Throws:

WorkException - thrown when the WorkManager is unable to submit the work to the thread pool queue.

startWork

WorkItem startWork(WorkWithExecutionContext e,
                 long startTimeOut_ms,
                 WorkListener wl)
                   throws WorkException,
                          java.lang.IllegalArgumentException

Submits a WorkWithExecutionContext object to a thread pool with an optional start timeout and a WorkListener callback. See startWork(WorkWithExecutionContext) for more information.

The startTimeout parameter specifies the period of time in milliseconds in which the execution of the Work instance must start. Otherwise, the Work instance is rejected with a WorkRejectedException with error code WorkRejectedException.TIMED_OUT. Note, this does not offer real-time guarantees as the method may return or the listener may be notified significantly later than when the startTimeout expires.

The WorkListener methods are called using the startWork caller's J2EE context as the Work progresses.

Parameters:

e - the J2EE context and the Work to execute.

startTimeOut_ms - the number of milliseconds that can elapse before the work is rejected while waiting to execute in the thread pool. Use the WorkManager.INDEFINITE constant to disable the timeout.

wl - if not null, the WorkListener methods are called by the WorkManager to inform the application of the progress of a Work. If the WorkListener is an Enterprise Java Bean then an IllegalArgumentException is thrown

Returns:

the WorkItem representing the asynchronous work.

Throws:

WorkException - thrown when the WorkManager is unable to submit the work to the thread pool queue.

java.lang.IllegalArgumentException - can be thrown if the async bean is an Enterprise Java Bean.

startWork

WorkItem startWork(WorkWithExecutionContext e,
                 long startTimeOut_ms,
                 WorkListener wl,
                 boolean isDaemon)
                   throws WorkException,
                          java.lang.IllegalArgumentException

Optionally executes a WorkWithExecutionContext as a daemon thread with an optional start timeout and WorkListener callback. Daemon threads are desired over pooled threads when they will run for a long time See startWork(WorkWithExecutionContext,long,WorkListener) for more information.

Parameters:

e - the J2EE context and the Work to execute.

startTimeOut_ms - the number of milliseconds that can elapse before the work is rejected while waiting to execute in the thread pool. Use the WorkManager.INDEFINITE constant to disable the timeout.

wl - if not null, the WorkListener methods are called by the WorkManager to inform the application of the progress of a Work. If the WorkListener is an Enterprise Java Bean then an IllegalArgumentException is thrown

isDaemon - If true, this Work is expected to run a long time and will not use a pooled thread.

Returns:

the WorkItem representing the asynchronous work.

Throws:

WorkException - thrown when the WorkManager is unable to submit the work to the thread pool queue.

java.lang.IllegalArgumentException - can be thrown if the async bean is an Enterprise Java Bean.

startWork

WorkItem startWork(Work e)
                   throws WorkException,
                          java.lang.IllegalArgumentException

Submits a Work object to run on a thread pool. The method will normally block until the thread is placed into the thread pool (depending on how the WorkManager is configured) and then will return. The submitted Work will then execute asynchronously. The Work will execute with the J2EE context of the method executing the startWork method.

At most once semantics are provided. If the server fails then the Work will not be executed on restart.

Parameters:

e - the Work to run asynchronously.

Returns:

the WorkItem representing the asynchronous work.

Throws:

WorkException - thrown when the WorkManager is unable to submit the work to the thread pool queue.

java.lang.IllegalArgumentException - can be thrown if the async bean is an Enterprise Java Bean.

startWork

WorkItem startWork(Work e,
                 boolean isDaemon)
                   throws WorkException,
                          java.lang.IllegalArgumentException

Optionally executes a Work as a daemon thread. Daemon threads are desired over pooled threads when they will run for a long time (hours and days versus seconds or minutes). See startWork(Work) for more information.

The life cycle of a Daemon Work is tied to the application that starts it. When the application is stopped, the Daemon Work's release method will be invoked if it is still running. The release method on these should be idempotent. Successive calls to the release method need to be handled since it can be called more than once.

Parameters:

e - the Work to run asynchronously.

isDaemon - If true, this Work is expected to run a long time and will not use a pooled thread.

Throws:

WorkException - thrown when the WorkManager is unable to submit the work to the thread pool queue.

java.lang.IllegalArgumentException - can be thrown if the async bean is an Enterprise Java Bean.

startWork

WorkItem startWork(Work e,
                 long startTimeOut_ms,
                 WorkListener wl)
                   throws WorkException,
                          java.lang.IllegalArgumentException

Submits a Work object to a thread pool with an optional start timeout and a WorkListener callback. See startWork(Work) for more information.

The startTimeout parameter specifies the period of time in milliseconds in which the execution of the Work instance must start. Otherwise, the Work instance is rejected with a WorkRejectedException with error code WorkRejectedException.TIMED_OUT. Note, this does not offer real-time guarantees as the method may return or the listener may be notified significantly later than when the startTimeout expires.

The WorkListener methods are called using the startWork caller's J2EE context as the Work progresses.

Parameters:

e - the Work to run asynchronously.

startTimeOut_ms - the number of milliseconds that can elapse before the work is rejected while waiting to execute in the thread pool. Use the WorkManager.INDEFINITE constant to disable the timeout.

wl - if not null, the WorkListener methods are called by the WorkManager to inform the application of the progress of a Work. If the WorkListener is an Enterprise Java Bean then an IllegalArgumentException is thrown

Returns:

the WorkItem representing the asynchronous work.

Throws:

WorkException - thrown when the WorkManager is unable to submit the work to the thread pool queue.

java.lang.IllegalArgumentException - can be thrown if the async bean is an Enterprise Java Bean.

startWork

WorkItem startWork(Work e,
                 long startTimeOut_ms,
                 WorkListener wl,
                 boolean isDaemon)
                   throws WorkException,
                          java.lang.IllegalArgumentException

Optionally executes a WorkWithExecutionContext as a daemon thread with an optional start timeout and WorkListener callback. Daemon threads are desired over pooled threads when they will run for a long time See startWork(WorkWithExecutionContext,long,WorkListener) for more information.

Parameters:

e - the J2EE context and the Work to execute.

startTimeOut_ms - the number of milliseconds that can elapse before the work is rejected while waiting to execute in the thread pool. Use the WorkManager.INDEFINITE constant to disable the timeout.

wl - if not null, the WorkListener methods are called by the WorkManager to inform the application of the progress of a Work. If the WorkListener is an Enterprise Java Bean then an IllegalArgumentException is thrown

isDaemon - If true, this Work is expected to run a long time and will not use a pooled thread.

Returns:

the WorkItem representing the asynchronous work.

Throws:

WorkException - thrown when the WorkManager is unable to submit the work to the thread pool queue.

java.lang.IllegalArgumentException - can be thrown if the async bean is an Enterprise Java Bean.

doWork

void doWork(WorkWithExecutionContext e)
            throws WorkException

Runs a WorkWithExecutionContext object synchronously on the current thread.

The WorkWithExecutionContext contains the Work to execute and the J2EE context to execute the work with. This allows delaying execution or propagating context between processes.

At-most-once semantics are implied. If the server fails then the Work will not be executed on restart.

This work should be short lived when called directly from an application. If the Work will run for a long time then startWork should be used instead.

Parameters:

e - the J2EE context and the Work to execute.

Throws:

WorkException - thrown when the Work throws an exception

doWork

void doWork(WorkWithExecutionContext e,
          WorkListener wl)
            throws WorkException,
                   java.lang.IllegalArgumentException

Runs a WorkWithExecutionContext object synchronously on the current thread with an optional WorkListener callback. See doWork(WorkWithExecutionContext) for more information.

The WorkListener methods are called using the startWork caller's J2EE context as the Work progresses.

Parameters:

e - the J2EE context and the Work to execute.

wl - if not null, the WorkListener methods are called by the WorkManager to inform the application of the progress of a Work. If the WorkListener is an Enterprise Java Bean then an IllegalArgumentException is thrown

Throws:

WorkException - thrown when the Work throws an exception

java.lang.IllegalArgumentException - can be thrown if the async bean is an Enterprise Java Bean.

doWork

void doWork(Work e)
            throws WorkException,
                   java.lang.IllegalArgumentException

Runs a Work object synchronously on the current thread.

At-most-once semantics are implied. If the server fails then the Work will not be executed on restart.

This work should be short lived when called directly from an application. If the Work will run for a long time then startWork should be used instead.

Parameters:

e - the Work to execute.

Throws:

WorkException - thrown when the Work throws an exception

java.lang.IllegalArgumentException - can be thrown if the async bean is an Enterprise Java Bean.

doWork

void doWork(Work e,
          WorkListener wl)
            throws WorkException,
                   java.lang.IllegalArgumentException

Runs a Work object synchronously on the current thread with an optional WorkListener callback.

The WorkListener methods are called using the startWork caller's J2EE context as the Work progresses.

At-most-once semantics are implied. If the server fails then the Work will not be executed on restart.

This work should be short lived when called directly from an application. If the Work will run for a long time then startWork should be used instead.

Parameters:

e - the Work to execute.

wl - if not null, the WorkListener methods are called by the WorkManager to inform the application of the progress of a Work. If the WorkListener is an Enterprise Java Bean then an IllegalArgumentException is thrown

Throws:

WorkException - thrown when the Work throws an exception

java.lang.IllegalArgumentException - can be thrown if the async bean is an Enterprise Java Bean.

join

boolean join(java.util.ArrayList workItems,
           boolean ANDOR,
           int timeout_ms)

This returns true if all or one of the the input ArrayList of WorkItem threads has finished. This operation can optionally block the caller's thread until all or one of the WorkItem threads are complete or until it optionally times-out.

A WorkItem object is returned from each of the startWork methods. If the ArrayList does not contain valid WorkItem instances, then an IllegalArgumentException exception will be thrown.

Parameters:

workItems - the list of WorkItem objects to block on. If the ArrayList contains non-WorkItem objects, then an IllegalArgumentException exception is thrown.

ANDOR - specifies whether we wait for all or one of the work items to complete. Use the WorkManager.JOIN_AND and WorkManager.JOIN_OR constants.

timeout_ms - timeout value in milliseconds to block. If 0 or WorkManager.IMMEDIATE then the current state is immediately returned. If negative then we block indefinitely until the join condition is satisified.

Returns:

true if the join condition is satisfied (all works are complete for WorkManager.JOIN_AND or one work is complete for WorkManager.JOIN_OR), or false if the join condition is not satisfied or a timeout occurs.

See Also:

WorkItem

create

WorkWithExecutionContext create(Work r)
                                throws java.lang.IllegalArgumentException

This returns a Work wrapped with the J2EE context of the caller.

Returns:

the WorkWithExecutionContext wrapping the Work with the current J2EE context.

Throws:

java.lang.IllegalArgumentException - This can be thrown if the async bean is an Enterprise Java Bean.

createEventSource

EventSource createEventSource()

This creates a new EventSource. An EventSource is a flexible source of asynchronous events which is J2EE context aware. It can be used by applications as an asynchronous event dispatcher in event driven applications. These EventSources can be used to fire and receive events within a single JVM, i.e. the one in which the EventSource is created.

Returns:

the new EventSource.