Package org.refcodes.jobbus

Class JobBusImpl<CTX>

java.lang.Object

org.refcodes.jobbus.JobBusImpl<CTX>

Type Parameters:

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

All Implemented Interfaces:

org.refcodes.component.FlushHandle<java.lang.String>, org.refcodes.component.HandleLookup<java.lang.String,org.refcodes.command.Undoable<CTX,?,?>>, org.refcodes.component.ProgressHandle<java.lang.String>, org.refcodes.component.ResetHandle<java.lang.String>, JobBus<CTX,java.lang.String>

public class JobBusImpl<CTX>
extends java.lang.Object
implements JobBus<CTX,java.lang.String>

The JobBusImpl is a ready to use implementation of a composite JobBus wrapping a JobBusDirectory (actually a JobBus is sufficient) and delegating the method calls to the wrapped instances. The JobBusDirectory is considered to be the master from which multiple JobBus instances can be derived. In case none JobBusDirectory is considered to be required, use the empty constructor which creates its internal JobBusDirectory.

In case you want to extend the JobBusImpl with setting concrete parameters for the generic types, please also overwrite the hook method

Constructor Summary

Constructors

Constructor	Description
JobBusImpl(CTX aContext)	Instantiates the JobBusImpl with the provided context and and a pre-defined String objects generating HandleGenerator.
JobBusImpl(JobBus<CTX,java.lang.String> aJobBus)	Instantiates the JobBusImpl by using the provided JobBus to which the method calls are delegated.

Method Summary

Modifier and Type	Method	Description
protected JobBus<CTX,java.lang.String>	createJobBus(CTX aContext)	Hook method pre-implemented useful when extending this class.
java.lang.String	execute(org.refcodes.command.Undoable<CTX,?,?> aJob)	Executes the given job.
<RET,E extends java.lang.Exception> void	execute(org.refcodes.command.Undoable<CTX,RET,E> aJob, java.util.function.BiConsumer<RET,E> aResultConsumer)	Executes the given job and invokes the provides BiConsumer lambda (closure) upon finished execution.
<RET,E extends java.lang.Exception> void	execute(org.refcodes.command.Undoable<CTX,RET,E> aJob, java.util.function.Consumer<RET> aResultConsumer)	Executes the given job and invokes the provided Consumer lambda (closure) upon finished execution.
void	flush(java.lang.String aHandle)
<E extends java.lang.Exception> E	getException(java.lang.String aHandle)	Returns the exception of the job in case it terminated with an error.
float	getProgress(java.lang.String aHandle)
<RET> RET	getResult(java.lang.String 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.
boolean	hasException(java.lang.String aHandle)	Determines whether the job identified by the given handle ended with an exception (instead of a regular result).
boolean	hasFlush(java.lang.String aHandle)
boolean	hasHandle(java.lang.String aHandle)
boolean	hasProgress(java.lang.String aHandle)
boolean	hasReset(java.lang.String aHandle)
boolean	hasResult(java.lang.String aHandle)	Determines whether the job identified by the given handle has a regular result (instead of an exception).
boolean	isExecuted(java.lang.String aHandle)	Determines whether the job has been executed.
org.refcodes.command.Undoable<CTX,?,?>	lookupHandle(java.lang.String aHandle)
org.refcodes.command.Undoable<CTX,?,?>	removeHandle(java.lang.String aHandle)
void	reset(java.lang.String aHandle)
void	waitForExecution(java.lang.String aHandle)	Waits till the job identified by the given handle finished execution by regularly terminating or by throwing an exception.
void	waitForExecution(java.lang.String 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 interface org.refcodes.component.FlushHandle

flushUnchecked

Methods inherited from class java.lang.Object

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

Constructor Detail

JobBusImpl

public JobBusImpl(JobBus<CTX,java.lang.String> aJobBus)

Instantiates the JobBusImpl by using the provided JobBus to which the method calls are delegated. Usually this constructor is used when you created a master JobBusDirectory from which client JobBus instances are to be derived. In case you do not require a master JobBusDirectory, please use the constructor JobBusImpl(Object), which constructs the JobBus delegate with the the provided context.

Parameters:

aJobBus - The JobBus to delegate the method calls to.

JobBusImpl

public JobBusImpl(CTX aContext)

Instantiates the JobBusImpl with the provided context and and a pre-defined String objects generating HandleGenerator. It is up to you which context (service, Component, POJO) you want to provide to a job (Undoable) when being executed.

Parameters:

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

Method Detail

hasHandle

public boolean hasHandle(java.lang.String aHandle)

Specified by:

hasHandle in interface org.refcodes.component.HandleLookup<java.lang.String,org.refcodes.command.Undoable<CTX,?,?>>

hasProgress

public boolean hasProgress(java.lang.String aHandle)
                    throws org.refcodes.component.UnknownHandleRuntimeException

Specified by:

hasProgress in interface org.refcodes.component.ProgressHandle<CTX>

Throws:

org.refcodes.component.UnknownHandleRuntimeException

hasReset

public boolean hasReset(java.lang.String aHandle)
                 throws org.refcodes.component.UnknownHandleRuntimeException

Specified by:

hasReset in interface org.refcodes.component.ResetHandle<CTX>

Throws:

org.refcodes.component.UnknownHandleRuntimeException

hasFlush

public boolean hasFlush(java.lang.String aHandle)
                 throws org.refcodes.component.UnknownHandleRuntimeException

Specified by:

hasFlush in interface org.refcodes.component.FlushHandle<CTX>

Throws:

org.refcodes.component.UnknownHandleRuntimeException

getProgress

public float getProgress(java.lang.String aHandle)
                  throws org.refcodes.component.UnsupportedHandleOperationRuntimeException,
                         org.refcodes.component.UnknownHandleRuntimeException

Specified by:

getProgress in interface org.refcodes.component.ProgressHandle<CTX>

Throws:

org.refcodes.component.UnsupportedHandleOperationRuntimeException

org.refcodes.component.UnknownHandleRuntimeException

lookupHandle

public org.refcodes.command.Undoable<CTX,?,?> lookupHandle(java.lang.String aHandle)
                                                    throws org.refcodes.component.UnknownHandleRuntimeException

Specified by:

lookupHandle in interface org.refcodes.component.HandleLookup<java.lang.String,org.refcodes.command.Undoable<CTX,?,?>>

Throws:

org.refcodes.component.UnknownHandleRuntimeException

reset

public void reset(java.lang.String aHandle)
           throws org.refcodes.component.UnknownHandleRuntimeException,
                  org.refcodes.component.UnsupportedHandleOperationRuntimeException

Specified by:

reset in interface org.refcodes.component.ResetHandle<CTX>

Throws:

org.refcodes.component.UnknownHandleRuntimeException

org.refcodes.component.UnsupportedHandleOperationRuntimeException

flush

public void flush(java.lang.String aHandle)
           throws org.refcodes.component.OpenException,
                  org.refcodes.component.UnknownHandleRuntimeException,
                  org.refcodes.component.UnsupportedHandleOperationRuntimeException

Specified by:

flush in interface org.refcodes.component.FlushHandle<CTX>

Throws:

org.refcodes.component.OpenException

org.refcodes.component.UnknownHandleRuntimeException

org.refcodes.component.UnsupportedHandleOperationRuntimeException

removeHandle

public org.refcodes.command.Undoable<CTX,?,?> removeHandle(java.lang.String aHandle)
                                                    throws org.refcodes.component.UnknownHandleRuntimeException

Specified by:

removeHandle in interface org.refcodes.component.HandleLookup<java.lang.String,org.refcodes.command.Undoable<CTX,?,?>>

Throws:

org.refcodes.component.UnknownHandleRuntimeException

execute

public java.lang.String execute(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:

execute in interface JobBus<CTX,java.lang.String>

Parameters:

aJob - The job to be executed.

Returns:

The handle associated with the provided job.

execute

public <RET,E extends java.lang.Exception> void execute(org.refcodes.command.Undoable<CTX,RET,E> aJob,
                                                        java.util.function.Consumer<RET> aResultConsumer)

Executes the given job and invokes the provided Consumer lambda (closure) upon finished execution. The parameter is passed in case we have an ordinary result, an exceptual situation is "ignored" as the Consumer will not be invoked in such a case. In case you have to take action upon an exceptional situation, then use the JobBus.execute(Undoable, BiConsumer) method.

Specified by:

execute in interface JobBus<CTX,java.lang.String>

Type Parameters:

RET - the generic type

E - the element type

Parameters:

aJob - The job to be executed.

aResultConsumer - The Consumer lambda to be invoked upon finished execution.

execute

public <RET,E extends java.lang.Exception> void execute(org.refcodes.command.Undoable<CTX,RET,E> aJob,
                                                        java.util.function.BiConsumer<RET,E> aResultConsumer)

Executes the given job and invokes the provides BiConsumer lambda (closure) upon finished execution. The first parameter is passed in case we have an ordinary result, the second one is passed in case we have an exceptional situation. Either the one parameter or the other one is passed, never both of them at the same invocation! In case both arguments are null, then your job has returned null. Consider using the Optional to be returned by your job. Though consider that the Optional is NOT serializable which could cause problems with remote job execution! In case you do not have to take action upon an exceptional situation, then use the JobBus.execute(Undoable, Consumer) method.

Specified by:

execute in interface JobBus<CTX,java.lang.String>

Type Parameters:

RET - the generic type

E - the element type

Parameters:

aJob - The job to be executed.

aResultConsumer - The BiConsumer lambda to be invoked upon finished execution.

See Also:

"http://www.refcodes.org/blog/obliged_to_do_the_optional_or_is_it_optional"

waitForExecution

public void waitForExecution(java.lang.String aHandle)
                      throws org.refcodes.component.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,java.lang.String>

Parameters:

aHandle - The handle associated with the provided job.

Throws:

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

waitForExecution

public void waitForExecution(java.lang.String aHandle,
                             long aTimeoutInMs)
                      throws org.refcodes.component.UnknownHandleRuntimeException,
                             org.refcodes.component.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,java.lang.String>

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.UnknownHandleRuntimeException - Thrown in case the handle is not unknown.

org.refcodes.component.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.NoResultAvailableRuntimeException

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

Specified by:

getResult in interface JobBus<CTX,java.lang.String>

Type Parameters:

JOB - the generic type

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.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.NoResultAvailableRuntimeException,
                                                                                org.refcodes.component.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,java.lang.String>

Type Parameters:

JOB - the generic type

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.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.HandleTimeoutRuntimeException - the handle timeout runtime exception

isExecuted

public boolean isExecuted(java.lang.String aHandle)
                   throws org.refcodes.component.UnknownHandleRuntimeException

Determines whether the job has been executed.

Specified by:

isExecuted in interface JobBus<CTX,java.lang.String>

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.UnknownHandleRuntimeException - in case the handle is not unknown.

hasResult

public boolean hasResult(java.lang.String aHandle)
                  throws org.refcodes.component.UnknownHandleRuntimeException,
                         org.refcodes.command.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,java.lang.String>

Parameters:

aHandle - The handle associated to the job in question.

Returns:

The result of the job.

Throws:

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

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

hasException

public boolean hasException(java.lang.String aHandle)
                     throws org.refcodes.component.UnknownHandleRuntimeException,
                            org.refcodes.command.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,java.lang.String>

Parameters:

aHandle - The handle associated to the job in question.

Returns:

The exception of the job's execution.

Throws:

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

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

getResult

public <RET> RET getResult(java.lang.String aHandle)
                    throws org.refcodes.component.UnknownHandleRuntimeException,
                           org.refcodes.command.NotYetExecutedRuntimeException,
                           org.refcodes.command.NoResultAvailableRuntimeException

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

Specified by:

getResult in interface JobBus<CTX,java.lang.String>

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 RET.

Parameters:

aHandle - The handle associated to the job in question.

Returns:

The result after executing the job.

Throws:

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

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

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

getException

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

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

Specified by:

getException in interface JobBus<CTX,java.lang.String>

Type Parameters:

E - the element type

Parameters:

aHandle - The handle associated to the job in question.

Returns:

The exception after executing the job.

Throws:

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

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

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

createJobBus

protected JobBus<CTX,java.lang.String> createJobBus(CTX aContext)

Hook method pre-implemented useful when extending this class.

Parameters:

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

Returns:

The ready to use JobBus.