WorkManager


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  package javax.resource.spi.work;
25  
26  import java.lang.Object  ;
27  import java.lang.Runnable  ;
28  import java.lang.Exception  ;
29  import java.lang.Throwable  ;
30  
31  /**
32   * This interface models a <code>WorkManager</code> which provides a facility
33   * to submit <code>Work</code> instances for execution. This frees the user
34   * from having to create Java threads directly to do work. Further, this
35   * allows efficient pooling of thread resources and more control over thread
36   * usage.
37   *
38   * The various stages in <code>Work</code> processing are:
39   * <ul>
40   * <li> work submit: A <code>Work</code> instance is being submitted for 
41   * execution. The <code>Work</code> instance could either be accepted or 
42   * rejected with a <code>WorkRejectedException</code> set to an appropriate
43   * error code. </li>
44   *
45   * <li> work accepted: The submitted <code>Work</code> instance has been 
46   * accepted. The accepted <code>Work</code> instance could either start 
47   * execution or could be rejected again with a 
48   * <code>WorkRejectedException</code> set to an appropriate error code.
49   * There is no guarantee on when the  execution would start unless a start 
50   * timeout duration is specified. When a start timeout is specified, the 
51   * <code>Work</code> execution must be started within the specified  
52   * duration (not a  real-time guarantee), failing which a 
53   * <code>WorkRejectedException</code> set to an error code 
54   * (<code>WorkRejected.TIMED_OUT</code>) is thrown. </li>
55   *
56   * <li> work rejected: The <code>Work</code> instance has  been rejected. 
57   * The <code>Work</code> instance could be rejected during <code>Work</code>
58   * submittal  or after the <code>Work</code> instance has been accepted 
59   * (but before Work instance starts execution). The rejection could be due 
60   * to internal factors or start timeout expiration. A 
61   * <code>WorkRejectedException</code> with an appropriate error code 
62   * (indicates the reason) is thrown in both cases. </li>
63   *
64   * <li> work started: The execution of the <code>Work</code> 
65   * instance has started. This means that a thread
66   * has been allocated for its execution. But this  
67   * does not guarantee that the allocated thread has been scheduled to run 
68   * on a CPU resource. Once execution is started, the allocated thread 
69   * sets up an appropriate execution context (transaction , security, etc)
70   * and calls Work.run(). Note, any exception thrown during execution context
71   * setup or Work.run() leads to completion of processing. </li>
72   *
73   * <li> work completed: The execution of the <code>Work</code> has been 
74   * completed. The execution could complete with or without an exception.
75   * The <code>WorkManager</code> catches any exception thrown during 
76   * <code>Work</code> processing (which includes execution context setup), 
77   * and wraps it with a <code>WorkCompletedException</code>. </li>
78   * </ul>
79   *
80   * @version 1.0
81   * @author  Ram Jeyaraman
82   */
83  public interface WorkManager {
84  
85      /**
86       * A constant to indicate timeout duration. A zero timeout value indicates
87       * an action be performed immediately.
88       */
89      long IMMEDIATE = 0L;
90  
91      /**
92       * A constant to indicate timeout duration. A maximum timeout value 
93       * indicates that an action be performed arbitrarily without any time 
94       * constraint.
95       */
96      long INDEFINITE = Long.MAX_VALUE;
97  
98      /**
99       * A constant to indicate an unknown start delay duration or other unknown
100      * values.
101      */
102     long UNKNOWN = -1;
103 
104     /**
105      * Accepts a <code>Work</code> instance for processing. This call
106      * blocks until the <code>Work</code> instance completes execution.
107      * There is no guarantee on when the accepted <code>Work</code> 
108      * instance would start execution ie., there is no time constraint 
109      * to start execution.
110      *
111      * @param work The unit of work to be done.  
112      * Could be long or short-lived.
113      *
114      * @throws WorkRejectedException indicates that a 
115      * <code>Work</code> instance has been rejected from further processing.
116      * This can occur due to internal factors.
117      *
118      * @throws WorkCompletedException indicates that a
119      * <code>Work</code> instance has completed execution with an exception.
120      */
121     void doWork(Work   work) // startTimeout = INDEFINITE
122     throws WorkException  ;
123 
124     /**
125      * Accepts a <code>Work</code> instance for processing. This call
126      * blocks until the <code>Work</code> instance completes execution.
127      *
128      * @param work The unit of work to be done.  
129      * Could be long or short-lived.
130      *
131      * @param startTimeout a time duration (in milliseconds) 
132      * within which the execution of the <code>Work</code> instance must
133      * start. Otherwise, the <code>Work</code> instance is rejected with a
134      * <code>WorkRejectedException</code> set to an appropriate error code 
135      * (<code>WorkRejectedException.TIMED_OUT</code>). Note, this
136      * does not offer real-time guarantees.
137      *
138      * @param execContext an object containing the execution
139      * context with which the submitted <code>Work</code> instance must
140      * be executed.
141      *
142      * @param workListener an object which would be notified
143      * when the various <code>Work</code> processing events (work accepted, 
144      * work rejected, work started, work completed) occur.
145      *
146      * @throws WorkRejectedException indicates that a 
147      * <code>Work</code> instance has been rejected from further processing.
148      * This can occur due to internal factors or start timeout expiration.
149      *
150      * @throws WorkCompletedException indicates that a
151      * <code>Work</code> instance has completed execution with an exception.
152      */
153     void doWork(Work   work, long startTimeout, 
154             ExecutionContext   execContext, WorkListener   workListener) 
155     throws WorkException  ;
156 
157     /**
158      * Accepts a <code>Work</code> instance for processing. This call
159      * blocks until the <code>Work</code> instance starts execution
160      * but not until its completion. There is no guarantee on when
161      * the accepted <code>Work</code> instance would start
162      * execution ie., there is no time constraint to start execution.
163      *
164      * @param work The unit of work to be done.  
165      * Could be long or short-lived.
166      *
167      * @return the time elapsed (in milliseconds) from <code>Work</code>
168      * acceptance until start of execution. Note, this does not offer 
169      * real-time guarantees. It is valid to return -1, if the actual start 
170      * delay duration is unknown.
171      *
172      * @throws WorkRejectedException indicates that a 
173      * <code>Work</code> instance has been rejected from further processing.
174      * This can occur due to internal factors.
175      */
176     long startWork(Work   work) // startTimeout = INDEFINITE
177     throws WorkException  ;
178 
179     /**
180      * Accepts a <code>Work</code> instance for processing. This call
181      * blocks until the <code>Work</code> instance starts execution
182      * but not until its completion. There is no guarantee on when
183      * the accepted <code>Work</code> instance would start
184      * execution ie., there is no time constraint to start execution.
185      *
186      * @param work The unit of work to be done.  
187      * Could be long or short-lived.
188      *
189      * @param startTimeout a time duration (in milliseconds) 
190      * within which the execution of the <code>Work</code> instance must
191      * start. Otherwise, the <code>Work</code> instance is rejected with a
192      * <code>WorkRejectedException</code> set to an appropriate error code 
193      * (<code>WorkRejectedException.TIMED_OUT</code>). Note, this
194      * does not offer real-time guarantees.
195      *
196      * @param execContext an object containing the execution
197      * context with which the submitted <code>Work</code> instance must
198      * be executed.
199      *
200      * @param workListener an object which would be notified
201      * when the various <code>Work</code> processing events (work accepted, 
202      * work rejected, work started, work completed) occur.
203      *
204      * @return the time elapsed (in milliseconds) from <code>Work</code>
205      * acceptance until start of execution. Note, this does not offer 
206      * real-time guarantees. It is valid to return -1, if the actual start 
207      * delay duration is unknown.
208      *
209      * @throws WorkRejectedException indicates that a 
210      * <code>Work</code> instance has been rejected from further processing.
211      * This can occur due to internal factors or start timeout expiration.
212      */
213     long startWork(Work   work, long startTimeout, 
214             ExecutionContext   execContext, WorkListener   workListener) 
215     throws WorkException  ;
216 
217     /**
218      * Accepts a <code>Work</code> instance for processing. This call
219      * does not block and returns immediately once a <code>Work</code>
220      * instance has been accepted for processing. There is no guarantee
221      * on when the submitted <code>Work</code> instance would start
222      * execution ie., there is no time constraint to start execution.
223      *
224      * @param work The unit of work to be done.  
225      * Could be long or short-lived.
226      *
227      * @throws WorkRejectedException indicates that a 
228      * <code>Work</code> instance has been rejected from further processing.
229      * This can occur due to internal factors.
230      */
231     void scheduleWork(Work   work) // startTimeout = INDEFINITE
232     throws WorkException  ;
233 
234     /**
235      * Accepts a <code>Work</code> instance for processing. This call
236      * does not block and returns immediately once a <code>Work</code>
237      * instance has been accepted for processing.
238      *
239      * @param work The unit of work to be done. 
240      * Could be long or short-lived.
241      *
242      * @param startTimeout a time duration (in milliseconds) 
243      * within which the execution of the <code>Work</code> instance must
244      * start. Otherwise, the <code>Work</code> instance is rejected with a
245      * <code>WorkRejectedException</code> set to an appropriate error code 
246      * (<code>WorkRejectedException.TIMED_OUT</code>). Note, this
247      * does not offer real-time guarantees.
248      *
249      * @param execContext an object containing the execution
250      * context with which the submitted <code>Work</code> instance must
251      * be executed.
252      *
253      * @param workListener an object which would be notified
254      * when the various <code>Work</code> processing events (work accepted, 
255      * work rejected, work started, work completed) occur.
256      *
257      * @throws WorkRejectedException indicates that a 
258      * <code>Work</code> instance has been rejected from further processing.
259      * This can occur due to internal factors.
260      */
261     void scheduleWork(Work   work, long startTimeout, 
262             ExecutionContext   execContext, WorkListener   workListener) 
263     throws WorkException  ;
264 }
265
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags