1 package org.argeo.jcr; 2 3 4 /** 5 * Simple monitor abstraction. Inspired by Eclipse IProgressMOnitor, but without 6 * dependency to it. 7 */ 8 public interface JcrMonitor { 9 /** 10 * Constant indicating an unknown amount of work. 11 */ 12 public final static int UNKNOWN = -1; 13 14 /** 15 * Notifies that the main task is beginning. This must only be called once 16 * on a given progress monitor instance. 17 * 18 * @param name 19 * the name (or description) of the main task 20 * @param totalWork 21 * the total number of work units into which the main task is 22 * been subdivided. If the value is <code>UNKNOWN</code> the 23 * implementation is free to indicate progress in a way which 24 * doesn't require the total number of work units in advance. 25 */ 26 public void beginTask(String name, int totalWork); 27 28 /** 29 * Notifies that the work is done; that is, either the main task is 30 * completed or the user canceled it. This method may be called more than 31 * once (implementations should be prepared to handle this case). 32 */ 33 public void done(); 34 35 /** 36 * Returns whether cancelation of current operation has been requested. 37 * Long-running operations should poll to see if cancelation has been 38 * requested. 39 * 40 * @return <code>true</code> if cancellation has been requested, and 41 * <code>false</code> otherwise 42 * @see #setCanceled(boolean) 43 */ 44 public boolean isCanceled(); 45 46 /** 47 * Sets the cancel state to the given value. 48 * 49 * @param value 50 * <code>true</code> indicates that cancelation has been 51 * requested (but not necessarily acknowledged); 52 * <code>false</code> clears this flag 53 * @see #isCanceled() 54 */ 55 public void setCanceled(boolean value); 56 57 /** 58 * Sets the task name to the given value. This method is used to restore the 59 * task label after a nested operation was executed. Normally there is no 60 * need for clients to call this method. 61 * 62 * @param name 63 * the name (or description) of the main task 64 * @see #beginTask(java.lang.String, int) 65 */ 66 public void setTaskName(String name); 67 68 /** 69 * Notifies that a subtask of the main task is beginning. Subtasks are 70 * optional; the main task might not have subtasks. 71 * 72 * @param name 73 * the name (or description) of the subtask 74 */ 75 public void subTask(String name); 76 77 /** 78 * Notifies that a given number of work unit of the main task has been 79 * completed. Note that this amount represents an installment, as opposed to 80 * a cumulative amount of work done to date. 81 * 82 * @param work 83 * a non-negative number of work units just completed 84 */ 85 public void worked(int work); 86 87 }