IMessageQueue

Interface for asynchronous message queues.

Extends: IOpenable, IClosable

Description

The IMessageQueue interface is used for asynchronous message queues.

Important points

  • Not all queues may implement all the methods.
  • An ttempt to call a non-supported method will result in a NotImplemented exception.
  • To verify if a specific method is supported check MessagingCapabilities.

Instance methods

abandon

Returns a 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 sent to dead letter queue.

void abandon(MessageEnvelope message) throws ApplicationException

beginListen

Listens for incoming messages without blocking the current thread.
See also IMessageReceiver, listen

void beginListen(IContext context, IMessageReceiver receiver)

  • context: IContext - (optional) a context to trace execution through a call chain.
  • receiver: IMessageReceiver - receiver used to receive incoming messages.

complete

Permanently removes a message from the queue. This method is usually used to remove the message after successful processing.

void complete(MessageEnvelope message) throws ApplicationException

endListen

Ends listening for incoming messages. When this method is called, listen unblocks the thread and execution continues.

void endListen(IContext context) throws ApplicationException

  • context: IContext - (optional) a context to trace execution through a call chain.

getCapabilities

Gets the queue capabilities

MessagingCapabilities getCapabilities()

getName

Gets the queue name

String getName()

  • returns: String - queue name.

listen

Listens for incoming messages and blocks the current thread until queue is closed.
See also IMessageReceiver, receive

void listen(IContext context, IMessageReceiver receiver) throws ApplicationException

  • context: IContext - (optional) a context to trace execution through a call chain.
  • receiver: IMessageReceiver - receiver used to receive incoming messages.

moveToDeadLetter

Permanently removes a message from the queue and sends it to the dead letter queue.

void moveToDeadLetter(MessagingCapabilities message) throws ApplicationException

peek

Peeks a single incoming message from the queue without removing it. If there are no messages available in the queue, it returns null.

MessageEnvelope peek(IContext context) throws ApplicationException

  • context: IContext - (optional) a context to trace execution through a call chain.
  • returns: MessageEnvelope - peeked message or null.

peekBatch

Peeks multiple incoming messages from the queue without removing them. If there are no messages available in the queue, it returns an empty list.

List<MessageEnvelope> peekBatch(IContext context, int messageCount) throws ApplicationException

  • context: IContext - (optional) a context to trace execution through a call chain.
  • messageCount: number - maximum number of messages to peek.
  • returns: MessageEnvelope[] - peeked list with messages.

readMessageCount

Reads the current number of messages in the queue to be delivered.

int readMessageCount()

  • returns: int - number of messages.

receive

Receives an incoming message and removes it from the queue.

MessageEnvelope receive(IContext context, long waitTimeout) throws ApplicationException

  • context: IContext - (optional) a context to trace execution through a call chain.
  • waitTimeout: number - timeout in milliseconds to wait for a message to come.
  • returns: MessageEnvelope - received message or null.

renewLock

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.

void renewLock(MessageEnvelope message, long lockTimeout) throws ApplicationException

  • message: MessageEnvelope - message to extend its lock.
  • lockTimeout: number - locking timeout in milliseconds.

send

Sends a message into the queue.

void send(IContext context, MessageEnvelope envelop) throws ApplicationException

  • context: IContext - (optional) a context to trace execution through a call chain.
  • envelope: MessageEnvelope - message envelop to be sent.

sendAsObject

Sends an object into the queue. Before being sent, the object is converted into JSON string and wrapped in a MessageEnvelope.

void sendAsObject(IContext context, String messageType, Object message) throws ApplicationException

  • context: IContext - (optional) a context to trace execution through a call chain.
  • messageType: String - message type
  • value: Object - object value to be sent

See also