Package 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

 // The required parameters is connectionString, a way to authenticate with Service Bus using credentials.
 // The connectionString/queueName must be set by the application. The 'connectionString' format is shown below.
 // "Endpoint={fully-qualified-namespace};SharedAccessKeyName={policy-name};SharedAccessKey={key}"
 ServiceBusReceiverClient receiver = new ServiceBusClientBuilder()
     .connectionString(connectionString)
     .receiver()
     .queueName(queueName)
     .buildClient();

 // Use the receiver and finally close it.
 receiver.close();
 

See Also:

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

Method Summary

Modifier and Type	Method	Description
void	abandon(ServiceBusReceivedMessage message)	Abandons a message.
void	abandon(ServiceBusReceivedMessage message, AbandonOptions options)	Abandons a message and updates the message's properties.
void	close()	Disposes of the consumer by closing the underlying links to the service.
void	commitTransaction(ServiceBusTransactionContext transactionContext)	Commits the transaction and all the operations associated with it.
void	complete(ServiceBusReceivedMessage message)	Completes a message.
void	complete(ServiceBusReceivedMessage message, CompleteOptions options)	Completes a message.
ServiceBusTransactionContext	createTransaction()	Starts a new transaction on Service Bus.
void	deadLetter(ServiceBusReceivedMessage message)	Moves a message to the dead-letter sub-queue.
void	deadLetter(ServiceBusReceivedMessage message, DeadLetterOptions options)	Moves a message to the dead-letter sub-queue with dead-letter reason, error description, and/or modified properties.
void	defer(ServiceBusReceivedMessage message)	Defers a message.
void	defer(ServiceBusReceivedMessage message, DeferOptions options)	Defers a message using its lock token with modified message property.
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.
String	getIdentifier()	Gets the identifier of the instance of ServiceBusReceiverClient.
String	getSessionId()	Gets the SessionId of the session if this receiver is a session receiver.
byte[]	getSessionState()	Gets the state of the session if this receiver is a session receiver.
ServiceBusReceivedMessage	peekMessage()	Reads the next active message without changing the state of the receiver or the message source.
ServiceBusReceivedMessage	peekMessage(long sequenceNumber)	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>	peekMessages(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>	peekMessages(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.
ServiceBusReceivedMessage	receiveDeferredMessage(long sequenceNumber)	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>	receiveMessages(int maxMessages)	Receives an iterable stream of messages from the Service Bus entity.
com.azure.core.util.IterableStream<ServiceBusReceivedMessage>	receiveMessages(int maxMessages, Duration maxWaitTime)	Receives an iterable stream of messages from the Service Bus entity.
OffsetDateTime	renewMessageLock(ServiceBusReceivedMessage message)	Renews the lock on the specified message.
void	renewMessageLock(ServiceBusReceivedMessage message, Duration maxLockRenewalDuration, Consumer<Throwable> onError)	Starts the auto lock renewal for a message with the given lock.
OffsetDateTime	renewSessionLock()	Sets the state of the session if this receiver is a session receiver.
void	renewSessionLock(Duration maxLockRenewalDuration, Consumer<Throwable> onError)	Starts the auto lock renewal for the session that this receiver works for.
void	rollbackTransaction(ServiceBusTransactionContext transactionContext)	Rollbacks the transaction given and all operations associated with it.
void	setSessionState(byte[] sessionState)	Sets the state of the session if this receiver is a session receiver.

Methods inherited from class java.lang.Object

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

Method Details

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.

getSessionId

public String getSessionId()

Gets the SessionId of the session if this receiver is a session receiver.

Returns:

The SessionId or null if this is not a session receiver.

getIdentifier

public String getIdentifier()

Gets the identifier of the instance of ServiceBusReceiverClient.

Returns:

The identifier that can identify the instance of ServiceBusReceiverClient.

abandon

public void abandon(ServiceBusReceivedMessage message)

Abandons a message. This will make the message available again for processing. Abandoning a message will increase the delivery count on the message.

Parameters:

message - The ServiceBusReceivedMessage to perform this operation.

Throws:

NullPointerException - if message is null.

UnsupportedOperationException - if the receiver was opened in ServiceBusReceiveMode.RECEIVE_AND_DELETE mode or if the message was received from peekMessage.

IllegalStateException - if receiver is already disposed.

ServiceBusException - if the message could not be abandoned.

IllegalArgumentException - if the message has either been deleted or already settled.

abandon

public void abandon(ServiceBusReceivedMessage message,
 AbandonOptions options)

Abandons a message 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:

message - The ServiceBusReceivedMessage to perform this operation.

options - The options to set while abandoning the message.

Throws:

NullPointerException - if message or options is null. Also if transactionContext.transactionId is null when options.transactionContext is specified.

UnsupportedOperationException - if the receiver was opened in ServiceBusReceiveMode.RECEIVE_AND_DELETE mode or if the message was received from peekMessage.

IllegalStateException - if receiver is already disposed.

IllegalArgumentException - if the message has either been deleted or already settled.

ServiceBusException - if the message could not be abandoned.

complete

public void complete(ServiceBusReceivedMessage message)

Completes a message. This will delete the message from the service.

Parameters:

message - The ServiceBusReceivedMessage to perform this operation.

Throws:

NullPointerException - if message is null.

UnsupportedOperationException - if the receiver was opened in ServiceBusReceiveMode.RECEIVE_AND_DELETE mode or if the message was received from peekMessage.

IllegalStateException - if receiver is already disposed.

IllegalArgumentException - if the message has either been deleted or already settled.

ServiceBusException - if the message could not be completed.

complete

public void complete(ServiceBusReceivedMessage message,
 CompleteOptions options)

Completes a message. This will delete the message from the service.

Parameters:

message - The ServiceBusReceivedMessage to perform this operation.

options - Options used to complete the message.

Throws:

NullPointerException - if message or options is null. Also if transactionContext.transactionId is null when options.transactionContext is specified.

UnsupportedOperationException - if the receiver was opened in ServiceBusReceiveMode.RECEIVE_AND_DELETE mode or if the message was received from peekMessage.

IllegalStateException - if receiver is already disposed.

IllegalArgumentException - if the message has either been deleted or already settled.

ServiceBusException - if the message could not be completed.

defer

public void defer(ServiceBusReceivedMessage message)

Defers a message. This will move message into the deferred subqueue.

Parameters:

message - The ServiceBusReceivedMessage to perform this operation.

Throws:

NullPointerException - if message is null.

UnsupportedOperationException - if the receiver was opened in ServiceBusReceiveMode.RECEIVE_AND_DELETE mode or if the message was received from peekMessage.

IllegalStateException - if receiver is already disposed.

ServiceBusException - if the message could not be deferred.

IllegalArgumentException - if the message has either been deleted or already settled.

See Also:

• Message deferral

defer

public void defer(ServiceBusReceivedMessage message,
 DeferOptions options)

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

Parameters:

message - The ServiceBusReceivedMessage to perform this operation.

options - Options used to defer the message.

Throws:

NullPointerException - if message or options is null. Also if transactionContext.transactionId is null when options.transactionContext is specified.

UnsupportedOperationException - if the receiver was opened in ServiceBusReceiveMode.RECEIVE_AND_DELETE mode or if the message was received from peekMessage.

IllegalStateException - if receiver is already disposed.

ServiceBusException - if the message could not be deferred.

IllegalArgumentException - if the message has either been deleted or already settled.

See Also:

• Message deferral

deadLetter

public void deadLetter(ServiceBusReceivedMessage message)

Moves a message to the dead-letter sub-queue.

Parameters:

message - The ServiceBusReceivedMessage to perform this operation.

Throws:

NullPointerException - if message is null.

UnsupportedOperationException - if the receiver was opened in ServiceBusReceiveMode.RECEIVE_AND_DELETE mode or if the message was received from peekMessage.

IllegalStateException - if receiver is already disposed.

ServiceBusException - if the message could not be dead-lettered.

IllegalArgumentException - if the message has either been deleted or already settled.

See Also:

• Dead letter queues

deadLetter

public void deadLetter(ServiceBusReceivedMessage message,
 DeadLetterOptions options)

Moves a message to the dead-letter sub-queue with dead-letter reason, error description, and/or modified properties.

Parameters:

message - The ServiceBusReceivedMessage to perform this operation.

options - Options used to dead-letter the message.

Throws:

NullPointerException - if message or options is null. Also if transactionContext.transactionId is null when options.transactionContext is specified.

UnsupportedOperationException - if the receiver was opened in ServiceBusReceiveMode.RECEIVE_AND_DELETE mode or if the message was received from peekMessage.

IllegalStateException - if the receiver is already disposed of.

ServiceBusException - if the message could not be dead-lettered.

IllegalArgumentException - if the message has either been deleted or already settled.

See Also:

• Dead letter queues

getSessionState

public byte[] getSessionState()

Gets the state of the session if this receiver is a session receiver.

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 or receiver is already disposed.

ServiceBusException - if the session state could not be acquired.

peekMessage

public ServiceBusReceivedMessage peekMessage()

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

Returns:

A peeked ServiceBusReceivedMessage.

Throws:

IllegalStateException - if the receiver is already disposed.

ServiceBusException - if an error occurs while peeking at the message.

See Also:

• Message browsing

peekMessage

public ServiceBusReceivedMessage peekMessage(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.

Throws:

IllegalStateException - if the receiver is already disposed.

ServiceBusException - if an error occurs while peeking at the message.

See Also:

• Message browsing

peekMessages

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

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

Parameters:

maxMessages - The maximum number of messages to peek.

Returns:

An IterableStream of messages that are peeked.

Throws:

IllegalArgumentException - if maxMessages is not a positive integer.

IllegalStateException - if the receiver is already disposed.

ServiceBusException - if an error occurs while peeking at messages.

See Also:

• Message browsing

peekMessages

public com.azure.core.util.IterableStream<ServiceBusReceivedMessage> peekMessages(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 messages peeked.

Throws:

IllegalArgumentException - if maxMessages is not a positive integer.

IllegalStateException - if the receiver is already disposed.

ServiceBusException - if an error occurs while peeking at messages.

See Also:

• Message browsing

receiveMessages

public com.azure.core.util.IterableStream<ServiceBusReceivedMessage> receiveMessages(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 override it by using receiveMessages(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.

IllegalStateException - if the receiver is already disposed.

ServiceBusException - if an error occurs while receiving messages.

See Also:

• Synchronous receive and prefetch

receiveMessages

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

Receives an iterable stream of messages from the Service Bus entity. The default receive mode is ServiceBusReceiveMode.PEEK_LOCK unless it is changed during creation of ServiceBusReceiverClient using ServiceBusClientBuilder.ServiceBusReceiverClientBuilder.receiveMode(ServiceBusReceiveMode).

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.

IllegalStateException - if the receiver is already disposed.

NullPointerException - if maxWaitTime is null.

ServiceBusException - if an error occurs while receiving messages.

See Also:

• Synchronous receive and prefetch

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.

Throws:

IllegalStateException - if receiver is already disposed.

ServiceBusException - if deferred message cannot be received.

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.

Throws:

NullPointerException - if sequenceNumbers is null.

IllegalStateException - if receiver is already disposed.

ServiceBusException - if deferred messages cannot be received.

renewMessageLock

public OffsetDateTime renewMessageLock(ServiceBusReceivedMessage message)

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 ServiceBusReceiveMode.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:

message - The ServiceBusReceivedMessage to perform lock renewal.

Returns:

The new expiration time for the message.

Throws:

NullPointerException - if message or message.getLockToken() is null.

UnsupportedOperationException - if the receiver was opened in ServiceBusReceiveMode.RECEIVE_AND_DELETE mode or if the message was received from peekMessage.

IllegalStateException - if the receiver is a session receiver or receiver is already disposed.

IllegalArgumentException - if message.getLockToken() is an empty value.

renewMessageLock

public void renewMessageLock(ServiceBusReceivedMessage message,
 Duration maxLockRenewalDuration,
 Consumer<Throwable> onError)

Starts the auto lock renewal for a message with the given lock.

Parameters:

message - The ServiceBusReceivedMessage to perform auto-lock renewal.

maxLockRenewalDuration - Maximum duration to keep renewing the lock token.

onError - A function to call when an error occurs during lock renewal.

Throws:

NullPointerException - if message, message.getLockToken(), or maxLockRenewalDuration is null.

IllegalStateException - if the receiver is a session receiver or the receiver is disposed.

IllegalArgumentException - if message.getLockToken() is an empty value.

ServiceBusException - If the message cannot be renewed.

renewSessionLock

public OffsetDateTime renewSessionLock()

Sets the state of the session if this receiver is a session receiver.

Returns:

The next expiration time for the session lock.

Throws:

IllegalStateException - if the receiver is a non-session receiver or receiver is already disposed.

ServiceBusException - if the session lock cannot be renewed.

renewSessionLock

public void renewSessionLock(Duration maxLockRenewalDuration,
 Consumer<Throwable> onError)

Starts the auto lock renewal for the session that this receiver works for.

Parameters:

maxLockRenewalDuration - Maximum duration to keep renewing the session.

onError - A function to call when an error occurs during lock renewal.

Throws:

NullPointerException - if sessionId or maxLockRenewalDuration is null.

IllegalArgumentException - if sessionId is an empty string or maxLockRenewalDuration is negative.

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

ServiceBusException - if the session lock renewal operation cannot be started.

setSessionState

public void setSessionState(byte[] sessionState)

Sets the state of the session if this receiver is a session receiver.

Parameters:

sessionState - State to set on the session.

Throws:

IllegalStateException - if the receiver is a non-session receiver or receiver is already disposed.

ServiceBusException - if the session state cannot be set.

createTransaction

public ServiceBusTransactionContext createTransaction()

Starts a new transaction on Service Bus. The ServiceBusTransactionContext should be passed along to all operations that need to be in this transaction.

Creating and using a transaction

 ServiceBusTransactionContext transaction = receiver.createTransaction();

 // Process messages and associate operations with the transaction.
 ServiceBusReceivedMessage deferredMessage = receiver.receiveDeferredMessage(sequenceNumber);
 receiver.complete(deferredMessage, new CompleteOptions().setTransactionContext(transaction));
 receiver.abandon(receivedMessage, new AbandonOptions().setTransactionContext(transaction));
 receiver.commitTransaction(transaction);
 

Returns:

A new ServiceBusTransactionContext.

Throws:

IllegalStateException - if the receiver is already disposed.

ServiceBusException - if a transaction cannot be created.

commitTransaction

public void commitTransaction(ServiceBusTransactionContext transactionContext)

Commits the transaction and all the operations associated with it.

Creating and using a transaction

 ServiceBusTransactionContext transaction = receiver.createTransaction();

 // Process messages and associate operations with the transaction.
 ServiceBusReceivedMessage deferredMessage = receiver.receiveDeferredMessage(sequenceNumber);
 receiver.complete(deferredMessage, new CompleteOptions().setTransactionContext(transaction));
 receiver.abandon(receivedMessage, new AbandonOptions().setTransactionContext(transaction));
 receiver.commitTransaction(transaction);
 

Parameters:

transactionContext - The transaction to be commit.

Throws:

IllegalStateException - if the receiver is already disposed.

NullPointerException - if transactionContext or transactionContext.transactionId is null.

ServiceBusException - if the transaction could not be committed.

rollbackTransaction

public void rollbackTransaction(ServiceBusTransactionContext transactionContext)

Rollbacks the transaction given and all operations associated with it.

Creating and using a transaction

 ServiceBusTransactionContext transaction = receiver.createTransaction();

 // Process messages and associate operations with the transaction.
 ServiceBusReceivedMessage deferredMessage = receiver.receiveDeferredMessage(sequenceNumber);
 receiver.complete(deferredMessage, new CompleteOptions().setTransactionContext(transaction));
 receiver.abandon(receivedMessage, new AbandonOptions().setTransactionContext(transaction));
 receiver.commitTransaction(transaction);
 

Parameters:

transactionContext - The transaction to be rollback.

Throws:

IllegalStateException - if the receiver is alread disposed.

NullPointerException - if transactionContext or transactionContext.transactionId is null.

ServiceBusException - if the transaction could not be rolled back.

close

public void close()

Disposes of the consumer by closing the underlying links to the service.

Specified by:

close in interface AutoCloseable