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