Package org.pipservices3.messaging.queues

Interface IMessageQueue

All Superinterfaces:
org.pipservices3.commons.run.IClosable, org.pipservices3.commons.run.IOpenable
All Known Implementing Classes:
MemoryMessageQueue, MessageQueue
public interface IMessageQueue
extends org.pipservices3.commons.run.IOpenable
Interface for asynchronous message queues.

Not all queues may implement all the methods. Attempt to call non-supported method will result in NotImplemented exception. To verify if specific method is supported consult with MessagingCapabilities.

See Also:
MessageEnvelop, MessagingCapabilities

  • Method Summary

    Modifier and Type Method Description
    void abandon​(MessageEnvelop message)
    Returns 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.
    void complete​(MessageEnvelop message)
    Permanently removes a message from the queue.
    void endListen​(String correlationId)
    Ends listening for incoming messages.
    MessagingCapabilities getCapabilities()
    Gets the queue capabilities
    Long getMessageCount()
    Gets the current number of messages in the queue to be delivered.
    String getName()
    Gets the queue name
    void listen​(String correlationId, IMessageReceiver receiver)
    Listens for incoming messages and blocks the current thread until queue is closed.
    void moveToDeadLetter​(MessageEnvelop message)
    Permanently removes a message from the queue and sends it to dead letter queue.
    MessageEnvelop peek​(String correlationId)
    Peeks a single incoming message from the queue without removing it.
    List<MessageEnvelop> peekBatch​(String correlationId, int messageCount)
    Peeks multiple incoming messages from the queue without removing them.
    MessageEnvelop receive​(String correlationId, long waitTimeout)
    Receives an incoming message and removes it from the queue.
    void renewLock​(MessageEnvelop message, long lockTimeout)
    Renews a lock on a message that makes it invisible from other receivers in the queue.
    void send​(String correlationId, MessageEnvelop envelop)
    Sends a message into the queue.
    void sendAsObject​(String correlationId, String messageType, Object message)
    Sends an object into the queue.

    Methods inherited from interface org.pipservices3.commons.run.IClosable

    close

    Methods inherited from interface org.pipservices3.commons.run.IOpenable

    isOpen, open

  • Method Details

    • getName

      String getName()
      Gets the queue name
      Returns:
      the queue name.

    • getCapabilities

      MessagingCapabilities getCapabilities()
      Gets the queue capabilities
      Returns:
      the queue's capabilities object.

    • getMessageCount

      Long getMessageCount()
      Gets the current number of messages in the queue to be delivered.
      Returns:
      number of messages.

    • send

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

    • sendAsObject

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

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

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

      MessageEnvelop receive​(String correlationId, long waitTimeout) throws org.pipservices3.commons.errors.ApplicationException
      Receives an incoming message and removes it from the queue.
      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

      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.
      Parameters:
      message - a message to extend its lock.
      lockTimeout - a locking timeout in milliseconds.
      Throws:
      org.pipservices3.commons.errors.ApplicationException - when error occured.

    • complete

      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.
      Parameters:
      message - a message to remove.
      Throws:
      org.pipservices3.commons.errors.ApplicationException - when error occured.

    • abandon

      void abandon​(MessageEnvelop message) throws org.pipservices3.commons.errors.ApplicationException
      Returns 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.
      Parameters:
      message - a message to return.
      Throws:
      org.pipservices3.commons.errors.ApplicationException - when error occured.

    • moveToDeadLetter

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

    • listen

      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.
      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, receive(String, long)

    • beginListen

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

    • endListen

      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.
      Parameters:
      correlationId - (optional) transaction id to trace execution through call chain.
      Throws:
      org.pipservices3.commons.errors.ApplicationException - when error occured.