org.crosswire.common.progress
Class Job

java.lang.Object
  extended by org.crosswire.common.progress.Job
All Implemented Interfaces:
Progress

public final class Job
extends Object
implements Progress

A Generic method of keeping track of Threads and monitoring their progress.

Author:
Joe Walker, DM Smith
See Also:
The GNU Lesser General Public License for details.

Nested Class Summary
(package private)  class Job.PredictTask
          So we can fake progress for Jobs that don't tell us how they are doing
 
Field Summary
private  boolean cancelable
          Does this job allow interruptions?
private  Map<String,Integer> currentPredictionMap
          The timings loaded from where they were saved after the last run
private  String currentSectionName
          Description of what we are doing
private static int EXTRA_TIME
          The amount of extra time if the predicted time was off and more time is needed.
private  Timer fakingTimer
          The timer that lets us post fake progress events.
private  boolean finished
          Have we just finished?
private  String jobID
           
private  ProgressMode jobMode
          The type of job being performed.
private  String jobName
          A short descriptive phrase
private  List<WorkListener> listeners
          People that want to know about "cancelable" changes
private static org.slf4j.Logger log
          The log stream
private  Map<String,Integer> nextPredictionMap
          The timings as measured this time
private  int percent
          The officially reported progress
private  URI predictionMapURI
          The URI to which we load and save timings
private static int REPORTING_INTERVAL
           
private  long startTime
          When did this job start? Measured in milliseconds since beginning of epoch.
private  int totalUnits
          Total amount of work to do.
private  Thread workerThread
          Optional thread to monitor progress
private  int workUnits
          The amount of work done against the total.
 
Fields inherited from interface org.crosswire.common.progress.Progress
CREATE_INDEX, DOWNLOAD_SEARCH_INDEX, INSTALL_BOOK, RELOAD_BOOK_LIST, UNKNOWN
 
Constructor Summary
protected Job(String jobID, String jobName, Thread worker)
          Create a new Job.
 
Method Summary
 void addWorkListener(WorkListener li)
          Add a listener to the list
 void beginJob(String sectionName)
          Start the task measured from 0 to 100.
 void beginJob(String sectionName, int totalWork)
          Start the task reporting progress toward total work.
 void beginJob(String sectionName, URI predictURI)
          Start the task using timings from a prior run as a guess for the current run.
 void cancel()
          Cancel the job (if possible).
 void done()
          Called to indicate that we are finished doing work.
protected  void fireStateChanged()
           
 String getJobID()
          The Job ID associated with this job
 String getJobName()
           
 ProgressMode getProgressMode()
          Gets the current ProgressMode.
 String getSectionName()
          The section name is used in reporting progress.
 int getTotalWork()
           
 int getWork()
          Return the computed percentage as an integer, typically from 0 to 100.
 int getWorkDone()
           
private  void ignoreTimings()
          Typically called from in a catch block, this ensures that we don't save the timing file because we have a messed up run.
 void incrementWorkDone(int step)
          Indicate progress toward the whole.
 boolean isCancelable()
          Might the job be cancelable?
 boolean isFinished()
          Used to determine whether job is done or canceled or reached totalWork.
private  int loadPredictions()
          Load the predictive timings if any
 void removeWorkListener(WorkListener li)
          Remote a listener from the list
private  void savePredictions()
          Save the known timings to a properties file.
 void setCancelable(boolean newInterruptable)
          Indicates whether the job is cancelable or not.
 void setSectionName(String sectionName)
          We have moved onto another section so update the section title.
 void setTotalWork(int totalWork)
          Set the total amount of work to be done.
 void setWork(int work)
          Indicate progress toward 100%.
 void setWorkDone(int work)
          Indicate progress toward the whole.
protected  boolean updateProgress(long now)
          Get estimated the percent progress
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

REPORTING_INTERVAL

private static final int REPORTING_INTERVAL
See Also:
Constant Field Values

EXTRA_TIME

private static final int EXTRA_TIME
The amount of extra time if the predicted time was off and more time is needed.

See Also:
Constant Field Values

jobMode

private ProgressMode jobMode
The type of job being performed. This is used to simplify code.


totalUnits

private int totalUnits
Total amount of work to do.


cancelable

private boolean cancelable
Does this job allow interruptions?


finished

private boolean finished
Have we just finished?


workUnits

private int workUnits
The amount of work done against the total.


percent

private int percent
The officially reported progress


jobName

private String jobName
A short descriptive phrase


jobID

private final String jobID

workerThread

private Thread workerThread
Optional thread to monitor progress


currentSectionName

private String currentSectionName
Description of what we are doing


predictionMapURI

private URI predictionMapURI
The URI to which we load and save timings


currentPredictionMap

private Map<String,Integer> currentPredictionMap
The timings loaded from where they were saved after the last run


nextPredictionMap

private Map<String,Integer> nextPredictionMap
The timings as measured this time


startTime

private long startTime
When did this job start? Measured in milliseconds since beginning of epoch.


fakingTimer

private Timer fakingTimer
The timer that lets us post fake progress events.


listeners

private List<WorkListener> listeners
People that want to know about "cancelable" changes


log

private static final org.slf4j.Logger log
The log stream

Constructor Detail

Job

protected Job(String jobID,
              String jobName,
              Thread worker)
Create a new Job. This will automatically fire a workProgressed event to all WorkListeners, with the work property of this job set to 0.

Parameters:
jobID - the job identifier
jobName - Short description of this job
worker - Optional thread to use in request to stop worker
Method Detail

beginJob

public void beginJob(String sectionName)
Description copied from interface: Progress
Start the task measured from 0 to 100. It is the caller's responsibility to compute percentages.

Specified by:
beginJob in interface Progress
Parameters:
sectionName - the initial name of the job.

beginJob

public void beginJob(String sectionName,
                     int totalWork)
Description copied from interface: Progress
Start the task reporting progress toward total work. Percentages will be computed on behalf of the caller.

Specified by:
beginJob in interface Progress
Parameters:
sectionName - the initial name of the job.
totalWork - the total amount that is to be worked.

beginJob

public void beginJob(String sectionName,
                     URI predictURI)
Description copied from interface: Progress
Start the task using timings from a prior run as a guess for the current run. If there are no predictions then progress is faked.

Specified by:
beginJob in interface Progress
Parameters:
sectionName - the initial name of the job.
predictURI - the URI of a properties file from which past behavior is read and the results of the current run are stored.

getJobName

public String getJobName()
Specified by:
getJobName in interface Progress
Returns:
the job name

getProgressMode

public ProgressMode getProgressMode()
Description copied from interface: Progress
Gets the current ProgressMode. Builders of progress bars should use an indeterminant progress bar for ProgressMode.UNKNOWN and ProgressMode.PREDICTIVE.

Specified by:
getProgressMode in interface Progress
Returns:
the current progress mode.

getTotalWork

public int getTotalWork()
Specified by:
getTotalWork in interface Progress
Returns:
the total amount of work to be done, or UNKNOWN if it not known

setTotalWork

public void setTotalWork(int totalWork)
Description copied from interface: Progress
Set the total amount of work to be done. This can be called any time. It is the responsibility of the caller for it to be meaningful. It is ignored when the task is started with a prediction properties file.

Specified by:
setTotalWork in interface Progress
Parameters:
totalWork - the total amount of work to be done in units that make sense to the caller.

getWork

public int getWork()
Description copied from interface: Progress
Return the computed percentage as an integer, typically from 0 to 100.

Specified by:
getWork in interface Progress
Returns:
the amount of work done as a percentage

setWork

public void setWork(int work)
Description copied from interface: Progress
Indicate progress toward 100%. Note this is just a call to setWorkDone.

Specified by:
setWork in interface Progress
Parameters:
work - a part of the whole.

getWorkDone

public int getWorkDone()
Specified by:
getWorkDone in interface Progress
Returns:
the amount of work done so far as reported by the caller

setWorkDone

public void setWorkDone(int work)
Description copied from interface: Progress
Indicate progress toward the whole. It is up to the caller to give a value that makes sense. When using 100 as a basis, it is typically a number from 0 to 100. In every case, it is a number from 0 to totalWork.

Specified by:
setWorkDone in interface Progress
Parameters:
work - a part of the whole.

incrementWorkDone

public void incrementWorkDone(int step)
Description copied from interface: Progress
Indicate progress toward the whole. It is up to the caller to give a value that makes sense.

Specified by:
incrementWorkDone in interface Progress
Parameters:
step - the amount of work done since the last call.

getSectionName

public String getSectionName()
Description copied from interface: Progress
The section name is used in reporting progress.

Specified by:
getSectionName in interface Progress
Returns:
the current section name

setSectionName

public void setSectionName(String sectionName)
Description copied from interface: Progress
We have moved onto another section so update the section title. The section name is used in reporting progress.

Specified by:
setSectionName in interface Progress
Parameters:
sectionName - the name of the section

done

public void done()
Description copied from interface: Progress
Called to indicate that we are finished doing work.

Specified by:
done in interface Progress

cancel

public void cancel()
Description copied from interface: Progress
Cancel the job (if possible). If isCancelable() is false, then the job will be canceled if cancelable becomes true. There is no guarantee that

Specified by:
cancel in interface Progress

isFinished

public boolean isFinished()
Description copied from interface: Progress
Used to determine whether job is done or canceled or reached totalWork.

Specified by:
isFinished in interface Progress
Returns:
true if finished

isCancelable

public boolean isCancelable()
Description copied from interface: Progress
Might the job be cancelable?

Specified by:
isCancelable in interface Progress
Returns:
true if the job can be cancelled

setCancelable

public void setCancelable(boolean newInterruptable)
Description copied from interface: Progress
Indicates whether the job is cancelable or not.

Specified by:
setCancelable in interface Progress
Parameters:
newInterruptable - The state to set.

addWorkListener

public void addWorkListener(WorkListener li)
Add a listener to the list

Parameters:
li - the interested listener

removeWorkListener

public void removeWorkListener(WorkListener li)
Remote a listener from the list

Parameters:
li - the disinterested listener

fireStateChanged

protected void fireStateChanged()

updateProgress

protected boolean updateProgress(long now)
Get estimated the percent progress

Parameters:
now - the current point in progress
Returns:
true if there is an update to progress.

loadPredictions

private int loadPredictions()
Load the predictive timings if any

Returns:
the length of progress

savePredictions

private void savePredictions()
Save the known timings to a properties file.


ignoreTimings

private void ignoreTimings()
Typically called from in a catch block, this ensures that we don't save the timing file because we have a messed up run.


getJobID

public String getJobID()
The Job ID associated with this job

Specified by:
getJobID in interface Progress
Returns:
the job ID

Copyright ยจ 2003-2015