Package org.eclipse.scanning.api.event.core

Interface IJobQueue<T>

Type Parameters:
T - The bean class used for the queue
All Superinterfaces:
AutoCloseable, IBeanClass<T>, IConnection
All Known Implementing Classes:
JobQueueImpl, JobQueueProxy
public interface IJobQueue<T> extends IConnection, IBeanClass<T>
A IJobQueue holds a queue of beans that represent tasks that can be run, together with a consumer thread that reads beans from the queue, creating and running a process for each according to the process factory that this queue has been configured with. It also contains a set of beans for running and completed tasks. As tasks run, any change in their status is published to the status topic, a JMS topic.

A job queue can be thought of a being composed of three components, and each method of this interface is directed at exactly one of these components:

  1. The submission queue: A queue of beans defining jobs to be run. The method getSubmissionQueue() returns a copy of the queue as a list. A bean can be submitted to the tail of the queue using the submit(Object) method. The methods moveForward(Object) and moveBackward(Object) and remove(Object) can be used to move beans up the queue, down the queue and to remove a bean from the queue, respectively. clearQueue() removes all beans from the queue
  2. The consumer thread: A thread that runs in a loop, removing a job bean from the submission queue, creating an IBeanProcess for it and running it The process is run in the same thread if IBeanProcess.isBlocking() is true, otherwise it is run in a new thread. The method setRunner(IProcessCreator) should be called by the code that creates the job queue to set the IProcessCreator used to create the processes. The methods start(), stop(), pause(), resume() can be used to control the consumer thread.
  3. The status set: An ordered set of beans for running and completed jobs. The consumer thread adds a bean to this set when it is removed from the submission queue. The method removeCompleted(Object) can be used to remove a particular bean from this method

When the status of the bean changes, it is published to the status topic, a JMS topic that can be listened to with an ISubscriber. The name of the status topic is returned by getStatusTopicName(). The beans status will change as the job is started and completed. Also, the job queue passes an IPublisher to the IBeanProcess that runs the job for the bean so that it can also send notifications to the status topic when necessary.

The job queue can also be controlled via a JMS topic called the command topic. The method getCommandTopicName() returns the name of this topic, and getCommandAckTopicName() the name of the topic used to return responses. The command topic takes QueueCommandBean where the action to be taken is determined by the command property This job queue is primarily intended to run solstice (GDA9) scans, however it can be used as a generic way to run jobs with messaging.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    IJobQueue.IQueueStatusListener
    An instance of this interface can be used by clients to be notified of changes to the queue's status, specifically whether its consumer thread is running, paused or stopped.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addQueueStatusListener(IJobQueue.IQueueStatusListener listener)
     
    void
    awaitStart()
    Awaits the start of the job queue's consumer thread.
    void
    awaitStop()
    Awaits the job queue's consumer thread having stopped.
    void
    cleanUpCompleted()
    Cleans up the set of beans for running and completed job by removing certain beans.
    void
    clearQueue()
    Removes all pending jobs from the submission queue.
    void
    clearRunningAndCompleted()
    Clears the set of beans for running and completed jobs.
    void
    clearRunningAndCompleted(boolean bool)
    Clears the set of beans for running and completed jobs, with an optional argument for whether to clear the currently running scan (if there is one)
    void
    defer(T bean)
    Sets the given bean (which must be Status.SUBMITTED to be deferred, not to be run until it is undeferred.
    String
    getCommandAckTopicName()
    The topic used by the consumer to send acknowledgements for commands received on the command topic.
    String
    getCommandTopicName()
    The topic used to run commands like terminate the running process and get the consumer to stop.
    UUID
    getJobQueueId()
    The UUID which uniquely defines this job queue.
    String
    getName()
     
    QueueStatus
    getQueueStatus()
    Returns the QueueStatus indicating whether the job queue's consumer thread is QueueStatus.RUNNING, QueueStatus.PAUSED or QueueStatus.STOPPED.
    String
    getQueueStatusTopicName()
    If set, the name of the topic that the job queue's consumer topic publishes QueueStatusBeans to, to indicate that it is running.
    IProcessCreator<T>
    getRunner()
    Returns the IProcessCreator used as a factory to create IBeanProcess for each bean as they are removed from the submission queue by the consumer thread.
    List<T>
    getRunningAndCompleted()
    Return a list of beans whose jobs are either running or completed.
    List<T>
    getRunningAndCompleted(String optionalArgument)
    Returns either the list returned by getRunningAndCompleted() or a sublist of that list, limited by the argument.
    String
    getStatusTopicName()
    The name of status topic, a JMS topic that receives updated versions of the bean as it changes while the task that it defines is run.
    List<T>
    getSubmissionQueue()
    Get a copy of the current submission queue as a list of beans.
    String
    getSubmitQueueName()
    The name job queue's submission queue.
    boolean
    isActive()
    Returns if the job queue is active.
    boolean
    isPaused()
    Returns whether the job queue's consumer thread is paused.
    boolean
    isPauseOnStart()
    Returns whether the job queue's consumer thread will start in a paused state if the submission queue is non-empty.
    boolean
    moveBackward(T bean)
    Moves the given bean towards the tail of the submission queue if possible, i.e.
    boolean
    moveForward(T bean)
    Moves the given bean towards the head of the submission queue if possible, i.e.
    void
    pause()
    Pauses the job queue's consumer thread if running.
    void
    pauseJob(T bean)
    If a process for the given bean exists and is running, pauses it.
    boolean
    remove(T bean)
    Removes the bean from the submission queue if present.
    boolean
    removeCompleted(T bean)
    Remove the given bean from the set of beans for running and completed jobs (the status set).
    void
    removeQueueStatusListener(IJobQueue.IQueueStatusListener listener)
     
    boolean
    replace(T bean)
    Replace the bean in the submission queue with the given bean, if present.
    void
    resume()
    Resumes the job queue's consumer thread if paused.
    void
    resumeJob(T bean)
    If a process for the given bean exists and is paused, resumes it.
    void
    run()
    Starts the job queue's consumer thread and blocks.
    void
    setName(String name)
     
    void
    setPauseOnStart(boolean pauseOnStart)
    Sets whether the job queue's consumer thread should start in a paused state if the submission queue is non-empty.
    void
    setRunner(IProcessCreator<T> process)
    Set the consumer process to run for each job.
    void
    setStatusTopicName(String statusTopicName)
    Set the name of the status topic.
    void
    start()
    Starts the consumer in new thread and return.
    void
    stop()
    Ask the consumer to stop
    void
    submit(T bean)
    Adds the given bean to the tail of the submission queue.
    void
    terminateJob(T bean)
    If the process for the given bean exists and is running or paused, terminates it.
    void
    undefer(T bean)
    Allow a submitted, deferred bean to be run when it is reached again.

    Methods inherited from interface org.eclipse.scanning.api.event.core.IBeanClass

    getBeanClass, setBeanClass

    Methods inherited from interface org.eclipse.scanning.api.event.core.IConnection

    close, disconnect, isConnected

  • Method Details

    • getSubmitQueueName

      String getSubmitQueueName()
      The name job queue's submission queue. This name is expected to be unique to this instance.
      Returns:
      name of the submit queue

    • getSubmissionQueue

      List<T> getSubmissionQueue() throws EventException
      Get a copy of the current submission queue as a list of beans.
      Returns:
      the submission queue
      Throws:
      EventException - if the submission queue cannot be returned for any reason

    • clearQueue

      void clearQueue() throws EventException
      Removes all pending jobs from the submission queue.
      Throws:
      EventException - if the queue cannot be cleared for any reason

    • getRunningAndCompleted

      List<T> getRunningAndCompleted() throws EventException
      Return a list of beans whose jobs are either running or completed. The list is ordered by submission time, not necessarily the ordering of the JMS queue.
      Returns:
      running and completed beans
      Throws:
      EventException - if the set of running and completed beans cannot be returned for any reason

    • getRunningAndCompleted

      List<T> getRunningAndCompleted(String optionalArgument) throws EventException
      Returns either the list returned by getRunningAndCompleted() or a sublist of that list, limited by the argument. Currently the optional argument may be a non-negative integer in which case if the number of submitted + running + completed scans exceeds the argument, completed scans are removed until either none remain or the number of scans being returned is less than the argument. If a scan is running it must always be returned. If any String that would not parse to a non-negative integer is passed, then the argument is taken to be unlimited, and this method should return getRunningAndCompleted()
      Parameters:
      optionalArgument - a String representation of a non-negative integer ("0", "1", "2"...)
      Returns:
      list containing the running bean and optionally some completed beans
      Throws:
      EventException

    • clearRunningAndCompleted

      void clearRunningAndCompleted() throws EventException
      Clears the set of beans for running and completed jobs.
      Throws:
      EventException - if the set of running and completed

    • clearRunningAndCompleted

      void clearRunningAndCompleted(boolean bool) throws EventException
      Clears the set of beans for running and completed jobs, with an optional argument for whether to clear the currently running scan (if there is one)
      Throws:
      EventException - if the set of running and completed

    • cleanUpCompleted

      void cleanUpCompleted() throws EventException
      Cleans up the set of beans for running and completed job by removing certain beans. Specifically, the beans that are removed are those that meet one of the following criteria:
      • have status Status.FAILED or Status.NONE;
      • have a status indicating that they are running (i.e. Status.isRunning() is true) and are older than the maximum running age (by default, two days);
      • have a status indicating that they are final (i.e. Status.isFinal() is true) and are older than the maximum complete age (by default, one week);
      • Additionally jobs that are not started or paused will have their status set to Status.FAILED;

      This method is intended to be called on starting the consumer.

      Throws:
      EventException

    • moveForward

      boolean moveForward(T bean) throws EventException
      Moves the given bean towards the head of the submission queue if possible, i.e. it will be processed sooner.
      Parameters:
      bean -
      Returns:
      true if the bean could be moved, false otherwise
      Throws:
      EventException

    • moveBackward

      boolean moveBackward(T bean) throws EventException
      Moves the given bean towards the tail of the submission queue if possible, i.e. it will be processed later.
      Parameters:
      bean -
      Returns:
      true if the bean could be moved, false otherwise
      Throws:
      EventException

    • remove

      boolean remove(T bean) throws EventException
      Removes the bean from the submission queue if present. If the bean has been moved to the set of running and completed jobs, it will not be removed.
      Parameters:
      bean - bean to remove
      Returns:
      true if the bean was removed, false otherwise, i.e. the bean was not present
      Throws:
      EventException

    • removeCompleted

      boolean removeCompleted(T bean) throws EventException
      Remove the given bean from the set of beans for running and completed jobs (the status set).
      Parameters:
      bean - bean to remove
      Returns:
      true if the bean was removed, false otherwise, i.e. the bean was not present
      Throws:
      EventException

    • replace

      boolean replace(T bean) throws EventException
      Replace the bean in the submission queue with the given bean, if present. If the bean has been moved to the set of running and completed jobs, it will not be removed. A bean will replace another if it has the same unique id as returned by IdBean.getUniqueId()
      Parameters:
      bean - bean to remove
      Returns:
      true if the bean was replaced, false otherwise, i.e. the bean was not present
      Throws:
      EventException

    • getStatusTopicName

      String getStatusTopicName()
      The name of status topic, a JMS topic that receives updated versions of the bean as it changes while the task that it defines is run.
      Returns:
      status topic name

    • setStatusTopicName

      void setStatusTopicName(String statusTopicName) throws EventException
      Set the name of the status topic.
      Parameters:
      statusTopicName - name of status topic
      Throws:
      EventException

    • setRunner

      void setRunner(IProcessCreator<T> process) throws EventException
      Set the consumer process to run for each job.
      Parameters:
      process -
      Throws:
      EventException - if the alive topic cannot be sent

    • start

      void start() throws EventException
      Starts the consumer in new thread and return. Similar to Thread.start() You must set the runner before calling this method
      Throws:
      EventException

    • stop

      void stop() throws EventException
      Ask the consumer to stop
      Throws:
      EventException

    • awaitStart

      void awaitStart() throws InterruptedException
      Awaits the start of the job queue's consumer thread. Mostly useful for testing.
      Throws:
      InterruptedException

    • awaitStop

      void awaitStop() throws InterruptedException
      Awaits the job queue's consumer thread having stopped. Mostly useful for testing.
      Throws:
      InterruptedException

    • run

      void run() throws EventException
      Starts the job queue's consumer thread and blocks. Similar to Thread.run() You must set the runner by calling setRunner(IProcessCreator) before calling this method.
      Throws:
      EventException

    • pause

      void pause() throws EventException
      Pauses the job queue's consumer thread if running. It will not process any more jobs until it resumes. Currently running jobs are not affected.
      Throws:
      EventException

    • resume

      void resume() throws EventException
      Resumes the job queue's consumer thread if paused. It will resume processing jobs.
      Throws:
      EventException

    • submit

      void submit(T bean) throws EventException
      Adds the given bean to the tail of the submission queue.
      Parameters:
      bean - bean to add
      Throws:
      EventException

    • pauseJob

      void pauseJob(T bean) throws EventException
      If a process for the given bean exists and is running, pauses it. If the bean is still in the submission queue, then instead defers the bean, allowing other scans to be run first.
      Parameters:
      bean - bean whose process to pause.
      Throws:
      EventException

    • resumeJob

      void resumeJob(T bean) throws EventException
      If a process for the given bean exists and is paused, resumes it.
      Parameters:
      bean - bean whose process to resume.
      Throws:
      EventException

    • defer

      void defer(T bean) throws EventException
      Sets the given bean (which must be Status.SUBMITTED to be deferred, not to be run until it is undeferred.
      Parameters:
      bean - bean whose process to resume.
      Throws:
      EventException

    • undefer

      void undefer(T bean) throws EventException
      Allow a submitted, deferred bean to be run when it is reached again.
      Parameters:
      bean - bean whose process to resume.
      Throws:
      EventException

    • terminateJob

      void terminateJob(T bean) throws EventException
      If the process for the given bean exists and is running or paused, terminates it. If the bean is still in the submission queue then instead when the consumer thread removes it from the queue it will set its status to Status.TERMINATED, add the bean to the set of running and completed jobs. It will not create a process for it.
      Parameters:
      bean - bean whose process to terminate
      Throws:
      EventException

    • getRunner

      IProcessCreator<T> getRunner()
      Returns the IProcessCreator used as a factory to create IBeanProcess for each bean as they are removed from the submission queue by the consumer thread.
      Returns:
      the process creator

    • isPaused

      boolean isPaused()
      Returns whether the job queue's consumer thread is paused.
      Returns:
      true if the consumer thread is paused, false otherwise

    • getCommandTopicName

      String getCommandTopicName()
      The topic used to run commands like terminate the running process and get the consumer to stop.
      Returns:
      topic name

    • getCommandAckTopicName

      String getCommandAckTopicName()
      The topic used by the consumer to send acknowledgements for commands received on the command topic.
      Returns:
      command acknowledgement topic name

    • getQueueStatusTopicName

      String getQueueStatusTopicName()
      If set, the name of the topic that the job queue's consumer topic publishes QueueStatusBeans to, to indicate that it is running.
      Returns:
      the queue status topic name, may be null

    • getJobQueueId

      UUID getJobQueueId()
      The UUID which uniquely defines this job queue.
      Returns:
      job queue id

    • getQueueStatus

      QueueStatus getQueueStatus()
      Returns the QueueStatus indicating whether the job queue's consumer thread is QueueStatus.RUNNING, QueueStatus.PAUSED or QueueStatus.STOPPED.
      Returns:
      the current status of the queue.

    • addQueueStatusListener

      void addQueueStatusListener(IJobQueue.IQueueStatusListener listener)

    • removeQueueStatusListener

      void removeQueueStatusListener(IJobQueue.IQueueStatusListener listener)

    • getName

      String getName()

    • setName

      void setName(String name)

    • isActive

      boolean isActive()
      Returns if the job queue is active. This is true as long as the consumer thread is not QueueStatus.STOPPED, i.e. it is QueueStatus.RUNNING or QueueStatus.PAUSED.
      Returns:
      true if the consumer is active

    • isPauseOnStart

      boolean isPauseOnStart()
      Returns whether the job queue's consumer thread will start in a paused state if the submission queue is non-empty. If the submission queue is empty this flag will have no effect.
      Returns:
      true if the consumer thread should start paused with a non-empty submission queue, false otherwise

    • setPauseOnStart

      void setPauseOnStart(boolean pauseOnStart)
      Sets whether the job queue's consumer thread should start in a paused state if the submission queue is non-empty. If the submission queue is empty this flag will have no effect. Note this must be called before the consumer thread is stared.
      Parameters:
      pauseOnStart - true if the consumer thread should start paused with a non-empty submission queue, false otherwise