com.azure.messaging.servicebus

Class ServiceBusReceiverClient

java.lang.Object

com.azure.messaging.servicebus.ServiceBusReceiverClient

All Implemented Interfaces:

AutoCloseable

public final class ServiceBusReceiverClient
extends Object
implements AutoCloseable

A synchronous receiver responsible for receiving ServiceBusReceivedMessage from a specific queue or topic on Azure Service Bus.

Create an instance of receiver

 ServiceBusReceiverClient receiver = new ServiceBusClientBuilder()
     .connectionString(
         "Endpoint={eh-namespace};SharedAccessKeyName={policy-name};SharedAccessKey={key};"
             + "Entity-Path={hub-name}")
     .receiver()
     .queueName("<< QUEUE NAME >>")
     .buildClient();
 

See Also:

ServiceBusClientBuilder, To communicate with a Service Bus resource using an asynchronous client.

Method Summary

Modifier and Type	Method and Description
void	abandon(MessageLockToken lockToken) Abandon a message with its lock token.
void	abandon(MessageLockToken lockToken, Map<String,Object> propertiesToModify) Abandon a message with its lock token and updates the message's properties.
void	abandon(MessageLockToken lockToken, Map<String,Object> propertiesToModify, String sessionId) Abandon a message with its lock token and updates the message's properties.
void	close()
void	complete(MessageLockToken lockToken) Completes a message using its lock token.
void	complete(MessageLockToken lockToken, String sessionId) Completes a message using its lock token.
void	deadLetter(MessageLockToken lockToken) Moves a message to the deadletter sub-queue.
void	deadLetter(MessageLockToken lockToken, DeadLetterOptions deadLetterOptions) Moves a message to the deadletter subqueue with deadletter reason, error description, and/or modified properties.
void	deadLetter(MessageLockToken lockToken, DeadLetterOptions deadLetterOptions, String sessionId) Moves a message to the deadletter subqueue with deadletter reason, error description, and/or modified properties.
void	deadLetter(MessageLockToken lockToken, String sessionId) Moves a message to the deadletter sub-queue.
void	defer(MessageLockToken lockToken) Defers a message using its lock token.
void	defer(MessageLockToken lockToken, Map<String,Object> propertiesToModify) Defers a message using its lock token with modified message property.
void	defer(MessageLockToken lockToken, Map<String,Object> propertiesToModify, String sessionId) Defers a message using its lock token with modified message property.
void	defer(MessageLockToken lockToken, String sessionId) Defers a message using its lock token.
String	getEntityPath() Gets the Service Bus resource this client interacts with.
String	getFullyQualifiedNamespace() Gets the fully qualified Service Bus namespace that the connection is associated with.
byte[]	getSessionState(String sessionId) Gets the state of a session given its identifier.
ServiceBusReceivedMessage	peek() Reads the next active message without changing the state of the receiver or the message source.
ServiceBusReceivedMessage	peek(String sessionId) Reads the next active message without changing the state of the receiver or the message source.
ServiceBusReceivedMessage	peekAt(long sequenceNumber) Starting from the given sequence number, reads next the active message without changing the state of the receiver or the message source.
ServiceBusReceivedMessage	peekAt(long sequenceNumber, String sessionId) Starting from the given sequence number, reads next the active message without changing the state of the receiver or the message source.
com.azure.core.util.IterableStream<ServiceBusReceivedMessage>	peekBatch(int maxMessages) Reads the next batch of active messages without changing the state of the receiver or the message source.
com.azure.core.util.IterableStream<ServiceBusReceivedMessage>	peekBatch(int maxMessages, String sessionId) Reads the next batch of active messages without changing the state of the receiver or the message source.
com.azure.core.util.IterableStream<ServiceBusReceivedMessage>	peekBatchAt(int maxMessages, long sequenceNumber) Starting from the given sequence number, reads the next batch of active messages without changing the state of the receiver or the message source.
com.azure.core.util.IterableStream<ServiceBusReceivedMessage>	peekBatchAt(int maxMessages, long sequenceNumber, String sessionId) Starting from the given sequence number, reads the next batch of active messages without changing the state of the receiver or the message source.
com.azure.core.util.IterableStream<ServiceBusReceivedMessageContext>	receive(int maxMessages) Receives an iterable stream of messages from the Service Bus entity.
com.azure.core.util.IterableStream<ServiceBusReceivedMessageContext>	receive(int maxMessages, Duration maxWaitTime) Receives an iterable stream of messages from the Service Bus entity.
ServiceBusReceivedMessage	receiveDeferredMessage(long sequenceNumber) Receives a deferred message.
ServiceBusReceivedMessage	receiveDeferredMessage(long sequenceNumber, String sessionId) Receives a deferred message.
com.azure.core.util.IterableStream<ServiceBusReceivedMessage>	receiveDeferredMessageBatch(Iterable<Long> sequenceNumbers) Receives a batch of deferred messages.
com.azure.core.util.IterableStream<ServiceBusReceivedMessage>	receiveDeferredMessageBatch(Iterable<Long> sequenceNumbers, String sessionId) Receives a batch of deferred messages.
Instant	renewMessageLock(MessageLockToken lockToken) Renews the lock on the specified message.
Instant	renewSessionLock(String sessionId) Sets the state of a session given its identifier.
void	setSessionState(String sessionId, byte[] sessionState) Sets the state of a session given its identifier.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getFullyQualifiedNamespace

public String getFullyQualifiedNamespace()

Gets the fully qualified Service Bus namespace that the connection is associated with. This is likely similar to {yournamespace}.servicebus.windows.net.

Returns:

The fully qualified Service Bus namespace that the connection is associated with.

getEntityPath

public String getEntityPath()

Gets the Service Bus resource this client interacts with.

Returns:

The Service Bus resource this client interacts with.

abandon

public void abandon(MessageLockToken lockToken)

Abandon a message with its lock token. This will make the message available again for processing. Abandoning a message will increase the delivery count on the message.

Parameters:

lockToken - Lock token of the message.

Throws:

NullPointerException - if lockToken is null.

UnsupportedOperationException - if the receiver was opened in ReceiveMode.RECEIVE_AND_DELETE mode.

IllegalArgumentException - if MessageLockToken.getLockToken() returns a null lock token.

abandon

public void abandon(MessageLockToken lockToken,
                    Map<String,Object> propertiesToModify)

Abandon a message with its lock token and updates the message's properties. This will make the message available again for processing. Abandoning a message will increase the delivery count on the message.

Parameters:

lockToken - Lock token of the message.

propertiesToModify - Properties to modify on the message.

Throws:

NullPointerException - if lockToken is null.

UnsupportedOperationException - if the receiver was opened in ReceiveMode.RECEIVE_AND_DELETE mode.

IllegalArgumentException - if MessageLockToken.getLockToken() returns a null lock token.

abandon

public void abandon(MessageLockToken lockToken,
                    Map<String,Object> propertiesToModify,
                    String sessionId)

Abandon a message with its lock token and updates the message's properties. This will make the message available again for processing. Abandoning a message will increase the delivery count on the message.

Parameters:

lockToken - Lock token of the message.

propertiesToModify - Properties to modify on the message.

sessionId - Session id of the message to abandon. null if there is no session.

Throws:

NullPointerException - if lockToken is null.

UnsupportedOperationException - if the receiver was opened in ReceiveMode.RECEIVE_AND_DELETE mode.

IllegalArgumentException - if MessageLockToken.getLockToken() returns a null lock token.

complete

public void complete(MessageLockToken lockToken)

Completes a message using its lock token. This will delete the message from the service.

Parameters:

lockToken - Lock token of the message.

Throws:

NullPointerException - if lockToken is null.

UnsupportedOperationException - if the receiver was opened in ReceiveMode.RECEIVE_AND_DELETE mode.

IllegalArgumentException - if MessageLockToken.getLockToken() returns a null lock token.

complete

public void complete(MessageLockToken lockToken,
                     String sessionId)

Completes a message using its lock token. This will delete the message from the service.

Parameters:

lockToken - Lock token of the message.

sessionId - Session id of the message to complete. null if there is no session.

Throws:

NullPointerException - if lockToken is null.

UnsupportedOperationException - if the receiver was opened in ReceiveMode.RECEIVE_AND_DELETE mode.

IllegalArgumentException - if MessageLockToken.getLockToken() returns a null lock token.

defer

public void defer(MessageLockToken lockToken)

Defers a message using its lock token. This will move message into the deferred subqueue.

Parameters:

lockToken - Lock token of the message.

Throws:

NullPointerException - if lockToken is null.

UnsupportedOperationException - if the receiver was opened in ReceiveMode.RECEIVE_AND_DELETE mode.

IllegalArgumentException - if MessageLockToken.getLockToken() returns a null lock token.

See Also:

Message deferral

defer

public void defer(MessageLockToken lockToken,
                  String sessionId)

Defers a message using its lock token. This will move message into the deferred subqueue.

Parameters:

lockToken - Lock token of the message.

sessionId - Session id of the message to defer. null if there is no session.

Throws:

NullPointerException - if lockToken is null.

UnsupportedOperationException - if the receiver was opened in ReceiveMode.RECEIVE_AND_DELETE mode.

IllegalArgumentException - if MessageLockToken.getLockToken() returns a null lock token.

See Also:

Message deferral

defer

public void defer(MessageLockToken lockToken,
                  Map<String,Object> propertiesToModify)

Defers a message using its lock token with modified message property. This will move message into the deferred subqueue.

Parameters:

lockToken - Lock token of the message.

propertiesToModify - Message properties to modify.

Throws:

NullPointerException - if lockToken is null.

UnsupportedOperationException - if the receiver was opened in ReceiveMode.RECEIVE_AND_DELETE mode.

IllegalArgumentException - if MessageLockToken.getLockToken() returns a null lock token.

See Also:

Message deferral

defer

public void defer(MessageLockToken lockToken,
                  Map<String,Object> propertiesToModify,
                  String sessionId)

Defers a message using its lock token with modified message property. This will move message into the deferred subqueue.

Parameters:

lockToken - Lock token of the message.

propertiesToModify - Message properties to modify.

sessionId - Session id of the message to defer. null if there is no session.

Throws:

NullPointerException - if lockToken is null.

UnsupportedOperationException - if the receiver was opened in ReceiveMode.RECEIVE_AND_DELETE mode.

IllegalArgumentException - if MessageLockToken.getLockToken() returns a null lock token.

See Also:

Message deferral

deadLetter

public void deadLetter(MessageLockToken lockToken)

Moves a message to the deadletter sub-queue.

Parameters:

lockToken - Lock token of the message.

Throws:

NullPointerException - if lockToken is null.

UnsupportedOperationException - if the receiver was opened in ReceiveMode.RECEIVE_AND_DELETE mode.

IllegalArgumentException - if MessageLockToken.getLockToken() returns a null lock token.

See Also:

Dead letter queues

deadLetter

public void deadLetter(MessageLockToken lockToken,
                       String sessionId)

Moves a message to the deadletter sub-queue.

Parameters:

lockToken - Lock token of the message.

sessionId - Session id of the message to deadletter. null if there is no session.

Throws:

NullPointerException - if lockToken is null.

UnsupportedOperationException - if the receiver was opened in ReceiveMode.RECEIVE_AND_DELETE mode.

IllegalArgumentException - if MessageLockToken.getLockToken() returns a null lock token.

See Also:

Dead letter queues

deadLetter

public void deadLetter(MessageLockToken lockToken,
                       DeadLetterOptions deadLetterOptions)

Moves a message to the deadletter subqueue with deadletter reason, error description, and/or modified properties.

Parameters:

lockToken - Lock token of the message.

deadLetterOptions - The options to specify when moving message to the deadletter sub-queue.

Throws:

NullPointerException - if lockToken is null.

UnsupportedOperationException - if the receiver was opened in ReceiveMode.RECEIVE_AND_DELETE mode.

IllegalArgumentException - if MessageLockToken.getLockToken() returns a null lock token.

deadLetter

public void deadLetter(MessageLockToken lockToken,
                       DeadLetterOptions deadLetterOptions,
                       String sessionId)

Moves a message to the deadletter subqueue with deadletter reason, error description, and/or modified properties.

Parameters:

lockToken - Lock token of the message.

deadLetterOptions - The options to specify when moving message to the deadletter sub-queue.

sessionId - Session id of the message to deadletter. null if there is no session.

Throws:

NullPointerException - if lockToken is null.

UnsupportedOperationException - if the receiver was opened in ReceiveMode.RECEIVE_AND_DELETE mode.

IllegalArgumentException - if MessageLockToken.getLockToken() returns a null lock token.

getSessionState

public byte[] getSessionState(String sessionId)

Gets the state of a session given its identifier.

Parameters:

sessionId - Identifier of session to get.

Returns:

The session state or null if there is no state set for the session.

Throws:

IllegalStateException - if the receiver is a non-session receiver.

peek

public ServiceBusReceivedMessage peek()

Reads the next active message without changing the state of the receiver or the message source. The first call to peek() fetches the first active message for this receiver. Each subsequent call fetches the subsequent message in the entity.

Returns:

A peeked ServiceBusReceivedMessage.

See Also:

Message browsing

peek

public ServiceBusReceivedMessage peek(String sessionId)

Reads the next active message without changing the state of the receiver or the message source. The first call to peek() fetches the first active message for this receiver. Each subsequent call fetches the subsequent message in the entity.

Parameters:

sessionId - Session id of the message to peek from. null if there is no session.

Returns:

A peeked ServiceBusReceivedMessage.

See Also:

Message browsing

peekAt

public ServiceBusReceivedMessage peekAt(long sequenceNumber)

Starting from the given sequence number, reads next the active message without changing the state of the receiver or the message source.

Parameters:

sequenceNumber - The sequence number from where to read the message.

Returns:

A peeked ServiceBusReceivedMessage.

See Also:

Message browsing

peekAt

public ServiceBusReceivedMessage peekAt(long sequenceNumber,
                                        String sessionId)

Starting from the given sequence number, reads next the active message without changing the state of the receiver or the message source.

Parameters:

sequenceNumber - The sequence number from where to read the message.

sessionId - Session id of the message to peek from. null if there is no session.

Returns:

A peeked ServiceBusReceivedMessage.

See Also:

Message browsing

peekBatch

public com.azure.core.util.IterableStream<ServiceBusReceivedMessage> peekBatch(int maxMessages)

Reads the next batch of active messages without changing the state of the receiver or the message source.

Parameters:

maxMessages - The number of messages.

Returns:

An IterableStream of messages that are peeked.

Throws:

IllegalArgumentException - if maxMessages is not a positive integer.

See Also:

Message browsing

peekBatch

public com.azure.core.util.IterableStream<ServiceBusReceivedMessage> peekBatch(int maxMessages,
                                                                               String sessionId)

Reads the next batch of active messages without changing the state of the receiver or the message source.

Parameters:

maxMessages - The number of messages.

sessionId - Session id of the messages to peek from. null if there is no session.

Returns:

An IterableStream of messages that are peeked.

Throws:

IllegalArgumentException - if maxMessages is not a positive integer.

See Also:

Message browsing

peekBatchAt

public com.azure.core.util.IterableStream<ServiceBusReceivedMessage> peekBatchAt(int maxMessages,
                                                                                 long sequenceNumber)

Starting from the given sequence number, reads the next batch of active messages without changing the state of the receiver or the message source.

Parameters:

maxMessages - The number of messages.

sequenceNumber - The sequence number from where to start reading messages.

Returns:

An IterableStream of ServiceBusReceivedMessage peeked.

Throws:

IllegalArgumentException - if maxMessages is not a positive integer.

See Also:

Message browsing

peekBatchAt

public com.azure.core.util.IterableStream<ServiceBusReceivedMessage> peekBatchAt(int maxMessages,
                                                                                 long sequenceNumber,
                                                                                 String sessionId)

Starting from the given sequence number, reads the next batch of active messages without changing the state of the receiver or the message source.

Parameters:

maxMessages - The number of messages.

sequenceNumber - The sequence number from where to start reading messages.

sessionId - Session id of the messages to peek from. null if there is no session.

Returns:

An IterableStream of ServiceBusReceivedMessage peeked.

Throws:

IllegalArgumentException - if maxMessages is not a positive integer.

See Also:

Message browsing

receive

public com.azure.core.util.IterableStream<ServiceBusReceivedMessageContext> receive(int maxMessages)

Receives an iterable stream of messages from the Service Bus entity. The receive operation will wait for a default 1 minute for receiving a message before it times out. You can it override by using ServiceBusReceiverClient.receive(int, Duration).

Parameters:

maxMessages - The maximum number of messages to receive.

Returns:

An IterableStream of at most maxMessages messages from the Service Bus entity.

Throws:

IllegalArgumentException - if maxMessages is zero or a negative value.

receive

public com.azure.core.util.IterableStream<ServiceBusReceivedMessageContext> receive(int maxMessages,
                                                                                    Duration maxWaitTime)

Receives an iterable stream of messages from the Service Bus entity.

Parameters:

maxMessages - The maximum number of messages to receive.

maxWaitTime - The time the client waits for receiving a message before it times out.

Returns:

An IterableStream of at most maxMessages messages from the Service Bus entity.

Throws:

IllegalArgumentException - if maxMessages or maxWaitTime is zero or a negative value.

receiveDeferredMessage

public ServiceBusReceivedMessage receiveDeferredMessage(long sequenceNumber)

Receives a deferred message. Deferred messages can only be received by using sequence number.

Parameters:

sequenceNumber - The sequence number of the message.

Returns:

A deferred message with the matching sequenceNumber.

receiveDeferredMessage

public ServiceBusReceivedMessage receiveDeferredMessage(long sequenceNumber,
                                                        String sessionId)

Receives a deferred message. Deferred messages can only be received by using sequence number.

Parameters:

sequenceNumber - The sequence number of the message.

sessionId - Session id of the deferred message.

Returns:

A deferred message with the matching sequenceNumber.

receiveDeferredMessageBatch

public com.azure.core.util.IterableStream<ServiceBusReceivedMessage> receiveDeferredMessageBatch(Iterable<Long> sequenceNumbers)

Receives a batch of deferred messages. Deferred messages can only be received by using sequence number.

Parameters:

sequenceNumbers - The sequence numbers of the deferred messages.

Returns:

An IterableStream of deferred messages.

receiveDeferredMessageBatch

public com.azure.core.util.IterableStream<ServiceBusReceivedMessage> receiveDeferredMessageBatch(Iterable<Long> sequenceNumbers,
                                                                                                 String sessionId)

Receives a batch of deferred messages. Deferred messages can only be received by using sequence number.

Parameters:

sequenceNumbers - The sequence numbers of the deferred messages.

sessionId - Session id of the deferred messages. null if there is no session.

Returns:

An IterableStream of deferred messages.

renewMessageLock

public Instant renewMessageLock(MessageLockToken lockToken)

Renews the lock on the specified message. The lock will be renewed based on the setting specified on the entity. When a message is received in ReceiveMode.PEEK_LOCK mode, the message is locked on the server for this receiver instance for a duration as specified during the Queue creation (LockDuration). If processing of the message requires longer than this duration, the lock needs to be renewed. For each renewal, the lock is reset to the entity's LockDuration value.

Parameters:

lockToken - Lock token of the message to renew.

Returns:

The new expiration time for the message.

Throws:

NullPointerException - if lockToken is null.

UnsupportedOperationException - if the receiver was opened in ReceiveMode.RECEIVE_AND_DELETE mode.

IllegalArgumentException - if MessageLockToken.getLockToken() returns a null lock token.

IllegalStateException - if the receiver is a session receiver.

renewSessionLock

public Instant renewSessionLock(String sessionId)

Sets the state of a session given its identifier.

Parameters:

sessionId - Identifier of session to get.

Returns:

The next expiration time for the session lock.

Throws:

IllegalStateException - if the receiver is a non-session receiver.

setSessionState

public void setSessionState(String sessionId,
                            byte[] sessionState)

Sets the state of a session given its identifier.

Parameters:

sessionId - Identifier of session to get.

sessionState - State to set on the session.

Throws:

IllegalStateException - if the receiver is a non-session receiver.

close

public void close()

Specified by:

close in interface AutoCloseable