org.refcodes.jobbus.impls

Class AbstractJobBus<CTX,H>

java.lang.Object

org.refcodes.jobbus.impls.AbstractJobBus<CTX,H>

Type Parameters:

CTX - The context type to use, can by any Component, service or POJO.

RET - The return type of the Undoable's proceedings.

H - The handle type used to reference a job.

All Implemented Interfaces:

org.refcodes.component.HandleLookup<H,org.refcodes.command.Undoable<CTX,?,?>>, org.refcodes.component.mixins.FlushHandle<H>, org.refcodes.component.mixins.ProgressHandle<H>, org.refcodes.component.mixins.ResetHandle<H>, JobBus<CTX,H>

Direct Known Subclasses:

AbstractJobBusDirectory

public abstract class AbstractJobBus<CTX,H>
extends Object
implements JobBus<CTX,H>

The AbstractJobBus implements the JobBus interface.

Constructor Summary

Constructors

Constructor and Description
AbstractJobBus(CTX aContext, org.refcodes.component.HandleGenerator<H> aHandleGenerator) Instantiates the AbstractJobBus with the provided context and the provided HandleGenerator.

Method Summary

Modifier and Type	Method and Description
void	flush(H aHandle)
<E extends Exception> E	getException(H aHandle) Returns the exception of the job in case it terminated with an error.
protected org.refcodes.command.Undoable<CTX,?,?>	getJob(H aHandle)
float	getProgress(H aHandle)
<RET> RET	getResult(H aHandle) Returns the result of the job as the result of executing the job.
<JOB extends org.refcodes.command.Undoable<CTX,RET,?>,RET> RET	getResult(JOB aJob) Executes the job and waits for the job's result or an exception.
<JOB extends org.refcodes.command.Undoable<CTX,RET,?>,RET> RET	getResult(JOB aJob, long aTimeoutInMs) Executes the job and waits for the job's result or an exception or till the timeout has been reached.
protected Collection<org.refcodes.command.Undoable<CTX,?,?>>	handleReferences() Retrieves the list of objects referenced by the handles.
protected Set<H>	handles() Returns the set of handles managed by this implementation.
boolean	hasException(H aHandle) Determines whether the job identified by the given handle ended with an exception (instead of a regular result).
boolean	hasFlush(H aHandle)
boolean	hasHandle(H aHandle)
boolean	hasProgress(H aHandle)
boolean	hasReset(H aHandle)
boolean	hasResult(H aHandle) Determines whether the job identified by the given handle has a regular result (instead of an exception).
boolean	isExecuted(H aHandle) Determines whether the job has been executed.
org.refcodes.command.Undoable<CTX,?,?>	lookupHandle(H aHandle)
org.refcodes.command.Undoable<CTX,?,?>	removeHandle(H aHandle)
void	reset(H aHandle)
H	start(org.refcodes.command.Undoable<CTX,?,?> aJob) Executes the given job.
void	waitForExecution(H aHandle) Waits till the job identified by the given handle finished execution by regularly terminating or by throwing an exception.
void	waitForExecution(H aHandle, long aTimeoutInMs) Waits till the job identified by the given handle finished execution by regularly terminating or by throwing an exception or till the timeout has been reached.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractJobBus

public AbstractJobBus(CTX aContext,
                      org.refcodes.component.HandleGenerator<H> aHandleGenerator)

Instantiates the AbstractJobBus with the provided context and the provided HandleGenerator. It is up to you which context (service, Component, POJO) you want to provide to a job (Undoable) when being executed. Also you can provide any HandleGenerator you thing useful when creating handles. It is up to your HandleGenerator to generate unique handle objects. The JobBusDirectory actually uses a String objects generating HandleGenerator. Make sure your handles implement the Object.hashCode() and Object.equals(Object) methods as of their method contracts as them handles will be used in collections such as HashMap data structures.

Parameters:

aContext - The context which is passed to the job (Undoable) instances when being executed.

aHandleGenerator - The HandleGenerator to be used when generating unique handle objects.

Method Detail

start

public H start(org.refcodes.command.Undoable<CTX,?,?> aJob)

Executes the given job. By double dispatch the job's execute method is invoked. The Job is provided with a service-bus to be able to perform its task. This is an implementation of the command pattern.

Specified by:

start in interface JobBus<CTX,H>

Parameters:

aJob - The job to be executed

Returns:

The handle associated with the provided job.

getException

public <E extends Exception> E getException(H aHandle)
                                     throws org.refcodes.component.traps.UnknownHandleRuntimeException,
                                            org.refcodes.command.traps.NotYetExecutedRuntimeException,
                                            org.refcodes.command.traps.NoExceptionAvailableRuntimeException

Returns the exception of the job in case it terminated with an error.

Specified by:

getException in interface JobBus<CTX,H>

Parameters:

aHandle - The handle associated to the job in question.

Returns:

The exception after executing the job.

Throws:

org.refcodes.component.traps.UnknownHandleRuntimeException - in case the handle is not unknown.

org.refcodes.command.traps.NotYetExecutedRuntimeException - in case the job has not been executed yet.

org.refcodes.command.traps.NoExceptionAvailableRuntimeException - in case the job did not provide an exception after execution.

getResult

public <RET> RET getResult(H aHandle)
                    throws org.refcodes.component.traps.UnknownHandleRuntimeException,
                           org.refcodes.command.traps.NotYetExecutedRuntimeException,
                           org.refcodes.command.traps.NoResultAvailableRuntimeException

Returns the result of the job as the result of executing the job.

Specified by:

getResult in interface JobBus<CTX,H>

Type Parameters:

RET - As of convenience, the return type of the Undoable instance's proceedings. CAUTION: As the handle does not permit insight on the Undoable (job) instance's return type, you may end up with a class cast exception in case you do not make sure that the result is of the expected type .

Parameters:

aHandle - The handle associated to the job in question.

Returns:

The result after executing the job.

Throws:

org.refcodes.component.traps.UnknownHandleRuntimeException - in case the handle is not unknown.

org.refcodes.command.traps.NotYetExecutedRuntimeException - in case the job has not been executed yet.

org.refcodes.command.traps.NoResultAvailableRuntimeException - in case the job did not provide a result after execution.

hasException

public boolean hasException(H aHandle)
                     throws org.refcodes.component.traps.UnknownHandleRuntimeException,
                            org.refcodes.command.traps.NotYetExecutedRuntimeException

Determines whether the job identified by the given handle ended with an exception (instead of a regular result). Most jobs do not have any exception, i.e. check if the job has been executed and also check if there is a result or an exception before requesting the according information.

Specified by:

hasException in interface JobBus<CTX,H>

Parameters:

aHandle - The handle associated to the job in question.

Returns:

The exception of the job's execution.

Throws:

org.refcodes.component.traps.UnknownHandleRuntimeException - in case the handle is not unknown.

org.refcodes.command.traps.NotYetExecutedRuntimeException - in case the job has not been executed yet.

hasResult

public boolean hasResult(H aHandle)
                  throws org.refcodes.component.traps.UnknownHandleRuntimeException,
                         org.refcodes.command.traps.NotYetExecutedRuntimeException

Determines whether the job identified by the given handle has a regular result (instead of an exception). There may be jobs which do not have any result, i.e. check if the job has been executed and also check if there is a result or an exception before requesting the according information.

Specified by:

hasResult in interface JobBus<CTX,H>

Parameters:

aHandle - The handle associated to the job in question.

Returns:

The result of the job.

Throws:

org.refcodes.component.traps.UnknownHandleRuntimeException - in case the handle is not unknown.

org.refcodes.command.traps.NotYetExecutedRuntimeException - in case the job has not been executed yet

isExecuted

public boolean isExecuted(H aHandle)
                   throws org.refcodes.component.traps.UnknownHandleRuntimeException

Determines whether the job has been executed.

Specified by:

isExecuted in interface JobBus<CTX,H>

Parameters:

aHandle - The handle associated to the job in question.

Returns:

True if the job represented by the handle has been executed.

Throws:

org.refcodes.component.traps.UnknownHandleRuntimeException - in case the handle is not unknown.

waitForExecution

public void waitForExecution(H aHandle)
                      throws org.refcodes.component.traps.UnknownHandleRuntimeException

Waits till the job identified by the given handle finished execution by regularly terminating or by throwing an exception. The handle my be used to determine if there was an exception or not and to retrieve the result or in case of an exception the exception object.

Specified by:

waitForExecution in interface JobBus<CTX,H>

Parameters:

aHandle - The handle associated with the provided job.

Throws:

org.refcodes.component.traps.UnknownHandleRuntimeException - in case the handle is not unknown.

waitForExecution

public void waitForExecution(H aHandle,
                             long aTimeoutInMs)
                      throws org.refcodes.component.traps.UnknownHandleRuntimeException,
                             org.refcodes.component.traps.HandleTimeoutRuntimeException

Waits till the job identified by the given handle finished execution by regularly terminating or by throwing an exception or till the timeout has been reached. In case the timeout has been reached before execution was finished, then a HandleTimeoutRuntimeException is thrown to abort the waiting loop. This is especially useful when a remote connection is used to managed a distributed JobBus infrastructure and due to connection issues, wait time would be endless. The handle my be used to determine if there was an exception or not and to retrieve the result or in case of an exception the exception object.

Specified by:

waitForExecution in interface JobBus<CTX,H>

Parameters:

aHandle - The handle associated with the provided job.

aTimeoutInMs - The timeout to wait at most even when execution did not finish. In case the timeout has been reached before execution was finished, then a HandleTimeoutRuntimeException is thrown to abort the waiting loop.

Throws:

org.refcodes.component.traps.UnknownHandleRuntimeException - Thrown in case the handle is not unknown.

org.refcodes.component.traps.HandleTimeoutRuntimeException - Thrown in case the timeout was reached before execution finished.

getResult

public <JOB extends org.refcodes.command.Undoable<CTX,RET,?>,RET> RET getResult(JOB aJob)
                                                                         throws org.refcodes.command.traps.NoResultAvailableRuntimeException

Executes the job and waits for the job's result or an exception.

Specified by:

getResult in interface JobBus<CTX,H>

RET - The return type of the Undoable's proceedings.

Parameters:

aJob - The job to execute

Returns:

The result of the job execution. In case the job does not produce a result by default ("void"), then the according exception is thrown. Make sure the job produces a result!

Throws:

org.refcodes.command.traps.NoResultAvailableRuntimeException - in case a job has been executed which never delivers a result or which terminated with an exception. Use JobBus.hasException(Object) and JobBus.hasResult(Object) to clarify which state your Undoable (job) is in.

getResult

public <JOB extends org.refcodes.command.Undoable<CTX,RET,?>,RET> RET getResult(JOB aJob,
                                                                                long aTimeoutInMs)
                                                                         throws org.refcodes.command.traps.NoResultAvailableRuntimeException,
                                                                                org.refcodes.component.traps.HandleTimeoutRuntimeException

Executes the job and waits for the job's result or an exception or till the timeout has been reached. In case the timeout has been reached before execution was finished, then a HandleTimeoutRuntimeException is thrown to abort the waiting loop. This is especially useful when a remote connection is used to managed a distributed JobBus infrastructure and due to connection issues, wait time would be endless.

Specified by:

getResult in interface JobBus<CTX,H>

RET - The return type of the Undoable's proceedings.

Parameters:

aJob - The job to execute

aTimeoutInMs - The timeout to wait at most even when execution did not finish. In case the timeout has been reached before execution was finished, then a HandleTimeoutRuntimeException is thrown to abort the waiting loop.

Returns:

The result of the job execution. In case the job does not produce a result by default ("void"), then the according exception is thrown. Make sure the job produces a result!

Throws:

org.refcodes.command.traps.NoResultAvailableRuntimeException - in case a job has been executed which never delivers a result or which terminated with an exception. Use JobBus.hasException(Object) and JobBus.hasResult(Object) to clarify which state your Undoable (job) is in.

org.refcodes.component.traps.HandleTimeoutRuntimeException

hasHandle

public boolean hasHandle(H aHandle)

Specified by:

hasHandle in interface org.refcodes.component.HandleLookup<H,org.refcodes.command.Undoable<CTX,?,?>>

lookupHandle

public org.refcodes.command.Undoable<CTX,?,?> lookupHandle(H aHandle)
                                                    throws org.refcodes.component.traps.UnknownHandleRuntimeException

Specified by:

lookupHandle in interface org.refcodes.component.HandleLookup<H,org.refcodes.command.Undoable<CTX,?,?>>

Throws:

org.refcodes.component.traps.UnknownHandleRuntimeException

removeHandle

public org.refcodes.command.Undoable<CTX,?,?> removeHandle(H aHandle)
                                                    throws org.refcodes.component.traps.UnknownHandleRuntimeException

Specified by:

removeHandle in interface org.refcodes.component.HandleLookup<H,org.refcodes.command.Undoable<CTX,?,?>>

Throws:

org.refcodes.component.traps.UnknownHandleRuntimeException

hasProgress

public boolean hasProgress(H aHandle)
                    throws org.refcodes.component.traps.UnknownHandleRuntimeException

Specified by:

hasProgress in interface org.refcodes.component.mixins.ProgressHandle<H>

Throws:

org.refcodes.component.traps.UnknownHandleRuntimeException

getProgress

public float getProgress(H aHandle)
                  throws org.refcodes.component.traps.UnsupportedHandleOperationRuntimeException,
                         org.refcodes.component.traps.UnknownHandleRuntimeException

Specified by:

getProgress in interface org.refcodes.component.mixins.ProgressHandle<H>

Throws:

org.refcodes.component.traps.UnsupportedHandleOperationRuntimeException

org.refcodes.component.traps.UnknownHandleRuntimeException

hasReset

public boolean hasReset(H aHandle)
                 throws org.refcodes.component.traps.UnknownHandleRuntimeException

Specified by:

hasReset in interface org.refcodes.component.mixins.ResetHandle<H>

Throws:

org.refcodes.component.traps.UnknownHandleRuntimeException

reset

public void reset(H aHandle)
           throws org.refcodes.component.traps.UnknownHandleRuntimeException,
                  org.refcodes.component.traps.UnsupportedHandleOperationRuntimeException

Specified by:

reset in interface org.refcodes.component.mixins.ResetHandle<H>

Throws:

org.refcodes.component.traps.UnknownHandleRuntimeException

org.refcodes.component.traps.UnsupportedHandleOperationRuntimeException

hasFlush

public boolean hasFlush(H aHandle)
                 throws org.refcodes.component.traps.UnknownHandleRuntimeException

Specified by:

hasFlush in interface org.refcodes.component.mixins.FlushHandle<H>

Throws:

org.refcodes.component.traps.UnknownHandleRuntimeException

flush

public void flush(H aHandle)
           throws IOException,
                  org.refcodes.component.traps.UnknownHandleRuntimeException,
                  org.refcodes.component.traps.UnsupportedHandleOperationRuntimeException

Specified by:

flush in interface org.refcodes.component.mixins.FlushHandle<H>

Throws:

IOException

org.refcodes.component.traps.UnknownHandleRuntimeException

org.refcodes.component.traps.UnsupportedHandleOperationRuntimeException

handleReferences

protected Collection<org.refcodes.command.Undoable<CTX,?,?>> handleReferences()

Retrieves the list of objects referenced by the handles.

Returns:

A collection with the objects referenced by handles.

handles

protected Set<H> handles()

Returns the set of handles managed by this implementation.

Returns:

The set containing all currently managed handles.

getJob

protected org.refcodes.command.Undoable<CTX,?,?> getJob(H aHandle)
                                                 throws org.refcodes.component.traps.UnknownHandleRuntimeException

Parameters:

aHandle -

Returns:

Throws:

org.refcodes.component.traps.UnknownHandleRuntimeException