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.

Future abandon(MessageEnvelope message)

beginListen

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

void beginListen(String? correlationId, IMessageReceiver receiver)

  • correlationId: String? - (optional) transaction id used to trace execution through the 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.

Future complete(MessageEnvelope message)

endListen

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

void endListen(String? correlationId)

  • correlationId: String? - (optional) transaction id used to trace execution through the call chain.

getCapabilities

Gets the queue capabilities

MessagingCapabilities getCapabilities()

getName

Gets the queue’s name

String getName()

  • returns: String - queue’s name.

listen

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

void listen(String? correlationId, IMessageReceiver receiver)

  • correlationId: String? - (optional) transaction id used to trace execution through the 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.

Future moveToDeadLetter(MessageEnvelope message)

peek

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

Future<MessageEnvelope?> peek(String? correlationId)

  • correlationId: String? - (optional) transaction id used to trace execution through the call chain.
  • returns: Future<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.

Future<List<MessageEnvelope?>> peekBatch(String? correlationId, int messageCount)

  • orrelation_id: String - (optional) transaction id used to trace execution through the call chain.
  • messageCount: int - maximum number of messages to peek.
  • returns: Future<List<MessageEnvelope?>> - peeked list with messages.

readMessageCount

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

Future<int> readMessageCount()

  • returns: Future<int> - number of messages.

receive

Receives an incoming message and removes it from the queue.

Future<MessageEnvelope?> receive(String? correlationId, int waitTimeout)

  • correlationId: String? - (optional) transaction id used to trace execution through the call chain.
  • waitTimeout: int - timeout in milliseconds to wait for a message to come.
  • returns: Future<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.

Future renewLock(MessageEnvelope message, int lockTimeout)

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

send

Sends a message into the queue.

Future send(String? correlationId, MessageEnvelope envelope)

  • correlationId: String? - (optional) transaction id used to trace execution through the 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.

Future sendAsObject(String? correlationId, String messageType, value)

  • correlationId: String? - (optional) transaction id used to trace execution through the call chain.
  • messageType: String - message type
  • value: dynamic - object value to be sent

See also