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

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