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

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