org.pipservices.messaging.queues

Interface IMessageQueue

All Superinterfaces:

org.pipservices.commons.run.IClosable, org.pipservices.commons.run.IOpenable

All Known Implementing Classes:

MemoryMessageQueue, MessageQueue

public interface IMessageQueue
extends org.pipservices.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 and 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.pipservices.commons.run.IOpenable

isOpen, open

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

close

Method Detail

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.pipservices.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.pipservices.commons.errors.ApplicationException - when error occured.

sendAsObject

void sendAsObject(String correlationId,
                  String messageType,
                  Object message)
           throws org.pipservices.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.pipservices.commons.errors.ApplicationException - when error occured.

See Also:

send(String, MessageEnvelop)

peek

MessageEnvelop peek(String correlationId)
             throws org.pipservices.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.pipservices.commons.errors.ApplicationException - when error occured.

peekBatch

List<MessageEnvelop> peekBatch(String correlationId,
                               int messageCount)
                        throws org.pipservices.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.pipservices.commons.errors.ApplicationException - when error occured.

receive

MessageEnvelop receive(String correlationId,
                       long waitTimeout)
                throws org.pipservices.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.pipservices.commons.errors.ApplicationException - when error occured.

renewLock

void renewLock(MessageEnvelop message,
               long lockTimeout)
        throws org.pipservices.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.pipservices.commons.errors.ApplicationException - when error occured.

complete

void complete(MessageEnvelop message)
       throws org.pipservices.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.pipservices.commons.errors.ApplicationException - when error occured.

abandon

void abandon(MessageEnvelop message)
      throws org.pipservices.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.pipservices.commons.errors.ApplicationException - when error occured.

moveToDeadLetter

void moveToDeadLetter(MessageEnvelop message)
               throws org.pipservices.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.pipservices.commons.errors.ApplicationException - when error occured.

listen

void listen(String correlationId,
            IMessageReceiver receiver)
     throws org.pipservices.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.pipservices.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.pipservices.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.pipservices.commons.errors.ApplicationException - when error occured.