|
IBM WebSphere Application ServerTM Release 7 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface WorkManager
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.
WorkManagerEvents
,
AsynchScope
,
Work
Field Summary | |
---|---|
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 | |
---|---|
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 |
---|
static final int IMMEDIATE
static final long INDEFINITE
static final boolean JOIN_AND
static final boolean JOIN_OR
Method Detail |
---|
WorkItem startWork(WorkWithExecutionContext e) throws WorkException
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.
e
- the J2EE context and the Work to execute.
WorkException
- thrown when the WorkManager is unable to
submit the work to the thread pool queue.WorkItem startWork(WorkWithExecutionContext e, boolean isDaemon) throws WorkException
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.
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.
WorkException
- thrown when the WorkManager is unable to
submit the work to the thread pool queue.WorkItem startWork(WorkWithExecutionContext e, long startTimeOut_ms, WorkListener wl) throws WorkException, java.lang.IllegalArgumentException
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.
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
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.WorkItem startWork(WorkWithExecutionContext e, long startTimeOut_ms, WorkListener wl, boolean isDaemon) throws WorkException, java.lang.IllegalArgumentException
startWork(WorkWithExecutionContext,long,WorkListener)
for more information.
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 thrownisDaemon
- If true, this Work is expected to run a long time and will not
use a pooled thread.
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.WorkItem startWork(Work e) throws WorkException, java.lang.IllegalArgumentException
startWork
method.At most once semantics are provided. If the server fails then the Work will not be executed on restart.
e
- the Work to run asynchronously.
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.WorkItem startWork(Work e, boolean isDaemon) throws WorkException, java.lang.IllegalArgumentException
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.
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.
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.WorkItem startWork(Work e, long startTimeOut_ms, WorkListener wl) throws WorkException, java.lang.IllegalArgumentException
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.
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
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.WorkItem startWork(Work e, long startTimeOut_ms, WorkListener wl, boolean isDaemon) throws WorkException, java.lang.IllegalArgumentException
startWork(WorkWithExecutionContext,long,WorkListener)
for more information.
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 thrownisDaemon
- If true, this Work is expected to run a long time and will not
use a pooled thread.
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.void doWork(WorkWithExecutionContext e) throws WorkException
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.
e
- the J2EE context and the Work to execute.
WorkException
- thrown when the Work throws an exceptionvoid doWork(WorkWithExecutionContext e, WorkListener wl) throws WorkException, java.lang.IllegalArgumentException
doWork(WorkWithExecutionContext)
for more information.The WorkListener methods are called using the startWork caller's J2EE context as the Work progresses.
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
WorkException
- thrown when the Work throws an exception
java.lang.IllegalArgumentException
- can be thrown if the async bean is an Enterprise Java Bean.void doWork(Work e) throws WorkException, java.lang.IllegalArgumentException
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.
e
- the Work to execute.
WorkException
- thrown when the Work throws an exception
java.lang.IllegalArgumentException
- can be thrown if the async bean is an Enterprise Java Bean.void doWork(Work e, WorkListener wl) throws WorkException, java.lang.IllegalArgumentException
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.
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
WorkException
- thrown when the Work throws an exception
java.lang.IllegalArgumentException
- can be thrown if the async bean is an Enterprise Java Bean.boolean join(java.util.ArrayList workItems, boolean ANDOR, int timeout_ms)
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.
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.
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.WorkItem
WorkWithExecutionContext create(Work r) throws java.lang.IllegalArgumentException
java.lang.IllegalArgumentException
- This can be thrown if the async bean is an Enterprise Java Bean.EventSource createEventSource()
|
IBM WebSphere Application ServerTM Release 7 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |