org.crosswire.common.progress
Class Job

java.lang.Object
  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