001 /*
002 * JBoss, Home of Professional Open Source.
003 * Copyright 2008, Red Hat Middleware LLC, and individual contributors
004 * as indicated by the @author tags. See the copyright.txt file in the
005 * distribution for a full listing of individual contributors.
006 *
007 * This is free software; you can redistribute it and/or modify it
008 * under the terms of the GNU Lesser General Public License as
009 * published by the Free Software Foundation; either version 2.1 of
010 * the License, or (at your option) any later version.
011 *
012 * This software is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * You should have received a copy of the GNU Lesser General Public
018 * License along with this software; if not, write to the Free
019 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021 */
022
023 package org.jboss.dna.common.monitor;
024
025 import java.util.Locale;
026 import org.jboss.dna.common.collection.Problems;
027 import org.jboss.dna.common.i18n.I18n;
028
029 /**
030 * A basic progress monitor that facilitates the updating and monitoring of progress towards the completion of an activity.
031 * Documentation hereafter will refer to the code in an application that updates progress as the <strong>Updater</strong>, and
032 * code that monitors progress as an <strong>Observer</strong>.
033 * <p>
034 * The progress of each {@link #getActivityName() activity} is started when the <strong>Updater</strong> calls
035 * {@link #beginTask(double, I18n, Object...)}, continues with a mixture of work ({@link #worked(double)}) and subtasks ({@link #createSubtask(double)}),
036 * and finishes when the activity is completed ({@link #done()}) or cancelled ({@link #setCancelled(boolean)}).
037 * </p>
038 * <p>
039 * If an activity is interrupted before its normal completion due to a cancellation request by an <strong>Observer</strong>, it
040 * is still the responsibility of the <strong>Updater</strong> to mark the activity as completed. Similarly, if an activity
041 * cannot be cancelled before its normal completion, the <strong>Updater</strong> must deny any previous cancellation request by
042 * calling {@link #setCancelled(boolean) setCancelled(false)}.
043 * </p>
044 *
045 * @author Randall Hauch
046 * @author John Verhaeg
047 */
048 public interface ProgressMonitor {
049
050 /**
051 * Get the name of the activity. This should never change for a progress monitor, and all
052 * {@link #createSubtask(double) subtasks} should have the same name.
053 *
054 * @return the activity's name
055 */
056 String getActivityName();
057
058 /**
059 * Called by the <strong>Updater</strong> to indicate work has started on the task, specifying the total amount of work that
060 * this task constitutes.
061 *
062 * @param totalWork the total number of work units for the task
063 * @param name the name of the task
064 * @param params the parameters for localization
065 */
066 void beginTask( double totalWork,
067 I18n name,
068 Object... params );
069
070 /**
071 * Called by the <strong>Updater</strong> to report work completed for this task.
072 *
073 * @param work the number of work units that have been worked
074 */
075 void worked( double work );
076
077 /**
078 * Called by the <strong>Updater</strong> to create a subtask with the given about of work. The resulting progress monitor
079 * must be started ({@link #beginTask(double, I18n, Object...)}) and finished ({@link #done()}).
080 *
081 * @param subtaskWork the number of work units for this subtask
082 * @return the progress monitor for the subtask
083 */
084 ProgressMonitor createSubtask( double subtaskWork );
085
086 /**
087 * Called by the <strong>Updater</strong> to mark this activity as complete. This method must be called, even if the activity
088 * has been cancelled.
089 */
090 void done();
091
092 /**
093 * Return whether this activity has completed.
094 *
095 * @return <code>true</code> if this activity has completed.
096 */
097 boolean isDone();
098
099 /**
100 * Called by an <strong>Observer</strong> to request the cancellation of this activity, or by the <strong>Updater</strong>
101 * to deny a prior cancellation request (i.e., when the activity {@link #done() completes} before the <strong>Updater</strong>
102 * recognizes a cancellation request by an <strong>Observer</strong>).
103 *
104 * @param value <code>true</code> if requesting the activity be cancelled.
105 */
106 void setCancelled( boolean value );
107
108 /**
109 * Return whether a request was made by an <strong>Observer</strong> to {@link #setCancelled(boolean) cancel} this activity.
110 *
111 * @return <code>true</code> if this activity has been requested to be cancelled.
112 */
113 boolean isCancelled();
114
115 /**
116 * Return the current status of this activity, localized to the specified locale. This method returns an immutable but
117 * consistent snapshot of the status for this activity. Note that if this instance is a {@link #createSubtask(double) subtask},
118 * this method returns the status of the subtask.
119 *
120 * @param locale the locale in which the status is to be represented; if null, the {@link Locale#getDefault() default locale}
121 * will be used
122 * @return the status of this activity
123 */
124 ProgressStatus getStatus( Locale locale );
125
126 /**
127 * Return the problems encountered during the {@link #getStatus(Locale) progress} made towards completing the associated
128 * {@link #getActivityName() activity}.
129 *
130 * @return the list of problems
131 */
132 Problems getProblems();
133 }