org.argeo.jcr/src/org/argeo/jcr/JcrMonitor.java

   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 }