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
- message: MessageEnvelope - message to return.
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
- message: MessageEnvelope - message to remove.
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()
- returns: MessagingCapabilities - queue’s capabilities object.
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
- message: MessageEnvelope - message to be removed.
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: Promise<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: Promise<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