Module org.refcodes.jobbus
Package org.refcodes.jobbus

Class JobBusProxy<CTX,H>

java.lang.Object
org.refcodes.jobbus.JobBusProxy<CTX,H>
Type Parameters:
CTX - The context type to use, can by any component, service or POJO.
H - The handle type used to reference a job.
All Implemented Interfaces:
org.refcodes.component.FlushHandle<H>, org.refcodes.component.HandleLookup<H,org.refcodes.command.Undoable<CTX,?,?>>, org.refcodes.component.ProgressHandle<H>, org.refcodes.component.ResetHandle<H>, JobBus<CTX,H>
public class JobBusProxy<CTX,H> extends Object implements JobBus<CTX,H>
The JobBusProxy implements a JobBus proxy: a JobBus proxy can use a remote JobBus whilst only delegating those operations to the remote JobBus which can be handled on the remote system. Any operation requiring asynchronous Thread operations is handled by the JobBusProxy. This is necessary for the synchronous operations as a) waiting for an asynchronous operation to finish may result in a timeout caused by the remoting framework and as b) invoking lambda operations on the proxy will not be propagated to a remote JobBus instance as bidirectional remoting usually is not supported by a remoting framework.

  • Constructor Summary

    Constructors
    Constructor
    Description
    JobBusProxy(JobBus<CTX,H> aJobBus)
    Instantiates a new job bus proxy impl.
    JobBusProxy(JobBus<CTX,H> aJobBus, ExecutorService aExecutorService)
    Instantiates a new job bus proxy impl.

  • Method Summary

    Modifier and Type
    Method
    Description
    H
    execute(org.refcodes.command.Undoable<CTX,?,?> aJob)
    Executes the given job.
    <RET, E extends Exception>
    void
    execute(org.refcodes.command.Undoable<CTX,RET,E> aJob, BiConsumer<RET,E> aResultConsumer)
    Executes the given job and invokes the provides BiConsumer lambda (closure) upon finished execution.
    <RET, E extends Exception>
    void
    execute(org.refcodes.command.Undoable<CTX,RET,E> aJob, Consumer<RET> aResultConsumer)
    Executes the given job and invokes the provided Consumer lambda (closure) upon finished execution.
    void
    flush(H aHandle)
    <E extends Exception>
    E
    getException(H aHandle)
    Returns the exception of the job in case it terminated with an error.
    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 aTimeoutMillis)
    Executes the job and waits for the job's result or an exception or till the timeout has been reached.
    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)
    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 aTimeoutMillis)
    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

    Methods inherited from interface org.refcodes.component.FlushHandle

    flushUnchecked

  • Constructor Details

    • JobBusProxy

      public JobBusProxy(JobBus<CTX,H> aJobBus)
      Instantiates a new job bus proxy impl.
      Parameters:
      aJobBus - the job bus

    • JobBusProxy

      public JobBusProxy(JobBus<CTX,H> aJobBus, ExecutorService aExecutorService)
      Instantiates a new job bus proxy impl.
      Parameters:
      aJobBus - the job bus
      aExecutorService - the executor service

  • Method Details

    • hasHandle

      public boolean hasHandle(H aHandle)
      Specified by:
      hasHandle in interface org.refcodes.component.HandleLookup<CTX,H>

    • hasProgress

      public boolean hasProgress(H aHandle)
      Specified by:
      hasProgress in interface org.refcodes.component.ProgressHandle<CTX>

    • hasReset

      public boolean hasReset(H aHandle)
      Specified by:
      hasReset in interface org.refcodes.component.ResetHandle<CTX>

    • hasFlush

      public boolean hasFlush(H aHandle)
      Specified by:
      hasFlush in interface org.refcodes.component.FlushHandle<CTX>

    • lookupHandle

      public org.refcodes.command.Undoable<CTX,?,?> lookupHandle(H aHandle)
      Specified by:
      lookupHandle in interface org.refcodes.component.HandleLookup<CTX,H>

    • removeHandle

      public org.refcodes.command.Undoable<CTX,?,?> removeHandle(H aHandle)
      Specified by:
      removeHandle in interface org.refcodes.component.HandleLookup<CTX,H>

    • reset

      public void reset(H aHandle)
      Specified by:
      reset in interface org.refcodes.component.ResetHandle<CTX>

    • getProgress

      public float getProgress(H aHandle)
      Specified by:
      getProgress in interface org.refcodes.component.ProgressHandle<CTX>

    • flush

      public void flush(H aHandle) throws IOException
      Specified by:
      flush in interface org.refcodes.component.FlushHandle<CTX>
      Throws:
      IOException

    • execute

      public H 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,H>
      Parameters:
      aJob - The job to be executed.
      Returns:
      The handle associated with the provided job.

    • isExecuted

      public boolean isExecuted(H aHandle)
      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.

    • hasResult

      public boolean hasResult(H aHandle)
      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.

    • hasException

      public boolean hasException(H aHandle)
      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.

    • getResult

      public <RET> RET getResult(H aHandle)
      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 RET.
      Parameters:
      aHandle - The handle associated to the job in question.
      Returns:
      The result after executing the job.

    • getException

      public <E extends Exception> E getException(H aHandle)
      Returns the exception of the job in case it terminated with an error.
      Specified by:
      getException in interface JobBus<CTX,H>
      Type Parameters:
      E - the element type
      Parameters:
      aHandle - The handle associated to the job in question.
      Returns:
      The exception after executing the job.

    • execute

      public <RET, E extends Exception> void execute(org.refcodes.command.Undoable<CTX,RET,E> aJob, Consumer<RET> aResultConsumer)
      Description copied from interface: JobBus
      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,H>
      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 Exception> void execute(org.refcodes.command.Undoable<CTX,RET,E> aJob, 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,H>
      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(H aHandle)
      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.

    • waitForExecution

      public void waitForExecution(H aHandle, long aTimeoutMillis)
      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 ehttps://www.metacodes.proly 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.
      aTimeoutMillis - 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.

    • getResult

      public <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.
      Specified by:
      getResult in interface JobBus<CTX,H>
      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!

    • getResult

      public <JOB extends org.refcodes.command.Undoable<CTX, RET, ?>, RET> RET getResult(JOB aJob, long aTimeoutMillis)
      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 ehttps://www.metacodes.proly 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>
      Type Parameters:
      JOB - the generic type
      RET - The return type of the Undoable's proceedings.
      Parameters:
      aJob - The job to execute
      aTimeoutMillis - 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!