bundles/org.simantics.history/src/org/simantics/history/util/ProgressMonitor.java

   1 /*******************************************************************************
   2  * Copyright (c) 2007, 2012 Association for Decentralized Information Management in
   3  * Industry THTH ry.
   4  * All rights reserved. This program and the accompanying materials
   5  * are made available under the terms of the Eclipse Public License v1.0
   6  * which accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *
   9  * Contributors:
  10  *     VTT Technical Research Centre of Finland - initial API and implementation
  11  *******************************************************************************/
  12 package org.simantics.history.util;
  13
  14 /**
  15  * A custom progress monitor interface for long operations (not using
  16  * Eclipse IProgressMonitor to avoid dependency on Eclipse runtime plug-ins).
  17  *
  18  * @author Tuukka Lehtonen
  19  */
  20 public interface ProgressMonitor {
  21
  22     /**
  23      * Notifies that the main task is beginning.  This must only be called once
  24      * on a given progress monitor instance.
  25      *
  26      * @param name the name (or description) of the main task
  27      * @param totalWork the total number of work units into which
  28      *  the main task is been subdivided. If the value is <code>UNKNOWN</code>
  29      *  the implementation is free to indicate progress in a way which
  30      *  doesn't require the total number of work units in advance.
  31      */
  32     public void beginTask(String name, int totalWork);
  33
  34     /**
  35      * Returns whether cancelation of current operation has been requested.
  36      * Long-running operations should poll to see if cancelation
  37      * has been requested.
  38      *
  39      * @return <code>true</code> if cancellation has been requested,
  40      *    and <code>false</code> otherwise
  41      */
  42     public boolean isCanceled();
  43
  44     /**
  45      * Sets the task name to the given value. This method is used to
  46      * restore the task label after a nested operation was executed.
  47      * Normally there is no need for clients to call this method.
  48      *
  49      * @param name the name (or description) of the main task
  50      * @see #beginTask(java.lang.String, int)
  51      */
  52     public void setTaskName(String name);
  53
  54     /**
  55      * Notifies that a subtask of the main task is beginning.
  56      * Subtasks are optional; the main task might not have subtasks.
  57      *
  58      * @param name the name (or description) of the subtask
  59      */
  60     public void subTask(String name);
  61
  62     /**
  63      * Notifies that a given number of work unit of the main task
  64      * has been completed. Note that this amount represents an
  65      * installment, as opposed to a cumulative amount of work done
  66      * to date.
  67      *
  68      * @param work a non-negative number of work units just completed
  69      */
  70     public void worked(int work);
  71
  72     /**
  73      * @author Tuukka Lehtonen
  74      */
  75     public static class Stub implements ProgressMonitor {
  76         @Override
  77         public void beginTask(String name, int totalWork) {
  78         }
  79         @Override
  80         public boolean isCanceled() {
  81             return false;
  82         }
  83         @Override
  84         public void setTaskName(String name) {
  85         }
  86         @Override
  87         public void subTask(String name) {
  88         }
  89         @Override
  90         public void worked(int work) {
  91         }
  92     }
  93
  94 }