Package org.pipservices3.messaging.queues

Class MessageQueue

java.lang.Object
org.pipservices3.messaging.queues.MessageQueue
All Implemented Interfaces:
org.pipservices3.commons.config.IConfigurable, org.pipservices3.commons.refer.IReferenceable, org.pipservices3.commons.run.IClosable, org.pipservices3.commons.run.IOpenable, IMessageQueue
Direct Known Subclasses:
MemoryMessageQueue
public abstract class MessageQueue
extends Object
implements IMessageQueue, org.pipservices3.commons.refer.IReferenceable, org.pipservices3.commons.config.IConfigurable, org.pipservices3.commons.run.IOpenable, org.pipservices3.commons.run.IClosable
Abstract message queue that is used as a basis for specific message queue implementations.

### Configuration parameters ###

  • name: name of the message queue
  • connection(s):
    • discovery_key: key to retrieve parameters from discovery service
    • protocol: connection protocol like http, https, tcp, udp
    • host: host name or IP address
    • port: port number
    • uri: resource URI or connection string with all parameters in it
  • credential(s):
    • store_key: key to retrieve parameters from credential store
    • username: user name
    • password: user password
    • access_id: application access id
    • access_key: application secret key

### References ###

  • *:logger:*:*:1.0 (optional) ILogger components to pass log messages
  • *:counters:*:*:1.0 (optional) ICounters components to pass collected measurements
  • *:discovery:*:*:1.0 (optional) IDiscovery services to resolve connection
  • *:credential-store:*:*:1.0 (optional) ICredentialStore componetns to lookup credential(s)

  • Field Summary

    Fields
    Modifier and Type Field Description
    protected MessagingCapabilities _capabilities  
    protected org.pipservices3.components.connect.ConnectionResolver _connectionResolver  
    protected org.pipservices3.components.count.CompositeCounters _counters  
    protected org.pipservices3.components.auth.CredentialResolver _credentialResolver  
    protected String _kind  
    protected Object _lock  
    protected org.pipservices3.components.log.CompositeLogger _logger  
    protected String _name  

  • Constructor Summary

    Constructors
    Constructor Description
    MessageQueue()
    Creates a new instance of the message queue.
    MessageQueue​(String name)
    Creates a new instance of the message queue.
    MessageQueue​(String name, org.pipservices3.commons.config.ConfigParams config)
    Creates a new instance of the message queue.

  • Method Summary

    Modifier and Type Method Description
    abstract void abandon​(MessageEnvelop message)
    Returnes message into the queue and makes it available for all subscribers to receive it again.
    void beginListen​(String correlationId, IMessageReceiver receiver)
    Listens for incoming messages without blocking the current thread.
    abstract void clear​(String correlationId)
    Clears component state.
    abstract void close​(String correlationId)
    Closes component and frees used resources.
    abstract void complete​(MessageEnvelop message)
    Permanently removes a message from the queue.
    void configure​(org.pipservices3.commons.config.ConfigParams config)
    Configures component by passing configuration parameters.
    abstract void endListen​(String correlationId)
    Ends listening for incoming messages.
    MessagingCapabilities getCapabilities()
    Gets the queue capabilities
    abstract Long getMessageCount()
    Gets the current number of messages in the queue to be delivered.
    String getName()
    Gets the queue name
    abstract boolean isOpen()
    Checks if the component is opened.
    abstract void listen​(String correlationId, IMessageReceiver receiver)
    Listens for incoming messages and blocks the current thread until queue is closed.
    abstract void moveToDeadLetter​(MessageEnvelop message)
    Permanently removes a message from the queue and sends it to dead letter queue.
    void open​(String correlationId)
    Opens the component.
    abstract void open​(String correlationId, org.pipservices3.components.connect.ConnectionParams connection, org.pipservices3.components.auth.CredentialParams credential)
    Opens the component with given connection and credential parameters.
    abstract MessageEnvelop peek​(String correlationId)
    Peeks a single incoming message from the queue without removing it.
    abstract List<MessageEnvelop> peekBatch​(String correlationId, int messageCount)
    Peeks multiple incoming messages from the queue without removing them.
    abstract MessageEnvelop receive​(String correlationId, long waitTimeout)
    Receives an incoming message and removes it from the queue.
    abstract void renewLock​(MessageEnvelop message, long lockTimeout)
    Renews a lock on a message that makes it invisible from other receivers in the queue.
    abstract void send​(String correlationId, MessageEnvelop message)
    Sends a message into the queue.
    void sendAsObject​(String correlationId, String messageType, Object message)
    Sends an object into the queue.
    void setReferences​(org.pipservices3.commons.refer.IReferences references)
    Sets references to dependent components.
    String toString()
    Gets a string representation of the object.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • _name

      protected String _name

    • _kind

      protected String _kind

    • _capabilities

      protected MessagingCapabilities _capabilities

    • _lock

      protected Object _lock

    • _logger

      protected org.pipservices3.components.log.CompositeLogger _logger

    • _counters

      protected org.pipservices3.components.count.CompositeCounters _counters

    • _connectionResolver

      protected org.pipservices3.components.connect.ConnectionResolver _connectionResolver

    • _credentialResolver

      protected org.pipservices3.components.auth.CredentialResolver _credentialResolver

  • Constructor Details

    • MessageQueue

      public MessageQueue()
      Creates a new instance of the message queue.

    • MessageQueue

      public MessageQueue​(String name)
      Creates a new instance of the message queue.
      Parameters:
      name - (optional) a queue name

    • MessageQueue

      public MessageQueue​(String name, org.pipservices3.commons.config.ConfigParams config)
      Creates a new instance of the message queue.
      Parameters:
      name - (optional) a queue name
      config - configuration parameters

  • Method Details

    • configure

      public void configure​(org.pipservices3.commons.config.ConfigParams config)
      Configures component by passing configuration parameters.
      Specified by:
      configure in interface org.pipservices3.commons.config.IConfigurable
      Parameters:
      config - configuration parameters to be set.

    • setReferences

      public void setReferences​(org.pipservices3.commons.refer.IReferences references) throws org.pipservices3.commons.refer.ReferenceException
      Sets references to dependent components.
      Specified by:
      setReferences in interface org.pipservices3.commons.refer.IReferenceable
      Parameters:
      references - references to locate the component dependencies.
      Throws:
      org.pipservices3.commons.refer.ReferenceException - when no found references.

    • getName

      public String getName()
      Gets the queue name
      Specified by:
      getName in interface IMessageQueue
      Returns:
      the queue name.

    • getCapabilities

      public MessagingCapabilities getCapabilities()
      Gets the queue capabilities
      Specified by:
      getCapabilities in interface IMessageQueue
      Returns:
      the queue's capabilities object.

    • getMessageCount

      public abstract Long getMessageCount()
      Description copied from interface: IMessageQueue
      Gets the current number of messages in the queue to be delivered.
      Specified by:
      getMessageCount in interface IMessageQueue
      Returns:
      number of messages.

    • isOpen

      public abstract boolean isOpen()
      Checks if the component is opened.
      Specified by:
      isOpen in interface org.pipservices3.commons.run.IOpenable
      Returns:
      true if the component has been opened and false otherwise.

    • open

      public void open​(String correlationId) throws org.pipservices3.commons.errors.ApplicationException
      Opens the component.
      Specified by:
      open in interface org.pipservices3.commons.run.IOpenable
      Parameters:
      correlationId - (optional) transaction id to trace execution through call chain.
      Throws:
      org.pipservices3.commons.errors.ApplicationException - when error occured.

    • open

      public abstract void open​(String correlationId, org.pipservices3.components.connect.ConnectionParams connection, org.pipservices3.components.auth.CredentialParams credential) throws org.pipservices3.commons.errors.ApplicationException
      Opens the component with given connection and credential parameters.
      Parameters:
      correlationId - (optional) transaction id to trace execution through call chain.
      connection - connection parameters
      credential - credential parameters
      Throws:
      org.pipservices3.commons.errors.ApplicationException - when error occured.

    • close

      public abstract void close​(String correlationId) throws org.pipservices3.commons.errors.ApplicationException
      Closes component and frees used resources.
      Specified by:
      close in interface org.pipservices3.commons.run.IClosable
      Parameters:
      correlationId - (optional) transaction id to trace execution through call chain.
      Throws:
      org.pipservices3.commons.errors.ApplicationException - when error occured.

    • clear

      public abstract void clear​(String correlationId) throws org.pipservices3.commons.errors.ApplicationException
      Clears component state.
      Parameters:
      correlationId - (optional) transaction id to trace execution through call chain.
      Throws:
      org.pipservices3.commons.errors.ApplicationException - when error occured.

    • send

      public abstract void send​(String correlationId, MessageEnvelop message) throws org.pipservices3.commons.errors.ApplicationException
      Sends a message into the queue.
      Specified by:
      send in interface IMessageQueue
      Parameters:
      correlationId - (optional) transaction id to trace execution through call chain.
      message - a message envelop to be sent.
      Throws:
      org.pipservices3.commons.errors.ApplicationException - when error occured.

    • sendAsObject

      public void sendAsObject​(String correlationId, String messageType, Object message) throws org.pipservices3.commons.errors.ApplicationException
      Sends an object into the queue. Before sending the object is converted into JSON string and wrapped in a [[MessageEnvelop]].
      Specified by:
      sendAsObject in interface IMessageQueue
      Parameters:
      correlationId - (optional) transaction id to trace execution through call chain.
      messageType - a message type
      message - an object value to be sent
      Throws:
      org.pipservices3.commons.errors.ApplicationException - when error occured.
      See Also:
      send(String, MessageEnvelop)

    • peek

      public abstract MessageEnvelop peek​(String correlationId) throws org.pipservices3.commons.errors.ApplicationException
      Peeks a single incoming message from the queue without removing it. If there are no messages available in the queue it returns null.
      Specified by:
      peek in interface IMessageQueue
      Parameters:
      correlationId - (optional) transaction id to trace execution through call chain.
      Returns:
      a message envelop object.
      Throws:
      org.pipservices3.commons.errors.ApplicationException - when error occured.

    • peekBatch

      public abstract List<MessageEnvelop> peekBatch​(String correlationId, int messageCount) throws org.pipservices3.commons.errors.ApplicationException
      Peeks multiple incoming messages from the queue without removing them. If there are no messages available in the queue it returns an empty list.
      Specified by:
      peekBatch in interface IMessageQueue
      Parameters:
      correlationId - (optional) transaction id to trace execution through call chain.
      messageCount - a maximum number of messages to peek.
      Returns:
      a list with messages.
      Throws:
      org.pipservices3.commons.errors.ApplicationException - when error occured.

    • receive

      public abstract MessageEnvelop receive​(String correlationId, long waitTimeout) throws org.pipservices3.commons.errors.ApplicationException
      Receives an incoming message and removes it from the queue.
      Specified by:
      receive in interface IMessageQueue
      Parameters:
      correlationId - (optional) transaction id to trace execution through call chain.
      waitTimeout - a timeout in milliseconds to wait for a message to come.
      Returns:
      a message envelop object.
      Throws:
      org.pipservices3.commons.errors.ApplicationException - when error occured.

    • renewLock

      public abstract void renewLock​(MessageEnvelop message, long lockTimeout) throws org.pipservices3.commons.errors.ApplicationException
      Renews a lock on a message that makes it invisible from other receivers in the queue. This method is usually used to extend the message processing time.
      Specified by:
      renewLock in interface IMessageQueue
      Parameters:
      message - a message to extend its lock.
      lockTimeout - a locking timeout in milliseconds.
      Throws:
      org.pipservices3.commons.errors.ApplicationException - when error occured.

    • abandon

      public abstract void abandon​(MessageEnvelop message) throws org.pipservices3.commons.errors.ApplicationException
      Returnes message into the queue and makes it available for all subscribers to receive it again. This method is usually used to return a message which could not be processed at the moment to repeat the attempt. Messages that cause unrecoverable errors shall be removed permanently or/and send to dead letter queue.
      Specified by:
      abandon in interface IMessageQueue
      Parameters:
      message - a message to return.
      Throws:
      org.pipservices3.commons.errors.ApplicationException - when error occured.

    • complete

      public abstract void complete​(MessageEnvelop message) throws org.pipservices3.commons.errors.ApplicationException
      Permanently removes a message from the queue. This method is usually used to remove the message after successful processing.
      Specified by:
      complete in interface IMessageQueue
      Parameters:
      message - a message to remove.
      Throws:
      org.pipservices3.commons.errors.ApplicationException - when error occured.

    • moveToDeadLetter

      public abstract void moveToDeadLetter​(MessageEnvelop message) throws org.pipservices3.commons.errors.ApplicationException
      Permanently removes a message from the queue and sends it to dead letter queue.
      Specified by:
      moveToDeadLetter in interface IMessageQueue
      Parameters:
      message - a message to be removed.
      Throws:
      org.pipservices3.commons.errors.ApplicationException - when error occured.

    • listen

      public abstract void listen​(String correlationId, IMessageReceiver receiver) throws org.pipservices3.commons.errors.ApplicationException
      Listens for incoming messages and blocks the current thread until queue is closed.
      Specified by:
      listen in interface IMessageQueue
      Parameters:
      correlationId - (optional) transaction id to trace execution through call chain.
      receiver - a receiver to receive incoming messages.
      Throws:
      org.pipservices3.commons.errors.ApplicationException - when error occured.
      See Also:
      IMessageReceiver

    • beginListen

      public void beginListen​(String correlationId, IMessageReceiver receiver)
      Listens for incoming messages without blocking the current thread.
      Specified by:
      beginListen in interface IMessageQueue
      Parameters:
      correlationId - (optional) transaction id to trace execution through call chain.
      receiver - a receiver to receive incoming messages.
      See Also:
      IMessageReceiver

    • endListen

      public abstract void endListen​(String correlationId) throws org.pipservices3.commons.errors.ApplicationException
      Ends listening for incoming messages. When this method is call [[listen]] unblocks the thread and execution continues.
      Specified by:
      endListen in interface IMessageQueue
      Parameters:
      correlationId - (optional) transaction id to trace execution through call chain.
      Throws:
      org.pipservices3.commons.errors.ApplicationException - when error occured.

    • toString

      public String toString()
      Gets a string representation of the object.
      Overrides:
      toString in class Object
      Returns:
      a string representation of the object.