commonj.work
Interface WorkManager

public interface WorkManager

The WorkManager is the abstraction for dispatching and monitoring asynchronous work and is a factory for creating application short or long lived Works.

WorkManagers are created by the server administrator. The vendor specific systems management console allows the administrator to create one or more WorkManagers and associate a JNDI name with each one. The administrator may specify implementation specific information such as min/max Works for each WorkManager. An application that requires a WorkManager should declare a resource-ref in the EJB or webapp that needs the WorkManager. The vendor descriptor editor or J2EE IDE 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>commonj.work.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 res-auth and res-sharing scopes are ignored in this version of the specification. The EJB or servlet can then use the WorkManager as it needs to.

A WorkManager can also be a pinned WorkManager. This is a WorkManager obtained using the RemoteWorkItem.getWorkManager method. This allows subsequent scheduleWorks to be send to the same remote WorkManager as the one that is associated with the RemoteWorkItem. Pinned WorkManagers are only supported on vendor implementations that support remote Works. However, applications that follow the programming model will work on all implementations however serializable Works will be executed within the local JVM only on those implementations.

See Also:

Work, RemoteWorkItem

Field Summary

static long	IMMEDIATE This constant can be used as a timeout for the waitForXXX methods.
static long	INDEFINITE This constant can be used as a timeout for either the waitForXXX methods.

Method Summary

WorkItem	schedule(Work work) Dispatches a Work asynchronously.
WorkItem	schedule(Work work, WorkListener wl) Dispatches a Work asynchronously.
boolean	waitForAll(java.util.Collection workItems, long timeout_ms) Wait for all WorkItems in the collection to finish successfully or otherwise.
java.util.Collection	waitForAny(java.util.Collection workItems, long timeout_ms) Wait for any of the WorkItems in the collection to finish.

Field Detail

IMMEDIATE

public static final long IMMEDIATE

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

See Also:

Constant Field Values

INDEFINITE

public static final long INDEFINITE

This constant can be used as a timeout for either the waitForXXX methods. It indicates a block forever intention when used with waitForXXX

See Also:

Constant Field Values

Method Detail

schedule

public WorkItem schedule(Work work)
                  throws WorkException,
                         java.lang.IllegalArgumentException

Dispatches a Work asynchronously. The work is dispatched and the method returns immediately. The J2EE context of the caller is used to execute the Work.

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

If this WorkManager is a pinned one, i.e. one obtained using RemoteWorkItem.getPinnedWorkManager() and that JVM that it represents has failed then a WorkRejectedException will be thrown even if the remote JVM restarts. The pinned WorkManager must be refreshed by using a normal WorkManager and then acquiring a new pinned WorkManager.

Parameters:

work - the Work to execute.

Returns:

the workitem representing the asynchronous work. If the Work is serializable then a RemoteWorkItem is always returned.

Throws:

If - queuing this up results in an exception then a WorkException is thrown.

java.lang.IllegalArgumentException - This is thrown if work is an Enterprise Bean.

WorkException

schedule

public WorkItem schedule(Work work,
                         WorkListener wl)
                  throws WorkException,
                         java.lang.IllegalArgumentException

Dispatches a Work asynchronously. The work is dispatched and the method returns immediately. The J2EE context of the caller is used to execute the Work.

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

The WorkListener methods are called using the J2EE context of the caller as the Work progresses through processing.

If this WorkManager is a pinned one, i.e. one obtained using RemoteWorkItem.getPinnedWorkManager() and that JVM that it represents has failed then a WorkRejectedException will be thrown even if the remote JVM restarts. The pinned WorkManager must be refreshed by using a normal WorkManager and then acquiring a new pinned WorkManager.

Parameters:

work - the Work to execute.

wl - can be null or a WorkListener which is used to inform the application of the progress of a Work.

Returns:

The workitem representing the asynchronous work. If the Work is serializable then a RemoteWorkItem is always returned.

Throws:

WorkException - If queuing this up results in an exception then a WorkException is thrown.

java.lang.IllegalArgumentException - thrown if work is an Enterprise Bean or

waitForAll

public boolean waitForAll(java.util.Collection workItems,
                          long timeout_ms)

Wait for all WorkItems in the collection to finish successfully or otherwise. All non-WorkItem elements in the collection are ignored. Once this is called then a copy is taken of the workItems. Changes during wait have no effect. WorkItems from different WorkManagers can be placed in a single collection and waited on together.

Parameters:

timeout_ms - the timout in milliseconds. If this is 0 then this method returns immediately.

Returns:

true if all WorkItems have completed, false if the timeout has expired.

waitForAny

public java.util.Collection waitForAny(java.util.Collection workItems,
                                       long timeout_ms)

Wait for any of the WorkItems in the collection to finish. If there are no WorkItems in the list then it returns immediately indicating a timeout. WorkItems from different WorkManagers can be placed in a single collection and waited on together.

Parameters:

timeout_ms - the timeout in ms. If this is 0 then the method returns immediately, i.e. does not block.

Returns:

the WorkItems that have completed or null if it time out expires before any finished.