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

Class AbstractJobBus<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>
    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 Description
      AbstractJobBus​(CTX aContext, org.refcodes.component.HandleGenerator<H> aHandleGenerator)
      Instantiates the AbstractJobBus with the provided context and the provided HandleGenerator.
      AbstractJobBus​(CTX aContext, org.refcodes.component.HandleGenerator<H> aHandleGenerator, ExecutorService aExecutorService)
      Instantiates the AbstractJobBus with the provided context and the provided HandleGenerator.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      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)
      Gets the exception.
      protected org.refcodes.command.Undoable<CTX,​?,​?> getJob​(H aHandle)
      Gets the job.
      float getProgress​(H aHandle)
      <RET> RET getResult​(H aHandle)
      Gets the result.
      <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)
      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 interface org.refcodes.component.FlushHandle

        flushUnchecked

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

      • AbstractJobBus

        public AbstractJobBus​(CTX aContext,
                      org.refcodes.component.HandleGenerator<H> aHandleGenerator,
                      ExecutorService aExecutorService)
        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.
        aExecutorService - The ExecutorService to be used, when null then an ExecutorService something like ControlFlowUtility.createCachedExecutorService(boolean) is then retrieved.

    • Method Detail

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

      • 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"

      • execute

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

      • getException

        public <E extends Exception> E getException​(H aHandle)
                                     throws org.refcodes.component.UnknownHandleRuntimeException,
                                            org.refcodes.command.NotYetExecutedRuntimeException,
                                            org.refcodes.command.NoExceptionAvailableRuntimeException
        Gets the exception.
        Specified by:
        getException in interface JobBus<CTX,​H>
        Type Parameters:
        E - the element type
        Parameters:
        aHandle - the handle
        Returns:
        the exception
        Throws:
        org.refcodes.component.UnknownHandleRuntimeException - the unknown handle runtime exception
        org.refcodes.command.NotYetExecutedRuntimeException - the not yet executed runtime exception
        org.refcodes.command.NoExceptionAvailableRuntimeException - the no exception available runtime exception

      • getResult

        public <RET> RET getResult​(H aHandle)
                    throws org.refcodes.component.UnknownHandleRuntimeException,
                           org.refcodes.command.NotYetExecutedRuntimeException,
                           org.refcodes.command.NoResultAvailableRuntimeException
        Gets the result.
        Specified by:
        getResult in interface JobBus<CTX,​H>
        Type Parameters:
        RET - the generic type
        Parameters:
        aHandle - the handle
        Returns:
        the result
        Throws:
        org.refcodes.component.UnknownHandleRuntimeException - the unknown handle runtime exception
        org.refcodes.command.NotYetExecutedRuntimeException - the not yet executed runtime exception
        org.refcodes.command.NoResultAvailableRuntimeException - the no result available runtime exception

      • hasException

        public boolean hasException​(H 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,​H>
        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.

      • hasResult

        public boolean hasResult​(H 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,​H>
        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

      • isExecuted

        public boolean isExecuted​(H aHandle)
                   throws org.refcodes.component.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.UnknownHandleRuntimeException - in case the handle is not unknown.

      • waitForExecution

        public void waitForExecution​(H 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,​H>
        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​(H 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,​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.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,​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!
        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,​H>
        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

      • hasHandle

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

      • lookupHandle

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

      • removeHandle

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

      • hasProgress

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

      • getProgress

        public float getProgress​(H 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

      • hasReset

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

      • reset

        public void reset​(H 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

      • hasFlush

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

      • flush

        public void flush​(H aHandle)
           throws IOException,
                  org.refcodes.component.UnknownHandleRuntimeException,
                  org.refcodes.component.UnsupportedHandleOperationRuntimeException
        Specified by:
        flush in interface org.refcodes.component.FlushHandle<CTX>
        Throws:
        IOException
        org.refcodes.component.UnknownHandleRuntimeException
        org.refcodes.component.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.UnknownHandleRuntimeException
        Gets the job.
        Parameters:
        aHandle - the handle
        Returns:
        the job
        Throws:
        org.refcodes.component.UnknownHandleRuntimeException - the unknown handle runtime exception