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

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `(package private) class` | `Job.PredictTask` So we can fake progress for Jobs that don't tell us how they are doing

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `Job(String jobID, String jobName, Thread worker)` Create a new Job.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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