Package version:

Interface ServiceBusSessionReceiver

A receiver that handles sessions, including renewing the session lock.

interface ServiceBusSessionReceiver {
    entityPath: string;
    identifier: string;
    isClosed: boolean;
    receiveMode: "peekLock" | "receiveAndDelete";
    sessionId: string;
    sessionLockedUntilUtc: Date;
    abandonMessage(message, propertiesToModify?): Promise<void>;
    close(): Promise<void>;
    completeMessage(message): Promise<void>;
    deadLetterMessage(message, options?): Promise<void>;
    deferMessage(message, propertiesToModify?): Promise<void>;
    getMessageIterator(options?): AsyncIterableIterator<ServiceBusReceivedMessage>;
    getSessionState(options?): Promise<any>;
    peekMessages(maxMessageCount, options?): Promise<ServiceBusReceivedMessage[]>;
    receiveDeferredMessages(sequenceNumbers, options?): Promise<ServiceBusReceivedMessage[]>;
    receiveMessages(maxMessageCount, options?): Promise<ServiceBusReceivedMessage[]>;
    renewMessageLock(message): Promise<Date>;
    renewSessionLock(options?): Promise<Date>;
    setSessionState(state, options?): Promise<void>;
    subscribe(handlers, options?): {
        close(): Promise<void>;
    };
}

Hierarchy (view full)

Properties

entityPath identifier isClosed receiveMode sessionId sessionLockedUntilUtc

Methods

abandonMessage close completeMessage deadLetterMessage deferMessage getMessageIterator getSessionState peekMessages receiveDeferredMessages receiveMessages renewMessageLock renewSessionLock setSessionState subscribe

Properties

entityPath

entityPath: string

Path of the entity for which the receiver has been created.

identifier

identifier: string

A name used to identify the receiver. This can be used to correlate logs and exceptions. If not specified or empty, a random unique one will be generated.

Readonly isClosed

isClosed: boolean

Returns true if either the receiver or the client that created it has been closed.

receiveMode

receiveMode: "peekLock" | "receiveAndDelete"

The receive mode used to create the receiver.

Readonly sessionId

sessionId: string

The session ID.

Readonly sessionLockedUntilUtc

sessionLockedUntilUtc: Date

The time in UTC until which the session is locked. Every time renewSessionLock() is called, this time gets updated to current time plus the lock duration as specified during the Queue/Subscription creation.

Will return undefined until a AMQP receiver link has been successfully set up for the session.

Methods

abandonMessage

  • abandonMessage(message, propertiesToModify?): Promise<void>

  • The lock held on the message by the receiver is let go, making the message available again in Service Bus for another receive operation.

    Parameters

    • message: ServiceBusReceivedMessage
    • Optional propertiesToModify: {
          [key: string]: number | boolean | string | Date | null;
      }

      The properties of the message to modify while abandoning the message.

      • [key: string]: number | boolean | string | Date | null

    Returns Promise<void>

    Throws

    ServiceBusError with the code SessionLockLost (for messages from a Queue/Subscription with sessions enabled) if the AMQP link with which the message was received is no longer alive. This can happen either because the lock on the session expired or the receiver was explicitly closed by the user or the AMQP link is closed by the library due to network loss or service error.

    Throws

    ServiceBusError with the code MessageLockLost (for messages from a Queue/Subscription with sessions not enabled) if the lock on the message has expired or the AMQP link with which the message was received is no longer alive. The latter can happen if the receiver was explicitly closed by the user or the AMQP link got closed by the library due to network loss or service error.

    Throws

    Error if the message is already settled. property on the message if you are not sure whether the message is settled.

    Throws

    Error if used in receiveAndDelete mode because all messages received in this mode are pre-settled. To avoid this error, update your code to not settle a message which is received in this mode.

    Throws

    ServiceBusError with the code ServiceTimeout if Service Bus does not acknowledge the request to settle the message in time. The message may or may not have been settled successfully.

close

  • close(): Promise<void>

  • Closes the receiver. Once closed, the receiver cannot be used for any further operations. Use the createReceiver() method on the ServiceBusClient to create a new Receiver.

    Returns Promise<void>

completeMessage

  • completeMessage(message): Promise<void>

  • Removes the message from Service Bus.

    Parameters

    Returns Promise<void>

    Throws

    Error with name SessionLockLostError (for messages from a Queue/Subscription with sessions enabled) if the AMQP link with which the message was received is no longer alive. This can happen either because the lock on the session expired or the receiver was explicitly closed by the user or the AMQP link is closed by the library due to network loss or service error.

    Throws

    Error with name MessageLockLostError (for messages from a Queue/Subscription with sessions not enabled) if the lock on the message has expired or the AMQP link with which the message was received is no longer alive. The latter can happen if the receiver was explicitly closed by the user or the AMQP link got closed by the library due to network loss or service error.

    Throws

    Error if the message is already settled. property on the message if you are not sure whether the message is settled.

    Throws

    Error if used in receiveAndDelete mode because all messages received in this mode are pre-settled. To avoid this error, update your code to not settle a message which is received in this mode.

    Throws

    Error with name ServiceUnavailableError if Service Bus does not acknowledge the request to settle the message in time. The message may or may not have been settled successfully.

deadLetterMessage

  • deadLetterMessage(message, options?): Promise<void>

  • Moves the message to the deadletter sub-queue. To receive a deadletted message, create a new QueueClient/SubscriptionClient using the path for the deadletter sub-queue.

    Parameters

    • message: ServiceBusReceivedMessage
    • Optional options: DeadLetterOptions & {
          [key: string]: number | boolean | string | Date | null;
      }

      The DeadLetter options that can be provided while rejecting the message.

    Returns Promise<void>

    Throws

    ServiceBusError with the code SessionLockLost (for messages from a Queue/Subscription with sessions enabled) if the AMQP link with which the message was received is no longer alive. This can happen either because the lock on the session expired or the receiver was explicitly closed by the user or the AMQP link is closed by the library due to network loss or service error.

    Throws

    ServiceBusError with the code MessageLockLost (for messages from a Queue/Subscription with sessions not enabled) if the lock on the message has expired or the AMQP link with which the message was received is no longer alive. The latter can happen if the receiver was explicitly closed by the user or the AMQP link got closed by the library due to network loss or service error.

    Throws

    Error if the message is already settled. property on the message if you are not sure whether the message is settled.

    Throws

    Error if used in receiveAndDelete mode because all messages received in this mode are pre-settled. To avoid this error, update your code to not settle a message which is received in this mode.

    Throws

    ServiceBusError with the code ServiceTimeout if Service Bus does not acknowledge the request to settle the message in time. The message may or may not have been settled successfully.

deferMessage

  • deferMessage(message, propertiesToModify?): Promise<void>

  • Defers the processing of the message. Save the sequenceNumber of the message, in order to receive it message again in the future using the receiveDeferredMessage method.

    Parameters

    • message: ServiceBusReceivedMessage
    • Optional propertiesToModify: {
          [key: string]: number | boolean | string | Date | null;
      }

      The properties of the message to modify while deferring the message

      • [key: string]: number | boolean | string | Date | null

    Returns Promise<void>

    Throws

    ServiceBusError with the code SessionLockLost (for messages from a Queue/Subscription with sessions enabled) if the AMQP link with which the message was received is no longer alive. This can happen either because the lock on the session expired or the receiver was explicitly closed by the user or the AMQP link is closed by the library due to network loss or service error.

    Throws

    ServiceBusError with the code MessageLockLost (for messages from a Queue/Subscription with sessions not enabled) if the lock on the message has expired or the AMQP link with which the message was received is no longer alive. The latter can happen if the receiver was explicitly closed by the user or the AMQP link got closed by the library due to network loss or service error.

    Throws

    Error if the message is already settled. property on the message if you are not sure whether the message is settled.

    Throws

    Error if used in receiveAndDelete mode because all messages received in this mode are pre-settled. To avoid this error, update your code to not settle a message which is received in this mode.

    Throws

    ServiceBusError with the code ServiceTimeout if Service Bus does not acknowledge the request to settle the message in time. The message may or may not have been settled successfully.

getMessageIterator

  • getMessageIterator(options?): AsyncIterableIterator<ServiceBusReceivedMessage>

  • Returns an iterator that can be used to receive messages from Service Bus.

    Parameters

    • Optional options: GetMessageIteratorOptions

      A set of options to control the receive operation.

      • abortSignal: The signal to use to abort the ongoing operation.

    Returns AsyncIterableIterator<ServiceBusReceivedMessage>

    Throws

    Error if the underlying connection, client or receiver is closed.

    Throws

    Error if current receiver is already in state of receiving messages.

    Throws

    ServiceBusError if the service returns an error while receiving messages.

getSessionState

  • getSessionState(options?): Promise<any>

  • Gets the state of the Session. For more on session states, see Session State

    Parameters

    Returns Promise<any>

    The state of that session

    Throws

    Error if the underlying connection or receiver is closed.

    Throws

    ServiceBusError if the service returns an error while retrieving session state.

peekMessages

  • peekMessages(maxMessageCount, options?): Promise<ServiceBusReceivedMessage[]>

  • Peek the next batch of active messages (including deferred but not deadlettered messages) on the queue or subscription without modifying them.

    • The first call to peekMessages() fetches the first active message. Each subsequent call fetches the subsequent message.
    • Unlike a "received" message, "peeked" message is a read-only version of the message. It cannot be Completed/Abandoned/Deferred/Deadlettered.

    Parameters

    • maxMessageCount: number

      The maximum number of messages to peek.

    • Optional options: PeekMessagesOptions

      Options that allow to specify the maximum number of messages to peek, the sequenceNumber to start peeking from or an abortSignal to abort the operation.

    Returns Promise<ServiceBusReceivedMessage[]>

receiveDeferredMessages

  • receiveDeferredMessages(sequenceNumbers, options?): Promise<ServiceBusReceivedMessage[]>

  • Returns a promise that resolves to an array of deferred messages identified by given sequenceNumbers.

    Parameters

    • sequenceNumbers: any

      The sequence number or an array of sequence numbers for the messages that need to be received.

    • Optional options: OperationOptionsBase

      Options bag to pass an abort signal or tracing options.

    Returns Promise<ServiceBusReceivedMessage[]>

    A list of messages identified by the given sequenceNumbers or an empty list if no messages are found.

    Throws

    Error if the underlying connection or receiver is closed.

    Throws

    ServiceBusError if the service returns an error while receiving deferred messages.

receiveMessages

  • receiveMessages(maxMessageCount, options?): Promise<ServiceBusReceivedMessage[]>

  • Returns a promise that resolves to an array of messages received from Service Bus.

    Parameters

    • maxMessageCount: number

      The maximum number of messages to receive.

    • Optional options: ReceiveMessagesOptions

      A set of options to control the receive operation.

      • maxWaitTimeInMs: The maximum time to wait for the first message before returning an empty array if no messages are available.
      • abortSignal: The signal to use to abort the ongoing operation.

    Returns Promise<ServiceBusReceivedMessage[]>

    A promise that resolves with an array of messages.

    Throws

    Error if the underlying connection, client or receiver is closed.

    Throws

    Error if current receiver is already in state of receiving messages.

    Throws

    ServiceBusError if the service returns an error while receiving messages.

renewMessageLock

  • renewMessageLock(message): Promise<Date>

  • Renews the lock on the message for the duration as specified during the Queue/Subscription creation.

    • Check the lockedUntilUtc property on the message for the time when the lock expires.
    • If a message is not settled (using either complete(), defer() or deadletter(), before its lock expires, then the message lands back in the Queue/Subscription for the next receive operation.

    Parameters

    Returns Promise<Date>

    New lock token expiry date and time in UTC format.

    Throws

    Error if the underlying connection, client or receiver is closed.

    Throws

    ServiceBusError if the service returns an error while renewing message lock.

renewSessionLock

setSessionState

  • setSessionState(state, options?): Promise<void>

  • Sets the state on the Session. For more on session states, see Session State

    Parameters

    • state: any

      The state that needs to be set.

    • Optional options: OperationOptionsBase

      Options bag to pass an abort signal or tracing options.

    Returns Promise<void>

    Throws

    Error if the underlying connection or receiver is closed.

    Throws

    ServiceBusError if the service returns an error while setting the session state.

subscribe

  • subscribe(handlers, options?): {
        close(): Promise<void>;
    }

  • Streams messages to message handlers.

    Parameters

    Returns {
        close(): Promise<void>;
    }

    An object that can be closed, sending any remaining messages to handlers and stopping new messages from arriving.

Settings

Member Visibility

Theme

Generated using TypeDoc