cz.cuni.amis.utils
Class Job<RESULT>

Package class diagram package Job
java.lang.Object
  extended by cz.cuni.amis.utils.Job<RESULT>

public abstract class Job<RESULT>
extends Object

This Job class represents and wraps one job you want to execute asynchronously. It is a combination of the java.lang.Thread and java.util.concurrent.Future class from java.concurrency packaga

Usage:

  1. Create your own job (anonymous class, inheritance, whatever)
  2. Implement job() method - there you might need to use setResult() method to specify the result of the job
  3. Start the job using startJob() method
  4. Then the thread is launched and job is being crunched
  5. Use await() / isFinished() / isFinishedOk() / isException() / getResult() to examine the results
Note that getResult() should be used only IFF isFinishedOk(), also notice that one instance of job can't be started twice (even if isFinished(), the second startJob() will throw exception)!

/p> Thread-safe.

Example:

MyJob myJob = new MyJob().startJob("my cool thread name");

myJob.await();

if (myJob.isFinishedOk()) {

switch(myJob.getResult()) {

// examine the result, act accordinally

}

}

Author:
Jimmy

Nested Class Summary
static class Job.JobWasAlreadyStartedException
          Exception that is thrown if you attempt to start one job twice.
 
Constructor Summary
Job()
           
 
Method Summary
 void await()
          If isRunning(), this will await till the job finishes.
 boolean await(long timeoutMillis)
          If isRunning(), this will await till the job finishes (with specified timeout).
 Exception getException()
          If isException() this returns an exception that has occured.
protected  Object getMutex()
          Returns object we used as a mutex for this class.
 RESULT getResult()
          Returns job result - should be used
 ImmutableFlag<Boolean> getRunningFlag()
          Returns you a flag that is marking whether the job is running or not.
 void interrupt()
          If job is running (thread is not null and isAlive()) - interrupts the thread.
 boolean isException()
          Whether the exception occurred during the job().
 boolean isFinished()
          Tells you whether the job has ended ...
 boolean isFinishedOk()
          True means: the job has finished correctly without throwing any exception...
 boolean isInterrupted()
          If thread is null: returns false
 boolean isRunning()
          Immediately tells you whether the job is running.
 boolean isStarted()
          Whether the job was already (somewhere in the past) started.
protected abstract  void job()
          Do your job here.
protected  void setResult(RESULT result)
          Use this protected method to set the result of the job.
 Job<RESULT> startJob()
          Starts the job (only iff !isStarted()) in the new thread.
 Job<RESULT> startJob(String threadName)
          Starts the job (only iff !isStarted()) in the new thread (with specific thread name).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Job

public Job()
Method Detail

getMutex

protected Object getMutex()
Returns object we used as a mutex for this class.

Do not use for your own jobs! If you screw up it will result in deadlock.

Returns:

interrupt

public void interrupt()
If job is running (thread is not null and isAlive()) - interrupts the thread.


isInterrupted

public boolean isInterrupted()
If thread is null: returns false

If thread is NOT null: returns thread.isInterrupted().

Returns:

getRunningFlag

public ImmutableFlag<Boolean> getRunningFlag()
Returns you a flag that is marking whether the job is running or not.

Returns:

isRunning

public boolean isRunning()
Immediately tells you whether the job is running.

Returns:

isFinished

public boolean isFinished()
Tells you whether the job has ended ... it doesn't tell you whether it finished OK or KO, use isException() to ask whether the job has finished OK.

Returns:

isFinishedOk

public boolean isFinishedOk()
True means: the job has finished correctly without throwing any exception...

False means: job has not finished yet / was not even started / or exception has occured.

Returns:

isStarted

public boolean isStarted()
Whether the job was already (somewhere in the past) started.

If returns true it does not necessarily mean the job is running!

Returns:

setResult

protected void setResult(RESULT result)
Use this protected method to set the result of the job. (Default result is null.)

Parameters:
result -

getResult

public RESULT getResult()
Returns job result - should be used

Returns:

isException

public boolean isException()
Whether the exception occurred during the job().

Returns:

getException

public Exception getException()
If isException() this returns an exception that has occured.

Returns:

job

protected abstract void job()
                     throws Exception
Do your job here.

Throws:
Exception

await

public void await()
           throws InterruptedException
If isRunning(), this will await till the job finishes.

Throws:
InterruptedException

await

public boolean await(long timeoutMillis)
              throws InterruptedException
If isRunning(), this will await till the job finishes (with specified timeout).

Returns:
true if the count reached zero and false if the waiting time elapsed before the count reached zero
Throws:
InterruptedException

startJob

public Job<RESULT> startJob()
Starts the job (only iff !isStarted()) in the new thread.

If isStarted() ... JobWasAlreadyStartedException is thrown.

Parameters:
job -
Returns:
this instance (you may immediately call await())

startJob

public Job<RESULT> startJob(String threadName)
Starts the job (only iff !isStarted()) in the new thread (with specific thread name).

If isStarted() ... JobWasAlreadyStartedException is thrown.

Parameters:
threadName -
Returns:
this instance (you may immediately call await())


Copyright © 2012 AMIS research group, Faculty of Mathematics and Physics, Charles University in Prague, Czech Republic. All Rights Reserved.