WorkManager (Java EE 5)

• 工作提交：提交 Work 实例以便执行。可能接受 Work 实例，也可能拒绝并将 WorkRejectedException 设置为相应的错误代码。
• 接受工作：接受提交的 Work 实例。接受的 Work 实例可能开始执行，也可能再次拒绝并将 WorkRejectedException 设置为相应的错误代码。除非指定了启动时间期限，否则不保证开始执行的时间。指定了启动时间时，必须在指定的期限（不是实时保证）内开始执行 Work，否则会失败并抛出错误代码设置为 WorkRejected.TIMED_OUT 的 WorkRejectedException。
• 拒绝工作：拒绝 Work 实例。在 Work 提交期间，或者在接受 Work 实例之后（但在 Work 实例开始执行之前）可能会拒绝 Work 实例。拒绝的原因可能是内部因素或者启动时间超时。在这两种情况下，都抛出带有相应错误代码（指示原因）的 WorkRejectedException。
• 开始工作：开始执行 Work 实例。这意味着已经为其执行分配了一个线程。但这并不保证已经安排了分配的线程在 CPU 资源上运行。开始执行之后，分配的线程设置相应的执行上下文（事务、安全等等）并调用 Work.run()。注意，在执行上下文设置或 Work.run() 期间抛出的任何异常将导致处理完成。
• 工作完成：完成 Work 的执行。执行完成时可能带有异常，也可能没有异常。WorkManager 在 Work 处理（包括执行上下文设置）期间捕获任何异常，并用 WorkCompletedException 包装。

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:

• work submit: A Work instance is being submitted for execution. The Work instance could either be accepted or rejected with a WorkRejectedException set to an appropriate error code.
• work accepted: The submitted Work instance has been accepted. The accepted Work instance could either start execution or could be rejected again with a WorkRejectedException set to an appropriate error code. There is no guarantee on when the execution would start unless a start timeout duration is specified. When a start timeout is specified, the Work execution must be started within the specified duration (not a real-time guarantee), failing which a WorkRejectedException set to an error code (WorkRejected.TIMED_OUT) is thrown.
• work rejected: The Work instance has been rejected. The Work instance could be rejected during Work submittal or after the Work instance has been accepted (but before Work instance starts execution). The rejection could be due to internal factors or start timeout expiration. A WorkRejectedException with an appropriate error code (indicates the reason) is thrown in both cases.
• work started: The execution of the Work instance has started. This means that a thread has been allocated for its execution. But this does not guarantee that the allocated thread has been scheduled to run on a CPU resource. Once execution is started, the allocated thread sets up an appropriate execution context (transaction , security, etc) and calls Work.run(). Note, any exception thrown during execution context setup or Work.run() leads to completion of processing.
• work completed: The execution of the Work has been completed. The execution could complete with or without an exception. The WorkManager catches any exception thrown during Work processing (which includes execution context setup), and wraps it with a WorkCompletedException.

Version:

1.0

Author:

Ram Jeyaraman

英文文档：

IMMEDIATE

static final long IMMEDIATE

A constant to indicate timeout duration. A zero timeout value indicates an action be performed immediately.

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

public void doWork(Work work) throws WorkException
接受 Work 实例以便进行处理。在 Work 实例完成执行前，此调用一直阻塞。不保证接受的 Work 实例何时开始执行，即对开始执行没有时间限制。

work	要完成的工作单位。时间可长可短。
Throws	WorkRejectedException: 指示进一步处理时拒绝了 Work 实例。这可能是由内部因素引起的。
Throws	WorkCompletedException: 指示 Work 实例完成了执行，但有一个异常。

英文文档：

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.

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

public void doWork(Work work, long startTimeout, ExecutionContext execContext, WorkListener workListener) throws WorkException
接受 Work 实例以便进行处理。在 Work 实例完成执行前，此调用一直阻塞。

work	要完成的工作单位。时间可长可短。
startTimeout	一个时间范围（以毫秒为单位），在这段时间内必须开始执行 Work 实例。否则，Work 实例将被拒绝，并抛出设置为相应错误代码 (WorkRejectedException.TIMED_OUT) 的 WorkRejectedException。注意，此方法不提供实时保证。
execContext	包含执行上下文的对象，必须使用该上下文执行提交的 Work 实例。
workListener	当发生多个 Work 处理事件（接受 work、拒绝 work、开始 work、完成 work）时应该通知的对象。
Throws	WorkRejectedException: 指示进一步处理时拒绝了 Work 实例。这可能是由内部因素或者启动时间超时引起的。
Throws	WorkCompletedException: 指示 Work 实例完成了执行，但有一个异常。

英文文档：

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

public long startWork(Work work) throws WorkException
接受 Work 实例以便进行处理。在 Work 实例开始执行但未完成前，此调用一直阻塞。不保证接受的 Work 实例何时开始执行，即对开始执行没有时间限制。

work	要完成的工作单位。时间可长可短。
return	从接受 Work 到开始执行的时间（以毫秒为单位）。注意，此方法不提供实时保证。如果启动延迟期限未知，则返回 -1 是有效的。
Throws	WorkRejectedException: 指示进一步处理时拒绝了 Work 实例。这可能是由内部因素引起的。

英文文档：

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.

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

public long startWork(Work work, long startTimeout, ExecutionContext execContext, WorkListener workListener) throws WorkException
接受 Work 实例以便进行处理。在 Work 实例开始执行但未完成前，此调用一直阻塞。不保证接受的 Work 实例何时开始执行，即对开始执行没有时间限制。

work	要完成的工作单位。时间可长可短。
startTimeout	一个时间范围（以毫秒为单位），在这段时间内必须开始执行 Work 实例。否则，Work 实例将被拒绝，并抛出设置为相应错误代码 (WorkRejectedException.TIMED_OUT) 的 WorkRejectedException。注意，此方法不提供实时保证。
execContext	包含执行上下文的对象，必须使用该上下文执行提交的 Work 实例。
workListener	当发生多个 Work 处理事件（接受 work、拒绝 work、开始 work、完成 work）时应该通知的对象。
return	从接受 Work 到开始执行的时间（以毫秒为单位）。注意，此方法不提供实时保证。如果启动延迟期限未知，则返回 -1 是有效的。
Throws	WorkRejectedException: 指示进一步处理时拒绝了 Work 实例。这可能是由内部因素或者启动时间超时引起的。

英文文档：

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

public void scheduleWork(Work work) throws WorkException
接受 Work 实例以便进行处理。此调用不会阻塞，接受了 Work 进行处理后便立即返回。不保证提交的 Work 实例何时开始执行，即对开始执行没有时间限制。

work	要完成的工作单位。时间可长可短。
Throws	WorkRejectedException: 指示进一步处理时拒绝了 Work 实例。这可能是由内部因素引起的。

英文文档：

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.

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

public void scheduleWork(Work work, long startTimeout, ExecutionContext execContext, WorkListener workListener) throws WorkException
接受 Work 实例以便进行处理。此调用不会阻塞，接受了 Work 进行处理后便立即返回。

work	要完成的工作单位。时间可长可短。
startTimeout	一个时间范围（以毫秒为单位），在这段时间内必须开始执行 Work 实例。否则，Work 实例将被拒绝，并抛出设置为相应错误代码 (WorkRejectedException.TIMED_OUT) 的 WorkRejectedException。注意，此方法不提供实时保证。
execContext	包含执行上下文的对象，必须使用该上下文执行提交的 Work 实例。
workListener	当发生多个 Work 处理事件（接受 work、拒绝 work、开始 work、完成 work）时应该通知的对象。
Throws	WorkRejectedException: 指示进一步处理时拒绝了 Work 实例。这可能是由内部因素引起的。

英文文档：

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

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.