Package org.eclipse.scanning.api.event

Interface IEventService

All Known Implementing Classes:
EventServiceImpl
public interface IEventService
The scanning event service allows one to subscribe to and broadcast events. It may be backed by the MsgBus or plain JMS queues and topics depending on the service implementor.
  • IJobQueue encapsulates a queue that beans can be submitted to, and a consumer thread that removes items from the head of the queue and creates and runs a process for them. It also published bean updates to a status topic and can be controlled via a command topic;
  • ISubmitter to submit to a JMS queue.
  • IJmsQueueReader to read a JMS queue and submit any items found immediately to the IJobQueue.
  • IPublisher can be used to publish to a JMS topic. For example the IJobQueue implementation uses one to pubilsh bean update to the status topic;
  • ISubscriber can be used to subscribe to a JMS topic. For example this can be used to listen to bean updates from an IJobQueue as the process for a job is run;
  • IRequester to post a request to a topic and listen for a response.
  • IResponder to listen for requests on a topic and post a response. This

Note that ISubmitter and IJmsQueueReader are legacy interface and should not be used by new code. IJobQueue replaced IConsumer, which used to consume beans from the head of a JMS queue, it did not have its own submit method. An ISubmitter was required to submit beans to the tail of the queue. This is no longer necessary as IJobQueue contains a queue in memory and does have its own IJobQueue.submit(Object) method - on the client an proxy should be used by calling createJobQueueProxy(URI, String). Due to existing code still using submitters, or other mechanisms to submit a bean to a JMS queue to run a job, IJmsQueueReader was developed as a temporary measure. This works by running a loop consuming items from a JMS queue and immediately submitting them to the IJobQueue with the same submission queue name. 

 
   IEventService service = ... // OSGi
   final IEventSubscriber subscriber = service.createSubscriber(...);

   IScanListener listener = new IScanListener() { // Listen to any scan
       void scanEventPerformed(ScanEvent evt) {
           ScanBean scan = evt.getBean();
           System.out.println(scan.getName()+" @ "+scan.getPercentComplete());
       }
   };

   subscriber.addScanListener(listener);
   // Subscribe to anything



   IEventService service = ... // OSGi

   final IPublisher publisher = service.createPublisher(...);
   final ScanBean scan = new ScanBean(...);

   publisher.broadcast(scan);

   // An event comes internally that the scan has changed state, so we notify like this:
   scan.setPercentComplete(3.14);
   publisher.broadcast(scan);

  • Method Details

    • createSubscriber

      <T extends EventListener> ISubscriber<T> createSubscriber(URI uri, String topicName)
      Creates an ISubscriber for the topic with the given name. Useful on the client for adding event listeners to be notified. Scan events have a unique id with which to ascertain if a given scan event came from given scan.
      Parameters:
      uri - - the location of the JMS broker
      Returns:
      IEventManager

    • createAMQPSubscriber

      <T extends EventListener> ISubscriber<T> createAMQPSubscriber(URI uri, String routingKey)
      Creates an ISubscriber for an AMQP topic with a given routingKey.
      Parameters:
      uri - - the location of the JMS broker
      Returns:
      IEventManager

    • createPublisher

      <U> IPublisher<U> createPublisher(URI uri, String topicName)
      Creates an IEventPublisher for the topic with the given name.
      Parameters:
      uri - - the location of the JMS broker
      Returns:
      IEventManager

    • createSubmitter

      <U extends StatusBean> ISubmitter<U> createSubmitter(URI uri, String queueName)
      Create a submitter for adding a bean of type U onto the queue.
      Parameters:
      uri -
      queueName -
      Returns:
      the new submitter

    • createJobQueue

      <U extends StatusBean> IJobQueue<U> createJobQueue(URI uri) throws EventException
      Create an IJobQueue with the default submission queue, status topic and command topic names
      Parameters:
      uri -
      Returns:
      the new job queue
      Throws:
      EventException

    • createJobQueue

      <U extends StatusBean> IJobQueue<U> createJobQueue(URI uri, String submissionQueueName, String statusTopicName) throws EventException
      Create a consumer with the given submission queue, and status topic names.
      Parameters:
      uri -
      submissionQueueName - name of the submission queue
      statusTopicName -
      Returns:
      the new job queue
      Throws:
      EventException

    • createJobQueue

      <U extends StatusBean> IJobQueue<U> createJobQueue(URI uri, String submissionQueueName, String statusTopicName, String consumerStatusTopicName, String commandTopicName, String commandAckTopicName) throws EventException
      Create a job queue with the given submission queue, status queue, status topic, consumer status topic, command topic and command acknowledgement topic names.
      Parameters:
      uri - the uri of the message
      submissionQueueName -
      statusTopicName -
      commandTopicName -
      commandAckTopicName -
      Returns:
      the new job queue
      Throws:
      EventException

    • createJmsQueueReader

      <U extends StatusBean> IJmsQueueReader<U> createJmsQueueReader(URI uri, String submissionQueueName) throws EventException
      Create a Jms queue reader. This will read messages from the JMS (ActiveMq) queue with the given name and add it to the submission queue of the IJobQueue with the same name.
      Parameters:
      uri -
      submissionQueueName -
      Returns:
      the JMS queue reader
      Throws:
      EventException

    • getJobQueue

      IJobQueue<? extends StatusBean> getJobQueue(String submissionQueueName) throws EventException
      Returns the job queue for the given submission queue name. For server-side code only! Client-side code should use createJobQueueProxy(URI, String).
      Parameters:
      submissionQueueName -
      Returns:
      the consumer for the given queue name
      Throws:
      EventException - thrown if no job queue exists for the given queue name.

    • createJobQueueProxy

      <U extends StatusBean> IJobQueue<U> createJobQueueProxy(URI uri, String submissionQueueName) throws EventException
      Create a proxy for the IJobQueue for the given submission queue name, using the default command and command acknowledgement topics.
      Parameters:
      uri -
      submissionQueueName -
      Returns:
      a proxy to the job queue for the given queue name
      Throws:
      EventException

    • createJobQueueProxy

      <U extends StatusBean> IJobQueue<U> createJobQueueProxy(URI uri, String submissionQueueName, String commandTopicName, String commandAckTopicName) throws EventException
      Create a proxy for the IJobQueue for the given submission queue. The given command topic and command acknowledgement topic names are used to communicate with the job queue.
      Parameters:
      uri -
      submissionQueueName -
      commandTopicName -
      commandAckTopicName -
      Returns:
      a proxy to the job queue for the given queue name
      Throws:
      EventException

    • disposeJobQueue

      void disposeJobQueue(String submissionQueueName) throws EventException
      Disconnect the JMS resources used by the IJobQueue for the given submission queue name and unregisters it from this service.
      Parameters:
      submissionQueueName -
      Throws:
      EventException

    • disposeAllJobQueues

      void disposeAllJobQueues() throws EventException
      Disconnect all JMS resources used by all IJobQueues and unregisters them from this service.
      Throws:
      EventException

    • createRequestor

      <T extends IdBean> IRequester<T> createRequestor(URI uri, String requestTopic, String responseTopic) throws EventException
      A poster encapsulates sending and receiving a reply. For instance request a list of detectors on the server. This is the same as creating a broadcaster, sending an object then subscribing to the reply.
      Parameters:
      uri -
      requestTopic -
      responseTopic -
      Returns:
      Throws:
      EventException

    • createResponder

      <T extends IdBean> IResponder<T> createResponder(URI uri, String requestTopic, String responseTopic) throws EventException
      Creates a responder on a given topic.
      Parameters:
      uri -
      requestTopic -
      responseTopic -
      Returns:
      Throws:
      EventException

    • getEventConnectorService

      IEventConnectorService getEventConnectorService()
      The current event connector service that this event service is using to talk to messaging and to marshall objects.
      Returns:

    • createRemoteService

      <T> T createRemoteService(URI uri, Class<T> serviceClass) throws EventException
      Use this call to create a remote service. A wrapper will be created around the service such that methods called on the client will cause an event to trigger which has a response generated by the server. The event service caches remote services assuming that each service should exist once.
      Parameters:
      uri -
      serviceClass -
      Returns:
      Throws:
      EventException