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