net.aavalla.utils.jobpool
Class Job<R,P>

java.lang.Object
  extended by net.aavalla.utils.jobpool.Job<R,P>
All Implemented Interfaces:
java.lang.Comparable<Job>
Direct Known Subclasses:
ParameterizedJob, SimpleJob, Tester.TestJob1, Tester.TestJob2

public abstract class Job<R,P>
extends java.lang.Object
implements java.lang.Comparable<Job>

Author:
Lari Natri

Field Summary
protected static java.lang.Throwable CANCELLEDRESULT
          Derived classes' work() methods should return or throw this object, if they are cancelled.
 
Constructor Summary
Job()
          Constructs a job and sets it's parameter (which will be passed to {@link #work(java.lang.Object)] to null.
Job(P p)
          Constructs a job and sets it's parameter
 
Method Summary
protected  boolean addCategory(JobCategory cat)
           
protected  boolean addConflictingCategory(JobCategory cat)
           
 boolean addJobFinishedListener(JobFinishedListener l)
          Adds a listener to be notified when this job has ended.
 boolean addJobFinishedListenerSwing(JobFinishedListener l)
          Adds a listener to be notified when this job has ended.
protected  void addSubjob(Job sub)
           
 boolean cancelPending()
          Returns true, if this job has a cancel pending ie.
 int compareTo(Job o)
          Compares Jobs by priorities.
 java.util.EnumSet<JobCategory> getCategories()
          Returns the categories this job is a part of.
 java.util.EnumSet<JobCategory> getConflictingCategories()
          Returns the categories this job conflicts with.
 long getExecutionTime()
          Returns execution time in nanoseconds.
 java.lang.String getName()
          Returns the name of this job.
 JobPriority getPriority()
          Returns the priority of this job.
 int getProgress()
          Returns the progress of this job as a number {-1, [0..100]}.
 JobState getState()
          Returns the state this job is currently in.
 java.lang.String getStatus()
          Returns the last job's status message reported in the Job's execute() method by calling reportStatus(String).
 boolean getUseRecursiveCancel()
           
 long getWaitingTime()
          Returns the time spent waiting for other threads for data.
 boolean isAncestorOf(Job j)
          Returns true if this job is an ancestor of the job given as parameter ie.
 boolean isSilent()
          Returns true, if this job is set to be silent ie.
 boolean removeJobFinishedListener(JobFinishedListener l)
          Removes a listener.
protected  void reportProgress(int newProgress)
          Reports the progress of this job to listeners including the pool.
protected  void reportStatus(java.lang.String newStatus)
           
 void setCancelPending(boolean cancel)
           
protected  void setCategories(java.util.Set<JobCategory> catset)
           
protected  void setConflictingCategories(java.util.Set<JobCategory> catset)
           
 void setName(java.lang.String name)
          Sets the name for this job.
protected  void setPriority(JobPriority newPriority)
          Sets the priority for this job.
protected  void setSilent(boolean silent)
           
protected  void setSupportsCancellation(boolean supCan)
           
 void setUseRecursiveCancel(boolean recCancel)
           
 boolean sharesAncestorWith(Job j)
          Returns true, if this job and the job given as parameter share an ancestor ie.
 boolean supportsCancellation()
          Returns true, if this Job has been set to support cancellation.
 java.lang.String toString()
          Returns the name and state of this job as string.
protected
<S> S
waitSubJob(Job<S,?> sub)
           
protected abstract  R work(P p)
          ABSTRACT PROTECTED
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

CANCELLEDRESULT

protected static final java.lang.Throwable CANCELLEDRESULT
Derived classes' work() methods should return or throw this object, if they are cancelled. Jobs that support cancellation should call setSupportsCancellation(true) in their constructors and in the work() method they should repeatedly check cancelPending().

Constructor Detail

Job

public Job(P p)
Constructs a job and sets it's parameter

Parameters:
p - parameter (will be passed to execute()).
See Also:
ParameterizedJob

Job

public Job()
Constructs a job and sets it's parameter (which will be passed to {@link #work(java.lang.Object)] to null.

Method Detail

getState

public final JobState getState()
Returns the state this job is currently in.

Returns:
state of this job
See Also:
JobState

toString

public java.lang.String toString()
Returns the name and state of this job as string.

Overrides:
toString in class java.lang.Object
Returns:
job's name and state

getName

public final java.lang.String getName()
Returns the name of this job. Never null.

Returns:
job's name
See Also:
setName(java.lang.String)

getProgress

public final int getProgress()
Returns the progress of this job as a number {-1, [0..100]}. -1 signifies unknown progress.

Returns:
current progress of this job

getStatus

public final java.lang.String getStatus()
Returns the last job's status message reported in the Job's execute() method by calling reportStatus(String). Not null.

Returns:
status message

getPriority

public final JobPriority getPriority()
Returns the priority of this job. Guaranteed not to change after this job has been added to a JobPool.

Returns:
priority
See Also:
JobPriority

getExecutionTime

public final long getExecutionTime()
Returns execution time in nanoseconds. Time waited for other threads is not included in the execution time.

Returns:
time in nanoseconds

getWaitingTime

public final long getWaitingTime()
Returns the time spent waiting for other threads for data. Time spent in the queue is not included.

Returns:
time waited for subjobs, in nanoseconds

getCategories

public final java.util.EnumSet<JobCategory> getCategories()
Returns the categories this job is a part of. Categories should be set in the job's constructor and are guaranteed not to change after the job has been added to a JobPool. Can be empty, but not null.

Returns:
categories
See Also:
getConflictingCategories()

getConflictingCategories

public final java.util.EnumSet<JobCategory> getConflictingCategories()
Returns the categories this job conflicts with. A Job will not be started while any jobs whose categories it conflicts with are running, not counting the ancestors of the would-be-started job. Guaranteed not to change after the job's been added to a JobPool. Can be empty, but not null.

Returns:
categories this job conflicts with
See Also:
getCategories()

isSilent

public boolean isSilent()
Returns true, if this job is set to be silent ie. it will not be shown in the JobPool-created UI. Note that even silent jobs are counted in JobPool.getRunningThreadsCount() and sJobPool.getUnfinishedRootJobsCount().

Returns:
true if job is silent, false otherwise

isAncestorOf

public boolean isAncestorOf(Job j)
Returns true if this job is an ancestor of the job given as parameter ie. if parameter job is a subjob of this job; else returns false. If the jobs are the same job, return value is false.

Parameters:
j -
Returns:
true if argument job is a subjob of this job
See Also:
sharesAncestorWith(net.aavalla.utils.jobpool.Job)

sharesAncestorWith

public boolean sharesAncestorWith(Job j)
Returns true, if this job and the job given as parameter share an ancestor ie. if they are part of the same subtree of jobs.

Parameters:
j - job
Returns:
true if jobs share an ancestor, false otherwise
See Also:
isAncestorOf(net.aavalla.utils.jobpool.Job)

supportsCancellation

public final boolean supportsCancellation()
Returns true, if this Job has been set to support cancellation. There are no guarantees that cancelling actually works. Derived classes' work(java.lang.Object) methods ought to check cancelPending() periodically.

Returns:
true if cancelling is supported, false otherwise

getUseRecursiveCancel

public final boolean getUseRecursiveCancel()

cancelPending

public final boolean cancelPending()
Returns true, if this job has a cancel pending ie. it supports cancellation and it has been instructed to be cancelled by setCancelPending(boolean). Jobs that support cancellation, ought to check this periodically in their work(java.lang.Object) method.

Returns:
true if the job has been set to be cancelled, false otherwise

setName

public final void setName(java.lang.String name)
                   throws java.lang.IllegalStateException
Sets the name for this job. Must be called before adding this job to a pool, best place for doing so is in the derived class' constructor.

Parameters:
name - new name for the job
Throws:
java.lang.IllegalStateException - Thrown, if called after the job has been added to a JobPool ie when getState()!=JobState.CREATED

setCancelPending

public final void setCancelPending(boolean cancel)

setUseRecursiveCancel

public final void setUseRecursiveCancel(boolean recCancel)

addJobFinishedListener

public final boolean addJobFinishedListener(JobFinishedListener l)
Adds a listener to be notified when this job has ended. Listener will be run in the same thread as the actual Job.work(). Each listener is only added once and thus executed only once. Listeners must be added before the job finishes (or fails), otherwise an exception is thrown. To play it safe, listeners should be added before adding the job to a pool.

Parameters:
l - listener to add
Returns:
true if listener didn't exist before
Throws:
java.lang.IllegalStateException - Thrown if called after this Job has already finished or failed.

addJobFinishedListenerSwing

public final boolean addJobFinishedListenerSwing(JobFinishedListener l)
Adds a listener to be notified when this job has ended. Listener will be run in the same thread as the actual Job.work(). Each listener is only added once and thus executed only once. Listeners added with this method are run by the Swing's Event Dispatcher Thread. Meant to be used for GUI updating. Listeners must be added before the job finishes (or fails), otherwise an exception is thrown. To play it safe, listeners should be added before adding the job to a pool.

Parameters:
l - listener to add
Returns:
true if listener didn't exist before
Throws:
java.lang.IllegalStateException - Thrown if called after this Job has already finished or failed.

removeJobFinishedListener

public final boolean removeJobFinishedListener(JobFinishedListener l)
Removes a listener. It will not be called after the Job finishes. Listeners will be cleared automatically after Job finishes so there is no need to call this method in the actual listener.

Parameters:
l - listener to remove
Returns:
true if the listener actually existed

compareTo

public final int compareTo(Job o)
Compares Jobs by priorities. If this Job would be run before parameter job, the value is negative, otherwise positive. 0 will be returned only if objects are the same object. Consistent with equals(). Used by JobPool to determine the order of starting jobs.

Specified by:
compareTo in interface java.lang.Comparable<Job>
Parameters:
o - other job to compare to
Returns:
negative if this job is to be run before o job.

setPriority

protected final void setPriority(JobPriority newPriority)
                          throws java.lang.IllegalStateException
Sets the priority for this job. Must be called before adding this job to a pool. Recommended place is in a derived class' constructor. Also PoolThread uses this for new sub jobs to set sub job's priority to the same as it's parent job.

Parameters:
newPriority - priority for this job
Throws:
java.lang.IllegalStateException - Thrown if trying to set priority when this job's state is anything else than CREATED.

addCategory

protected final boolean addCategory(JobCategory cat)
                             throws java.lang.IllegalStateException
Throws:
java.lang.IllegalStateException

setCategories

protected final void setCategories(java.util.Set<JobCategory> catset)
                            throws java.lang.IllegalStateException
Throws:
java.lang.IllegalStateException

addConflictingCategory

protected final boolean addConflictingCategory(JobCategory cat)
                                        throws java.lang.IllegalStateException
Throws:
java.lang.IllegalStateException

setConflictingCategories

protected final void setConflictingCategories(java.util.Set<JobCategory> catset)
                                       throws java.lang.IllegalStateException
Throws:
java.lang.IllegalStateException

setSupportsCancellation

protected final void setSupportsCancellation(boolean supCan)

setSilent

protected final void setSilent(boolean silent)
                        throws java.lang.IllegalStateException
Throws:
java.lang.IllegalStateException

reportProgress

protected final void reportProgress(int newProgress)
Reports the progress of this job to listeners including the pool. Should be called from within derived classes' work() method, but is also called from PoolThread just before (setting it to -1) and after (setting it to 100) calling work(). The progress should be in range [0..100] or -1, which signifies unknown progress.

Parameters:
newProgress -

reportStatus

protected final void reportStatus(java.lang.String newStatus)

addSubjob

protected final void addSubjob(Job sub)

waitSubJob

protected final <S> S waitSubJob(Job<S,?> sub)
                      throws java.lang.Throwable
Throws:
java.lang.Throwable

work

protected abstract R work(P p)
                   throws java.lang.Throwable
ABSTRACT PROTECTED

Throws:
java.lang.Throwable