Merge branch 'subtree'
[nikiroo-utils.git] / src / be / nikiroo / utils / Progress.java
1 package be.nikiroo.utils;
2
3 import java.util.ArrayList;
4 import java.util.EventListener;
5 import java.util.HashMap;
6 import java.util.List;
7 import java.util.Map;
8 import java.util.Map.Entry;
9
10 /**
11 * Progress reporting system, possibly nested.
12 *
13 * @author niki
14 */
15 public class Progress {
16 /**
17 * This event listener is designed to report progress events from
18 * {@link Progress}.
19 *
20 * @author niki
21 */
22 public interface ProgressListener extends EventListener {
23 /**
24 * A progression event.
25 *
26 * @param progress
27 * the {@link Progress} object that generated it, not
28 * necessarily the same as the one where the listener was
29 * attached (it could be a child {@link Progress} of this
30 * {@link Progress}).
31 * @param name
32 * the first non-null name of the {@link Progress} step that
33 * generated this event
34 */
35 public void progress(Progress progress, String name);
36 }
37
38 private Progress parent = null;
39 private Object lock = new Object();
40 private String name;
41 private Map<Progress, Double> children;
42 private List<ProgressListener> listeners;
43 private int min;
44 private int max;
45 private double relativeLocalProgress;
46 private double relativeProgress; // children included
47
48 /**
49 * Create a new default unnamed {@link Progress}, from 0 to 100.
50 */
51 public Progress() {
52 this(null);
53 }
54
55 /**
56 * Create a new default {@link Progress}, from 0 to 100.
57 *
58 * @param name
59 * the name of this {@link Progress} step
60 */
61 public Progress(String name) {
62 this(name, 0, 100);
63 }
64
65 /**
66 * Create a new unnamed {@link Progress}, from min to max.
67 *
68 * @param min
69 * the minimum progress value (and starting value) -- must be
70 * non-negative
71 * @param max
72 * the maximum progress value
73 */
74 public Progress(int min, int max) {
75 this(null, min, max);
76 }
77
78 /**
79 * Create a new {@link Progress}, from min to max.
80 *
81 * @param name
82 * the name of this {@link Progress} step
83 * @param min
84 * the minimum progress value (and starting value) -- must be
85 * non-negative
86 * @param max
87 * the maximum progress value
88 */
89 public Progress(String name, int min, int max) {
90 this.name = name;
91 this.children = new HashMap<Progress, Double>();
92 this.listeners = new ArrayList<Progress.ProgressListener>();
93 setMinMax(min, max);
94 setProgress(min);
95 }
96
97 /**
98 * The name of this {@link Progress} step.
99 *
100 * @return the name
101 */
102 public String getName() {
103 return name;
104 }
105
106 /**
107 * The name of this {@link Progress} step.
108 *
109 * @param name
110 * the new name
111 */
112 public void setName(String name) {
113 this.name = name;
114 changed(this, name);
115 }
116
117 /**
118 * The minimum progress value.
119 *
120 * @return the min
121 */
122 public int getMin() {
123 return min;
124 }
125
126 /**
127 * The minimum progress value.
128 *
129 * @param min
130 * the min to set
131 *
132 *
133 * @throws RuntimeException
134 * if min &lt; 0 or if min &gt; max
135 */
136 public void setMin(int min) {
137 if (min < 0) {
138 throw new RuntimeException("negative values not supported");
139 }
140
141 synchronized (lock) {
142 if (min > max) {
143 throw new RuntimeException(
144 "The minimum progress value must be <= the maximum progress value");
145 }
146
147 this.min = min;
148 }
149 }
150
151 /**
152 * The maximum progress value.
153 *
154 * @return the max
155 */
156 public int getMax() {
157 return max;
158 }
159
160 /**
161 * The maximum progress value (must be >= the minimum progress value).
162 *
163 * @param max
164 * the max to set
165 *
166 *
167 * @throws RuntimeException
168 * if max &lt; min
169 */
170 public void setMax(int max) {
171 synchronized (lock) {
172 if (max < min) {
173 throw new Error(
174 "The maximum progress value must be >= the minimum progress value");
175 }
176
177 this.max = max;
178 }
179 }
180
181 /**
182 * Set both the minimum and maximum progress values.
183 *
184 * @param min
185 * the min
186 * @param max
187 * the max
188 *
189 * @throws RuntimeException
190 * if min &lt; 0 or if min &gt; max
191 */
192 public void setMinMax(int min, int max) {
193 if (min < 0) {
194 throw new RuntimeException("negative values not supported");
195 }
196
197 if (min > max) {
198 throw new RuntimeException(
199 "The minimum progress value must be <= the maximum progress value");
200 }
201
202 synchronized (lock) {
203 this.min = min;
204 this.max = max;
205 }
206 }
207
208 /**
209 * Get the total progress value (including the optional children
210 * {@link Progress}) on a {@link Progress#getMin()} to
211 * {@link Progress#getMax()} scale.
212 *
213 * @return the progress the value
214 */
215 public int getProgress() {
216 return (int) Math.round(relativeProgress * (max - min));
217 }
218
219 /**
220 * Set the local progress value (not including the optional children
221 * {@link Progress}), on a {@link Progress#getMin()} to
222 * {@link Progress#getMax()} scale.
223 *
224 * @param progress
225 * the progress to set
226 */
227 public void setProgress(int progress) {
228 synchronized (lock) {
229 double childrenProgress = relativeProgress - relativeLocalProgress;
230
231 relativeLocalProgress = ((double) progress) / (max - min);
232
233 setRelativeProgress(this, name, relativeLocalProgress
234 + childrenProgress);
235 }
236 }
237
238 /**
239 * Get the total progress value (including the optional children
240 * {@link Progress}) on a 0.0 to 1.0 scale.
241 *
242 * @return the progress
243 */
244 public double getRelativeProgress() {
245 return relativeProgress;
246 }
247
248 /**
249 * Set the total progress value (including the optional children
250 * {@link Progress}), on a 0 to 1 scale.
251 *
252 * @param pg
253 * the {@link Progress} to report as the progression emitter
254 * @param name
255 * the current name (if it is NULL, the first non-null name in
256 * the hierarchy will overwrite it) of the {@link Progress} who
257 * emitted this change
258 * @param relativeProgress
259 * the progress to set
260 */
261 private void setRelativeProgress(Progress pg, String name,
262 double relativeProgress) {
263 synchronized (lock) {
264 relativeProgress = Math.max(0, relativeProgress);
265 relativeProgress = Math.min(1, relativeProgress);
266 this.relativeProgress = relativeProgress;
267
268 changed(pg, name);
269 }
270 }
271
272 /**
273 * Get the total progress value (including the optional children
274 * {@link Progress}) on a 0 to 1 scale.
275 *
276 * @return the progress the value
277 */
278 private int getLocalProgress() {
279 return (int) Math.round(relativeLocalProgress * (max - min));
280 }
281
282 /**
283 * Add some value to the current progression of this {@link Progress}.
284 *
285 * @param step
286 * the amount to add
287 */
288 public void add(int step) {
289 synchronized (lock) {
290 setProgress(getLocalProgress() + step);
291 }
292 }
293
294 /**
295 * Check if the action corresponding to this {@link Progress} is done (i.e.,
296 * if its progress value == its max value).
297 *
298 * @return TRUE if it is
299 */
300 public boolean isDone() {
301 return getProgress() == max;
302 }
303
304 /**
305 * Mark the {@link Progress} as done by setting its value to max.
306 */
307 public void done() {
308 synchronized (lock) {
309 double childrenProgress = relativeProgress - relativeLocalProgress;
310 relativeLocalProgress = 1 - childrenProgress;
311 setRelativeProgress(this, name, 1d);
312 }
313 }
314
315 /**
316 * Return the list of direct children of this {@link Progress}.
317 *
318 * @return the children (Who will think of the children??)
319 */
320 public List<Progress> getChildren() {
321 synchronized (lock) {
322 return new ArrayList<Progress>(children.keySet());
323 }
324 }
325
326 /**
327 * Notify the listeners that this {@link Progress} changed value.
328 *
329 * @param pg
330 * the emmiter, that is, the (sub-){link Progress} that just
331 * reported some change, not always the same as <tt>this</tt>
332 * @param name
333 * the current name (if it is NULL, the first non-null name in
334 * the hierarchy will overwrite it) of the {@link Progress} who
335 * emitted this change
336 */
337 private void changed(Progress pg, String name) {
338 if (pg == null) {
339 pg = this;
340 }
341
342 if (name == null) {
343 name = this.name;
344 }
345
346 synchronized (lock) {
347 for (ProgressListener l : listeners) {
348 l.progress(pg, name);
349 }
350 }
351 }
352
353 /**
354 * Add a {@link ProgressListener} that will trigger on progress changes.
355 * <p>
356 * Note: the {@link Progress} that will be reported will be the active
357 * progress, not necessarily the same as the current one (it could be a
358 * child {@link Progress} of this {@link Progress}).
359 *
360 * @param l
361 * the listener
362 */
363 public void addProgressListener(ProgressListener l) {
364 synchronized (lock) {
365 this.listeners.add(l);
366 }
367 }
368
369 /**
370 * Remove a {@link ProgressListener} that would trigger on progress changes.
371 *
372 * @param l
373 * the listener
374 *
375 * @return TRUE if it was found (and removed)
376 */
377 public boolean removeProgressListener(ProgressListener l) {
378 synchronized (lock) {
379 return this.listeners.remove(l);
380 }
381 }
382
383 /**
384 * Add a child {@link Progress} of the given weight.
385 *
386 * @param progress
387 * the child {@link Progress} to add
388 * @param weight
389 * the weight (on a {@link Progress#getMin()} to
390 * {@link Progress#getMax()} scale) of this child
391 * {@link Progress} in relation to its parent
392 *
393 * @throws RuntimeException
394 * if weight exceed {@link Progress#getMax()} or if progress
395 * already has a parent
396 */
397 public void addProgress(Progress progress, double weight) {
398 if (weight < min || weight > max) {
399 throw new RuntimeException(String.format(
400 "Progress object %s cannot have a weight of %f, "
401 + "it is outside of its parent (%s) range (%d)",
402 progress.name, weight, name, max));
403 }
404
405 if (progress.parent != null) {
406 throw new RuntimeException(String.format(
407 "Progress object %s cannot be added to %s, "
408 + "as it already has a parent (%s)", progress.name,
409 name, progress.parent.name));
410 }
411
412 ProgressListener progressListener = new ProgressListener() {
413 @Override
414 public void progress(Progress pg, String name) {
415 synchronized (lock) {
416 double total = relativeLocalProgress;
417 for (Entry<Progress, Double> entry : children.entrySet()) {
418 total += (entry.getValue() / (max - min))
419 * entry.getKey().getRelativeProgress();
420 }
421
422 setRelativeProgress(pg, name, total);
423 }
424 }
425 };
426
427 synchronized (lock) {
428 progress.parent = this;
429 this.children.put(progress, weight);
430 progress.addProgressListener(progressListener);
431 }
432 }
433 }