javax.resource.spi.work
Interface WorkManager

All Known Subinterfaces:
DistributableWorkManager

public interface WorkManager

This interface models a WorkManager which provides a facility to submit Work instances for execution. This frees the user from having to create Java threads directly to do work. Further, this allows efficient pooling of thread resources and more control over thread usage. The various stages in Work processing are:

Version:
1.0
Author:
Ram Jeyaraman

Field Summary
static long IMMEDIATE
          A constant to indicate timeout duration.
static long INDEFINITE
          A constant to indicate timeout duration.
static long UNKNOWN
          A constant to indicate an unknown start delay duration or other unknown values.
 
Method Summary
 void doWork(Work work)
          Accepts a Work instance for processing.
 void doWork(Work work, long startTimeout, ExecutionContext execContext, WorkListener workListener)
          Accepts a Work instance for processing.
 void scheduleWork(Work work)
          Accepts a Work instance for processing.
 void scheduleWork(Work work, long startTimeout, ExecutionContext execContext, WorkListener workListener)
          Accepts a Work instance for processing.
 long startWork(Work work)
          Accepts a Work instance for processing.
 long startWork(Work work, long startTimeout, ExecutionContext execContext, WorkListener workListener)
          Accepts a Work instance for processing.
 

Field Detail

IMMEDIATE

static final long IMMEDIATE
A constant to indicate timeout duration. A zero timeout value indicates an action be performed immediately. The WorkManager implementation must timeout the action as soon as possible.

See Also:
Constant Field Values

INDEFINITE

static final long INDEFINITE
A constant to indicate timeout duration. A maximum timeout value indicates that an action be performed arbitrarily without any time constraint.

See Also:
Constant Field Values

UNKNOWN

static final long UNKNOWN
A constant to indicate an unknown start delay duration or other unknown values.

See Also:
Constant Field Values
Method Detail

doWork

void doWork(Work work)
            throws WorkException
Accepts a Work instance for processing. This call blocks until the Work instance completes execution. There is no guarantee on when the accepted Work instance would start execution ie., there is no time constraint to start execution. (that is, startTimeout=INDEFINITE)

Parameters:
work - The unit of work to be done. Could be long or short-lived.
Throws:
WorkRejectedException - indicates that a Work instance has been rejected from further processing. This can occur due to internal factors.
WorkCompletedException - indicates that a Work instance has completed execution with an exception.
WorkException

doWork

void doWork(Work work,
            long startTimeout,
            ExecutionContext execContext,
            WorkListener workListener)
            throws WorkException
Accepts a Work instance for processing. This call blocks until the Work instance completes execution.

Parameters:
work - The unit of work to be done. Could be long or short-lived.
startTimeout - a time duration (in milliseconds) within which the execution of the Work instance must start. Otherwise, the Work instance is rejected with a WorkRejectedException set to an appropriate error code (WorkRejectedException.TIMED_OUT). Note, this does not offer real-time guarantees.
execContext - an object containing the execution context with which the submitted Work instance must be executed.
workListener - an object which would be notified when the various Work processing events (work accepted, work rejected, work started, work completed) occur.
Throws:
WorkRejectedException - indicates that a Work instance has been rejected from further processing. This can occur due to internal factors or start timeout expiration.
WorkCompletedException - indicates that a Work instance has completed execution with an exception.
WorkException

startWork

long startWork(Work work)
               throws WorkException
Accepts a Work instance for processing. This call blocks until the Work instance starts execution but not until its completion. There is no guarantee on when the accepted Work instance would start execution ie., there is no time constraint to start execution. (that is, startTimeout=INDEFINITE)

Parameters:
work - The unit of work to be done. Could be long or short-lived.
Returns:
the time elapsed (in milliseconds) from Work acceptance until start of execution. Note, this does not offer real-time guarantees. It is valid to return -1, if the actual start delay duration is unknown.
Throws:
WorkRejectedException - indicates that a Work instance has been rejected from further processing. This can occur due to internal factors.
WorkException

startWork

long startWork(Work work,
               long startTimeout,
               ExecutionContext execContext,
               WorkListener workListener)
               throws WorkException
Accepts a Work instance for processing. This call blocks until the Work instance starts execution but not until its completion. There is no guarantee on when the accepted Work instance would start execution ie., there is no time constraint to start execution.

Parameters:
work - The unit of work to be done. Could be long or short-lived.
startTimeout - a time duration (in milliseconds) within which the execution of the Work instance must start. Otherwise, the Work instance is rejected with a WorkRejectedException set to an appropriate error code (WorkRejectedException.TIMED_OUT). Note, this does not offer real-time guarantees.
execContext - an object containing the execution context with which the submitted Work instance must be executed.
workListener - an object which would be notified when the various Work processing events (work accepted, work rejected, work started, work completed) occur.
Returns:
the time elapsed (in milliseconds) from Work acceptance until start of execution. Note, this does not offer real-time guarantees. It is valid to return -1, if the actual start delay duration is unknown.
Throws:
WorkRejectedException - indicates that a Work instance has been rejected from further processing. This can occur due to internal factors or start timeout expiration.
WorkException

scheduleWork

void scheduleWork(Work work)
                  throws WorkException
Accepts a Work instance for processing. This call does not block and returns immediately once a Work instance has been accepted for processing. There is no guarantee on when the submitted Work instance would start execution ie., there is no time constraint to start execution. (that is, startTimeout=INDEFINITE).

Parameters:
work - The unit of work to be done. Could be long or short-lived.
Throws:
WorkRejectedException - indicates that a Work instance has been rejected from further processing. This can occur due to internal factors.
WorkException

scheduleWork

void scheduleWork(Work work,
                  long startTimeout,
                  ExecutionContext execContext,
                  WorkListener workListener)
                  throws WorkException
Accepts a Work instance for processing. This call does not block and returns immediately once a Work instance has been accepted for processing.

Parameters:
work - The unit of work to be done. Could be long or short-lived.
startTimeout - a time duration (in milliseconds) within which the execution of the Work instance must start. Otherwise, the Work instance is rejected with a WorkRejectedException set to an appropriate error code (WorkRejectedException.TIMED_OUT). Note, this does not offer real-time guarantees.
execContext - an object containing the execution context with which the submitted Work instance must be executed.
workListener - an object which would be notified when the various Work processing events (work accepted, work rejected, work started, work completed) occur.
Throws:
WorkRejectedException - indicates that a Work instance has been rejected from further processing. This can occur due to internal factors.
WorkException


Submit a bug or feature

Copyright © 2009-2011, Oracle Corporation and/or its affiliates. All Rights Reserved. Use is subject to license terms.

Generated on 10-February-2011 12:41