| Progress.java |
1 /**
2 * Distribution License:
3 * JSword is free software; you can redistribute it and/or modify it under
4 * the terms of the GNU Lesser General Public License, version 2.1 as published by
5 * the Free Software Foundation. This program is distributed in the hope
6 * that it will be useful, but WITHOUT ANY WARRANTY; without even the
7 * implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
8 * See the GNU Lesser General Public License for more details.
9 *
10 * The License is available on the internet at:
11 * http://www.gnu.org/copyleft/lgpl.html
12 * or by writing to:
13 * Free Software Foundation, Inc.
14 * 59 Temple Place - Suite 330
15 * Boston, MA 02111-1307, USA
16 *
17 * Copyright: 2005
18 * The copyright to this program is held by it's authors.
19 *
20 * ID: $Id: Progress.java 2040 2010-12-04 22:17:15Z dmsmith $
21 */
22 package org.crosswire.common.progress;
23
24 import java.net.URI;
25
26 /**
27 * A Generic way of keeping track of Threads and monitoring their progress.
28 *
29 * @see gnu.lgpl.License for license details.<br>
30 * The copyright to this program is held by it's authors.
31 * @author DM Smith [dmsmith555 at yahoo dot com]
32 */
33 public interface Progress {
34 /**
35 * Indicate that the total amount of work is unknown.
36 */
37 int UNKNOWN = -1;
38
39 /**
40 * Start the task measured from 0 to 100. It is the caller's responsibility to compute percentages.
41 *
42 * @param sectionName
43 * the initial name of the job.
44 */
45 void beginJob(String sectionName);
46
47 /**
48 * Start the task reporting progress toward total work. Percentages will be
49 * computed on behalf of the caller.
50 *
51 * @param sectionName
52 * the initial name of the job.
53 * @param totalWork
54 * the total amount that is to be worked.
55 */
56 void beginJob(String sectionName, int totalWork);
57
58 /**
59 * Start the task using timings from a prior run as a guess for the current
60 * run. If there are no predictions then progress is faked.
61 *
62 * @param sectionName
63 * the initial name of the job.
64 * @param predictURI
65 * the URI of a properties file from which past behavior is read
66 * and the results of the current run are stored.
67 */
68 void beginJob(String sectionName, URI predictURI);
69
70 /**
71 * @return the job name
72 */
73 String getJobName();
74
75 /**
76 * Gets the current ProgressMode. Builders of progress bars should use
77 * an indeterminant progress bar for ProgressMode.UNKNOWN and ProgressMode.PREDICTIVE.
78 * @return the current progress mode.
79 */
80 ProgressMode getProgressMode();
81
82 /**
83 * @return the total amount of work to be done, or UNKNOWN if it not known
84 */
85 int getTotalWork();
86
87 /**
88 * Set the total amount of work to be done. This can be called any time. It
89 * is the responsibility of the caller for it to be meaningful. It is
90 * ignored when the task is started with a prediction properties file.
91 *
92 * @param totalWork
93 * the total amount of work to be done in units that make sense
94 * to the caller.
95 */
96 void setTotalWork(int totalWork);
97
98 /**
99 * Return the computed percentage as an integer, typically from 0 to 100.
100 *
101 * @return the amount of work done as a percentage
102 */
103 int getWork();
104
105 /**
106 * Indicate progress toward 100%. Note this is just a call to setWorkDone.
107 *
108 * @param progress
109 * a part of the whole.
110 */
111 void setWork(int progress);
112
113 /**
114 * @return the amount of work done so far as reported by the caller
115 */
116 int getWorkDone();
117
118 /**
119 * Indicate progress toward the whole. It is up to the caller to give a
120 * value that makes sense. When using 100 as a basis, it is typically a
121 * number from 0 to 100. In every case, it is a number from 0 to totalWork.
122 *
123 * @param progress
124 * a part of the whole.
125 */
126 void setWorkDone(int progress);
127
128 /**
129 * Indicate progress toward the whole. It is up to the caller to give a
130 * value that makes sense.
131 *
132 * @param step
133 * the amount of work done since the last call.
134 */
135 void incrementWorkDone(int step);
136
137 /**
138 * The section name is used in reporting progress.
139 *
140 * @return the current section name
141 */
142 String getSectionName();
143
144 /**
145 * We have moved onto another section so update the section title. The section name is used in reporting progress.
146 *
147 * @param name
148 * the name of the section
149 */
150 void setSectionName(String name);
151
152 /**
153 * Called to indicate that we are finished doing work.
154 */
155 void done();
156
157 /**
158 * Cancel the job (if possible). If isCancelable() is false, then the job
159 * will be canceled if cancelable becomes true. There is no guarantee that
160 *
161 */
162 void cancel();
163
164 /**
165 * Used to determine whether job is done or canceled or reached totalWork.
166 */
167 boolean isFinished();
168
169 /**
170 * Might the job be cancelable?
171 */
172 boolean isCancelable();
173
174 /**
175 * Indicates whether the job is cancelable or not.
176 *
177 * @param newCancelable
178 * The state to set.
179 */
180 void setCancelable(boolean newCancelable);
181
182 }
183