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

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