1 /*
2 * Copyright 2010 Capgemini
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 *
15 */
16 package net.sf.appstatus.core.batch;
17
18 import java.util.Date;
19
20 import org.slf4j.Logger;
21
22 /**
23 * Monitor dedicated to monitor a job execution.
24 * <p>
25 * Usage :
26 * <p>
27 * <code>IBatchProgressMonitor monitor, getBatchProgressMonitor("name",
28 * "group", "uuid");<br/>
29 * <br/>
30 * // get item list<br/>
31 * monitor.beginTask( "taskName", "taskDescr", 2 );<br/>
32 * monitor.setCurrentItem( "1" ) ;<br/>
33 * <br/>
34 * // Do some work on item 1;<br/>
35 * <br/>
36 * monitor.worked(1);<br/>
37 * monitor.setCurrentItem( "2" ) ;<br/>
38 * <br/>
39 * // Do some work on item 2;<br/>
40 * <br/>
41 * monitor.worked(1);<br/>
42 * monitor.done();
43 *
44 * </code>
45 *
46 *
47 * @author Guillaume Mary
48 * @author Nicolas Richeton
49 *
50 */
51 public interface IBatchProgressMonitor {
52
53 /**
54 * Unknown amount of work.
55 */
56 public static final int UNKNOW = -1;
57
58 /**
59 * Begin a task execution.
60 *
61 * @param name
62 * task name
63 * @param description
64 * task description
65 * @param totalWork
66 * task amount of work to be done
67 */
68 void beginTask(String name, String description, int totalWork);
69
70 /**
71 * Create a sub task of this task with the amount of work the subtask
72 * execution will done.
73 *
74 * @param work
75 * work units of the task done by the subtask
76 * @return sub task progress monitor
77 */
78 IBatchProgressMonitor createSubTask(int work);
79
80 /**
81 * Set the task is done.
82 */
83 void done();
84
85 /**
86 * Report global failure.
87 * <p>
88 * Use this when the batch has issued a major error and cannot continue.
89 *
90 * @param reason
91 */
92 void fail(String reason);
93
94 /**
95 * Report global failure.
96 * <p>
97 * Use this when the batch has issued a major error and cannot continue.
98 *
99 * @param reason
100 * @param t
101 * Exception which caused the failure.
102 */
103 void fail(String reason, Throwable t);
104
105 Date getLastUpdate();
106
107 /**
108 * Retrieve the total amount of work for this task.
109 *
110 * @return the total amount of work
111 */
112 int getTotalWork();
113
114 /**
115 * Returns true if cancel has been requested for the current job, usually
116 * from a control UI.
117 *
118 * @return
119 */
120 boolean isCancelRequested();
121
122 /**
123 * Send a message during the task execution.
124 *
125 * @param message
126 * message
127 */
128 void message(String message);
129
130 /**
131 * Reject one item during the task processing.
132 * <p>
133 * Use this when :
134 * <ul>
135 * <li>Item processing has failed (exception, invalid data, connection issue
136 * ..) and a human action is probably required to before retry.</li>
137 * <li>The batch is able to go on and process other items (item processing
138 * is independent).</li>
139 * </ul>
140 * <p>
141 *
142 * @see IBatchProgressMonitor#reject(String, String, Throwable)
143 * IBatchProgressMonitor#reject(String, String, Throwable) can be used
144 * to provide the exception which has caused the failure.
145 *
146 * @param itemId
147 * rejected item id
148 * @param reason
149 * the reason
150 */
151 void reject(String itemId, String reason);
152
153 /**
154 * * Reject one item during the task processing.
155 *
156 * @see #reject(String, String)
157 * @param itemId
158 * @param reason
159 * @param e
160 * Exception
161 */
162 void reject(String itemId, String reason, Throwable e);
163
164 /**
165 * Reject a set of items during the task processing.
166 *
167 * @see #reject(String, String)
168 *
169 *
170 * @param itemIds
171 * Array of item ids rejected
172 * @param reason
173 * the reason
174 */
175 void reject(String[] itemIds, String reason);
176
177 /**
178 * Reject a set of items during the task processing.
179 *
180 * @see #reject(String, String)
181 * @param itemIds
182 * @param reason
183 * @param e
184 * Exception
185 */
186 void reject(String[] itemIds, String reason, Throwable e);
187
188 /**
189 * Set the current item which is being processed.
190 *
191 * @param item
192 * current processed item
193 */
194 void setCurrentItem(Object item);
195
196 /**
197 * Set the logger to use for the current batch.
198 *
199 * @param logger
200 */
201 void setLogger(Logger logger);
202
203 /**
204 * Notify the processing of items.
205 *
206 * @param work
207 * items processed
208 */
209 void worked(int work);
210 }