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 double relativeLocalProgress;
  41         private double relativeProgress; // 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, name);
 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 (int) Math.round(relativeProgress * (max - min));
 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                         double childrenProgress = relativeProgress - relativeLocalProgress;
 225
 226                         relativeLocalProgress = ((double) progress) / (max - min);
 227
 228                         setRelativeProgress(this, name, relativeLocalProgress
 229                                         + childrenProgress);
 230                 }
 231         }
 232
 233         /**
 234          * Get the total progress value (including the optional children
 235          * {@link Progress}) on a 0.0 to 1.0 scale.
 236          *
 237          * @return the progress
 238          */
 239         public double getRelativeProgress() {
 240                 return relativeProgress;
 241         }
 242
 243         /**
 244          * Set the total progress value (including the optional children
 245          * {@link Progress}), on a 0 to 1 scale.
 246          *
 247          * @param pg
 248          *            the {@link Progress} to report as the progression emitter
 249          * @param name
 250          *            the current name (if it is NULL, the first non-null name in
 251          *            the hierarchy will overwrite it) of the {@link Progress} who
 252          *            emitted this change
 253          * @param relativeProgress
 254          *            the progress to set
 255          */
 256         private void setRelativeProgress(Progress pg, String name,
 257                         double relativeProgress) {
 258                 synchronized (getLock()) {
 259                         relativeProgress = Math.max(0, relativeProgress);
 260                         relativeProgress = Math.min(1, relativeProgress);
 261                         this.relativeProgress = relativeProgress;
 262
 263                         changed(pg, name);
 264                 }
 265         }
 266
 267         /**
 268          * Get the total progress value (including the optional children
 269          * {@link Progress}) on a 0 to 1 scale.
 270          *
 271          * @return the progress the value
 272          */
 273         private int getLocalProgress() {
 274                 return (int) Math.round(relativeLocalProgress * (max - min));
 275         }
 276
 277         /**
 278          * Add some value to the current progression of this {@link Progress}.
 279          *
 280          * @param step
 281          *            the amount to add
 282          */
 283         public void add(int step) {
 284                 synchronized (getLock()) {
 285                         setProgress(getLocalProgress() + step);
 286                 }
 287         }
 288
 289         /**
 290          * Check if the action corresponding to this {@link Progress} is done (i.e.,
 291          * if its progress value == its max value).
 292          *
 293          * @return TRUE if it is
 294          */
 295         public boolean isDone() {
 296                 return relativeProgress >= 1d;
 297         }
 298
 299         /**
 300          * Mark the {@link Progress} as done by setting its value to max.
 301          */
 302         public void done() {
 303                 setProgress(getMax());
 304         }
 305
 306         /**
 307          * Return the list of direct children of this {@link Progress}.
 308          *
 309          * @return the children (Who will think of the children??)
 310          */
 311         public Set<Progress> getChildren() {
 312                 return children.keySet();
 313         }
 314
 315         /**
 316          * Notify the listeners that this {@link Progress} changed value.
 317          *
 318          * @param pg
 319          *            the emmiter
 320          * @param name
 321          *            the current name (if it is NULL, the first non-null name in
 322          *            the hierarchy will overwrite it) of the {@link Progress} who
 323          *            emitted this change
 324          */
 325         private void changed(Progress pg, String name) {
 326                 if (pg == null) {
 327                         pg = this;
 328                 }
 329
 330                 if (name == null) {
 331                         name = this.name;
 332                 }
 333
 334                 synchronized (getLock()) {
 335                         for (ProgressListener l : listeners) {
 336                                 l.progress(pg, name);
 337                         }
 338                 }
 339         }
 340
 341         /**
 342          * Add a {@link ProgressListener} that will trigger on progress changes.
 343          * <p>
 344          * Note: the {@link Progress} that will be reported will be the active
 345          * progress, not necessarily the same as the current one (it could be a
 346          * child {@link Progress} of this {@link Progress}).
 347          *
 348          * @param l
 349          *            the listener
 350          */
 351         public void addProgressListener(ProgressListener l) {
 352                 this.listeners.add(l);
 353         }
 354
 355         /**
 356          * Remove a {@link ProgressListener} that would trigger on progress changes.
 357          *
 358          * @param l
 359          *            the listener
 360          *
 361          * @return TRUE if it was found (and removed)
 362          */
 363         public boolean removeProgressListener(ProgressListener l) {
 364                 return this.listeners.remove(l);
 365         }
 366
 367         /**
 368          * Add a child {@link Progress} of the given weight.
 369          *
 370          * @param progress
 371          *            the child {@link Progress} to add
 372          * @param weight
 373          *            the weight (on a {@link Progress#getMin()} to
 374          *            {@link Progress#getMax()} scale) of this child
 375          *            {@link Progress} in relation to its parent
 376          *
 377          * @throws Error
 378          *             if weight exceed {@link Progress#getMax()} or if progress
 379          *             already has a parent
 380          */
 381         public void addProgress(Progress progress, double weight) {
 382                 if (weight < min || weight > max) {
 383                         throw new Error(String.format(
 384                                         "Progress object %s cannot have a weight of %f, "
 385                                                         + "it is outside of its parent (%s) range (%f)",
 386                                         progress.name, weight, name, max));
 387                 }
 388
 389                 if (progress.parent != null) {
 390                         throw new Error(String.format(
 391                                         "Progress object %s cannot be added to %s, "
 392                                                         + "as it already has a parent (%s)", progress.name,
 393                                         name, progress.parent.name));
 394                 }
 395
 396                 progress.addProgressListener(new ProgressListener() {
 397                         @Override
 398                         public void progress(Progress pg, String name) {
 399                                 synchronized (getLock()) {
 400                                         double total = relativeLocalProgress;
 401                                         for (Entry<Progress, Double> entry : children.entrySet()) {
 402                                                 total += (entry.getValue() / (max - min))
 403                                                                 * entry.getKey().getRelativeProgress();
 404                                         }
 405
 406                                         setRelativeProgress(pg, name, total);
 407                                 }
 408                         }
 409                 });
 410
 411                 this.children.put(progress, weight);
 412         }
 413
 414         /**
 415          * The lock object to use (this one or the recursively-parent one).
 416          *
 417          * @return the lock object to use
 418          */
 419         private Object getLock() {
 420                 synchronized (lock) {
 421                         if (parent != null) {
 422                                 return parent.getLock();
 423                         }
 424
 425                         return lock;
 426                 }
 427         }
 428 }