com.azure.messaging.servicebus.ServiceBusSessionReceiverAsyncClient.yml

### YamlMime:JavaType
uid: "com.azure.messaging.servicebus.ServiceBusSessionReceiverAsyncClient"
fullName: "com.azure.messaging.servicebus.ServiceBusSessionReceiverAsyncClient"
name: "ServiceBusSessionReceiverAsyncClient"
nameWithType: "ServiceBusSessionReceiverAsyncClient"
summary: "This **asynchronous** session receiver client is used to acquire session locks from a queue or topic and create <xref uid=\"com.azure.messaging.servicebus.ServiceBusReceiverAsyncClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"ServiceBusReceiverAsyncClient\"></xref> instances that are tied to the locked sessions."
inheritances:
- "<xref href=\"java.lang.Object?displayProperty=fullName\" data-throw-if-not-resolved=\"False\" />"
inheritedClassMethods:
- classRef: "java.lang.<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html\">Object</a>"
  methodsRef:
  - "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#clone--\">clone</a>"
  - "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#equals-java.lang.Object-\">equals</a>"
  - "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#finalize--\">finalize</a>"
  - "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#getClass--\">getClass</a>"
  - "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#hashCode--\">hashCode</a>"
  - "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#notify--\">notify</a>"
  - "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#notifyAll--\">notifyAll</a>"
  - "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#toString--\">toString</a>"
  - "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait--\">wait</a>"
  - "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait-long-\">wait</a>"
  - "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait-long-int-\">wait</a>"
syntax: "public final class **ServiceBusSessionReceiverAsyncClient**</br> implements <a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/AutoCloseable.html\">AutoCloseable</a>"
methods:
- uid: "com.azure.messaging.servicebus.ServiceBusSessionReceiverAsyncClient.acceptNextSession()"
  fullName: "com.azure.messaging.servicebus.ServiceBusSessionReceiverAsyncClient.acceptNextSession()"
  name: "acceptNextSession()"
  nameWithType: "ServiceBusSessionReceiverAsyncClient.acceptNextSession()"
  summary: "Acquires a session lock for the next available session and creates a <xref uid=\"com.azure.messaging.servicebus.ServiceBusReceiverAsyncClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"ServiceBusReceiverAsyncClient\"></xref> to receive messages from the session."
  syntax: "public Mono<ServiceBusReceiverAsyncClient> acceptNextSession()"
  desc: "Acquires a session lock for the next available session and creates a <xref uid=\"com.azure.messaging.servicebus.ServiceBusReceiverAsyncClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"ServiceBusReceiverAsyncClient\"></xref> to receive messages from the session. It will wait until a session is available if none is immediately available."
  returns:
    description: "A <xref uid=\"com.azure.messaging.servicebus.ServiceBusReceiverAsyncClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"ServiceBusReceiverAsyncClient\"></xref> that is tied to the available session."
    type: "<a href=\"https://projectreactor.io/docs/core/release/api/reactor/core/publisher/Mono.html\">Mono</a>&lt;<xref href=\"com.azure.messaging.servicebus.ServiceBusReceiverAsyncClient?alt=com.azure.messaging.servicebus.ServiceBusReceiverAsyncClient&text=ServiceBusReceiverAsyncClient\" data-throw-if-not-resolved=\"False\" />&gt;"
- uid: "com.azure.messaging.servicebus.ServiceBusSessionReceiverAsyncClient.acceptSession(java.lang.String)"
  fullName: "com.azure.messaging.servicebus.ServiceBusSessionReceiverAsyncClient.acceptSession(String sessionId)"
  name: "acceptSession(String sessionId)"
  nameWithType: "ServiceBusSessionReceiverAsyncClient.acceptSession(String sessionId)"
  summary: "Acquires a session lock for `sessionId` and create a <xref uid=\"com.azure.messaging.servicebus.ServiceBusReceiverAsyncClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"ServiceBusReceiverAsyncClient\"></xref> to receive messages from the session."
  parameters:
  - description: "The session id."
    name: "sessionId"
    type: "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/String.html\">String</a>"
  syntax: "public Mono<ServiceBusReceiverAsyncClient> acceptSession(String sessionId)"
  desc: "Acquires a session lock for `sessionId` and create a <xref uid=\"com.azure.messaging.servicebus.ServiceBusReceiverAsyncClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"ServiceBusReceiverAsyncClient\"></xref> to receive messages from the session. If the session is already locked by another client, an <xref uid=\"\" data-throw-if-not-resolved=\"false\" data-raw-source=\"AmqpException\"></xref> is thrown."
  returns:
    description: "A <xref uid=\"com.azure.messaging.servicebus.ServiceBusReceiverAsyncClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"ServiceBusReceiverAsyncClient\"></xref> that is tied to the specified session."
    type: "<a href=\"https://projectreactor.io/docs/core/release/api/reactor/core/publisher/Mono.html\">Mono</a>&lt;<xref href=\"com.azure.messaging.servicebus.ServiceBusReceiverAsyncClient?alt=com.azure.messaging.servicebus.ServiceBusReceiverAsyncClient&text=ServiceBusReceiverAsyncClient\" data-throw-if-not-resolved=\"False\" />&gt;"
- uid: "com.azure.messaging.servicebus.ServiceBusSessionReceiverAsyncClient.close()"
  fullName: "com.azure.messaging.servicebus.ServiceBusSessionReceiverAsyncClient.close()"
  name: "close()"
  nameWithType: "ServiceBusSessionReceiverAsyncClient.close()"
  syntax: "public void close()"
type: "class"
desc: "This **asynchronous** session receiver client is used to acquire session locks from a queue or topic and create <xref uid=\"com.azure.messaging.servicebus.ServiceBusReceiverAsyncClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"ServiceBusReceiverAsyncClient\"></xref> instances that are tied to the locked sessions. Sessions can be used as a first in, first out (FIFO) processing of messages. Queues and topics/subscriptions support Service Bus sessions, however, it must be [ enabled at the time of entity creation][enabled at the time of entity creation].\n\nThe examples shown in this document use a credential object named DefaultAzureCredential for authentication, which is appropriate for most scenarios, including local development and production environments. Additionally, we recommend using [managed identity][] for authentication in production environments. You can find more information on different ways of authenticating and their corresponding credential types in the [Azure Identity documentation\"][Azure Identity documentation].\n\n**Sample: Receive messages from a specific session**\n\nUse <xref uid=\"com.azure.messaging.servicebus.ServiceBusSessionReceiverAsyncClient.acceptSession(java.lang.String)\" data-throw-if-not-resolved=\"false\" data-raw-source=\"#acceptSession(String)\"></xref> to acquire the lock of a session if you know the session id. <xref uid=\"com.azure.messaging.servicebus.models.ServiceBusReceiveMode.PEEK_LOCK\" data-throw-if-not-resolved=\"false\" data-raw-source=\"ServiceBusReceiveMode#PEEK_LOCK\"></xref> and <xref uid=\"com.azure.messaging.servicebus.ServiceBusClientBuilder.ServiceBusProcessorClientBuilder.disableAutoComplete()\" data-throw-if-not-resolved=\"false\" data-raw-source=\"disableAutoComplete()\"></xref> are **strongly** recommended so users have control over message settlement.\n\n```java\nTokenCredential credential = new DefaultAzureCredentialBuilder().build();\n\n // 'fullyQualifiedNamespace' will look similar to \"{your-namespace}.servicebus.windows.net\"\n // 'disableAutoComplete' indicates that users will explicitly settle their message.\n ServiceBusSessionReceiverAsyncClient sessionReceiver = new ServiceBusClientBuilder()\n     .credential(fullyQualifiedNamespace, credential)\n     .sessionReceiver()\n     .disableAutoComplete()\n     .queueName(sessionEnabledQueueName)\n     .buildAsyncClient();\n\n // acceptSession(String) completes successfully with a receiver when \"<<my-session-id>>\" session is\n // successfully locked.\n // `Flux.usingWhen` is used, so we dispose of the receiver resource after `receiveMessages()` and the settlement\n // operations complete.\n // `Mono.usingWhen` can also be used if the resource closure returns a single item.\n Flux<Void> sessionMessages = Flux.usingWhen(\n     sessionReceiver.acceptSession(\"<<my-session-id>>\"),\n     receiver -> {\n         // Receive messages from <<my-session-id>> session.\n         return receiver.receiveMessages().flatMap(message -> {\n             System.out.printf(\"Received Sequence #: %s. Contents: %s%n\", message.getSequenceNumber(),\n                 message.getBody());\n\n             // Explicitly settle the message using complete, abandon, defer, dead-letter, etc.\n             if (isMessageProcessed) {\n                 return receiver.complete(message);\n             } else {\n                 return receiver.abandon(message);\n             }\n         });\n     },\n     receiver -> Mono.fromRunnable(() -> {\n         // Dispose of resources.\n         receiver.close();\n         sessionReceiver.close();\n     }));\n\n // When program ends, or you're done receiving all messages, the `subscription` can be disposed of. This code\n // is non-blocking and kicks off the operation.\n Disposable subscription = sessionMessages.subscribe(\n     unused -> {\n     }, error -> System.err.print(\"Error receiving message from session: \" + error),\n     () -> System.out.println(\"Completed receiving from session.\"));\n```\n\n**Sample: Receive messages from the first available session**\n\nUse <xref uid=\"com.azure.messaging.servicebus.ServiceBusSessionReceiverAsyncClient.acceptNextSession()\" data-throw-if-not-resolved=\"false\" data-raw-source=\"#acceptNextSession()\"></xref> to acquire the lock of the next available session without specifying the session id.\n\n```java\nTokenCredential credential = new DefaultAzureCredentialBuilder().build();\n\n // 'fullyQualifiedNamespace' will look similar to \"{your-namespace}.servicebus.windows.net\"\n // 'disableAutoComplete' indicates that users will explicitly settle their message.\n ServiceBusSessionReceiverAsyncClient sessionReceiver = new ServiceBusClientBuilder()\n     .credential(fullyQualifiedNamespace, credential)\n     .sessionReceiver()\n     .disableAutoComplete()\n     .queueName(sessionEnabledQueueName)\n     .buildAsyncClient();\n\n // Creates a client to receive messages from the first available session. It waits until\n // AmqpRetryOptions.getTryTimeout() elapses. If no session is available within that operation timeout, it\n // completes with a retriable error. Otherwise, a receiver is returned when a lock on the session is acquired.\n Mono<ServiceBusReceiverAsyncClient> receiverMono = sessionReceiver.acceptNextSession();\n\n Flux<Void> receiveMessagesFlux = Flux.usingWhen(receiverMono,\n     receiver -> receiver.receiveMessages().flatMap(message -> {\n         System.out.println(\"Received message: \" + message.getBody());\n\n         // Explicitly settle the message via complete, abandon, defer, dead-letter, etc.\n         if (isMessageProcessed) {\n             return receiver.complete(message);\n         } else {\n             return receiver.abandon(message);\n         }\n     }),\n     receiver -> Mono.fromRunnable(() -> {\n         // Dispose of the receiver and sessionReceiver when done receiving messages.\n         receiver.close();\n         sessionReceiver.close();\n     }));\n\n // This is a non-blocking call that moves onto the next line of code after setting up and starting the receive\n // operation. Customers can keep a reference to `subscription` and dispose of it when they want to stop\n // receiving messages.\n Disposable subscription = receiveMessagesFlux.subscribe(unused -> {\n }, error -> System.out.println(\"Error occurred: \" + error),\n     () -> System.out.println(\"Receiving complete.\"));\n```\n\n\n[enabled at the time of entity creation]: https://learn.microsoft.com/azure/service-bus-messaging/enable-message-sessions\n[managed identity]: https://learn.microsoft.com/azure/active-directory/managed-identities-azure-resources/\n[Azure Identity documentation]: https://learn.microsoft.com/java/api/overview/azure/identity-readme"
implements:
- "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/AutoCloseable.html\">AutoCloseable</a>"
metadata: {}
package: "com.azure.messaging.servicebus"
artifact: com.azure:azure-messaging-servicebus:7.17.1