ServiceBusReceiverClient (Azure SDK for Java Reference Documentation)

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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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.
`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 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(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.
  - 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 is 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 is 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 is 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 is 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.
    
    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.
    
    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.
    
    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 ServiceBusReceiverClient.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.
  - 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.
    
    ServiceBusException - if an error occurs while receiving messages.
  - 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 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.
    
    IllegalStateException - if the receiver is a non-session receiver or the receiver is disposed.
  - 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

Visit the Azure for Java Developers site for more Java documentation, including quick starts, tutorials, and code samples.

Class ServiceBusReceiverClient

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getFullyQualifiedNamespace

getEntityPath

abandon

abandon

complete

complete

defer

defer

deadLetter

deadLetter

getSessionState

peekMessage

peekMessage

peekMessages

peekMessages

receiveMessages

receiveMessages

receiveDeferredMessage

receiveDeferredMessageBatch

renewMessageLock

renewMessageLock

renewSessionLock

renewSessionLock

setSessionState

createTransaction

commitTransaction

rollbackTransaction

close