public final class ServiceBusReceiverClient extends Object implements AutoCloseable
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();
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.
|
public String getFullyQualifiedNamespace()
{yournamespace}.servicebus.windows.net
.public String getEntityPath()
public void abandon(ServiceBusReceivedMessage message)
message
. This will make the message available again for processing.
Abandoning a message will increase the delivery count on the message.message
- The ServiceBusReceivedMessage
to perform this operation.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.public void abandon(ServiceBusReceivedMessage message, AbandonOptions options)
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.message
- The ServiceBusReceivedMessage
to perform this operation.options
- The options to set while abandoning the message.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.public void complete(ServiceBusReceivedMessage message)
message
. This will delete the message from the service.message
- The ServiceBusReceivedMessage
to perform this operation.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.public void complete(ServiceBusReceivedMessage message, CompleteOptions options)
message
. This will delete the message from the service.message
- The ServiceBusReceivedMessage
to perform this operation.options
- Options used to complete the message.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.public void defer(ServiceBusReceivedMessage message)
message
. This will move message into the deferred subqueue.message
- The ServiceBusReceivedMessage
to perform this operation.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.public void defer(ServiceBusReceivedMessage message, DeferOptions options)
message
using its lock token with modified message property. This
will move message into the deferred sub-queue.message
- The ServiceBusReceivedMessage
to perform this operation.options
- Options used to defer the message.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.public void deadLetter(ServiceBusReceivedMessage message)
message
to the dead-letter sub-queue.message
- The ServiceBusReceivedMessage
to perform this operation.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.public void deadLetter(ServiceBusReceivedMessage message, DeadLetterOptions options)
message
to the dead-letter sub-queue with dead-letter reason, error
description, and/or modified properties.message
- The ServiceBusReceivedMessage
to perform this operation.options
- Options used to dead-letter the message.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.public byte[] getSessionState()
IllegalStateException
- if the receiver is a non-session receiver or receiver is already disposed.ServiceBusException
- if the session state could not be acquired.public ServiceBusReceivedMessage peekMessage()
peekMessage()
fetches the first active message for this receiver. Each subsequent call fetches the
subsequent message in the entity.ServiceBusReceivedMessage
.IllegalStateException
- if the receiver is already disposed.ServiceBusException
- if an error occurs while peeking at the message.public ServiceBusReceivedMessage peekMessage(long sequenceNumber)
sequenceNumber
- The sequence number from where to read the message.ServiceBusReceivedMessage
.IllegalStateException
- if the receiver is already disposed.ServiceBusException
- if an error occurs while peeking at the message.public com.azure.core.util.IterableStream<ServiceBusReceivedMessage> peekMessages(int maxMessages)
maxMessages
- The maximum number of messages to peek.IterableStream
of messages
that are peeked.IllegalArgumentException
- if maxMessages
is not a positive integer.IllegalStateException
- if the receiver is already disposed.ServiceBusException
- if an error occurs while peeking at messages.public com.azure.core.util.IterableStream<ServiceBusReceivedMessage> peekMessages(int maxMessages, long sequenceNumber)
maxMessages
- The number of messages.sequenceNumber
- The sequence number from where to start reading messages.IterableStream
of messages
peeked.IllegalArgumentException
- if maxMessages
is not a positive integer.IllegalStateException
- if the receiver is already disposed.ServiceBusException
- if an error occurs while peeking at messages.public com.azure.core.util.IterableStream<ServiceBusReceivedMessage> receiveMessages(int maxMessages)
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)
.maxMessages
- The maximum number of messages to receive.IterableStream
of at most maxMessages
messages from the Service Bus entity.IllegalArgumentException
- if maxMessages
is zero or a negative value.IllegalStateException
- if the receiver is already disposed.ServiceBusException
- if an error occurs while receiving messages.public com.azure.core.util.IterableStream<ServiceBusReceivedMessage> receiveMessages(int maxMessages, Duration maxWaitTime)
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)
.maxMessages
- The maximum number of messages to receive.maxWaitTime
- The time the client waits for receiving a message before it times out.IterableStream
of at most maxMessages
messages from the Service Bus entity.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.public ServiceBusReceivedMessage receiveDeferredMessage(long sequenceNumber)
message
. Deferred messages can only be received by using
sequence number.sequenceNumber
- The sequence number
of the
message.sequenceNumber
.IllegalStateException
- if receiver is already disposed.ServiceBusException
- if deferred message cannot be received.public com.azure.core.util.IterableStream<ServiceBusReceivedMessage> receiveDeferredMessageBatch(Iterable<Long> sequenceNumbers)
messages
. Deferred messages can only be received
by using sequence number.sequenceNumbers
- The sequence numbers of the deferred messages.IterableStream
of deferred messages
.NullPointerException
- if sequenceNumbers
is null.IllegalStateException
- if receiver is already disposed.ServiceBusException
- if deferred messages cannot be received.public OffsetDateTime renewMessageLock(ServiceBusReceivedMessage message)
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.message
- The ServiceBusReceivedMessage
to perform lock renewal.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.public void renewMessageLock(ServiceBusReceivedMessage message, Duration maxLockRenewalDuration, Consumer<Throwable> onError)
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.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.public OffsetDateTime renewSessionLock()
IllegalStateException
- if the receiver is a non-session receiver or receiver is already disposed.ServiceBusException
- if the session lock cannot be renewed.public void renewSessionLock(Duration maxLockRenewalDuration, Consumer<Throwable> onError)
maxLockRenewalDuration
- Maximum duration to keep renewing the session.onError
- A function to call when an error occurs during lock renewal.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.public void setSessionState(byte[] sessionState)
sessionState
- State to set on the session.IllegalStateException
- if the receiver is a non-session receiver or receiver is already disposed.ServiceBusException
- if the session state cannot be set.public ServiceBusTransactionContext createTransaction()
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);
ServiceBusTransactionContext
.IllegalStateException
- if the receiver is already disposed.ServiceBusException
- if a transaction cannot be created.public void commitTransaction(ServiceBusTransactionContext transactionContext)
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);
transactionContext
- The transaction to be commit.IllegalStateException
- if the receiver is already disposed.NullPointerException
- if transactionContext
or transactionContext.transactionId
is null.ServiceBusException
- if the transaction could not be committed.public void rollbackTransaction(ServiceBusTransactionContext transactionContext)
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);
transactionContext
- The transaction to be rollback.IllegalStateException
- if the receiver is alread disposed.NullPointerException
- if transactionContext
or transactionContext.transactionId
is null.ServiceBusException
- if the transaction could not be rolled back.public void close()
close
in interface AutoCloseable
Copyright © 2021 Microsoft Corporation. All rights reserved.