39 строки
16 KiB
YAML
39 строки
16 KiB
YAML
### YamlMime:JavaPackage
|
|
uid: "com.azure.messaging.servicebus"
|
|
fullName: "com.azure.messaging.servicebus"
|
|
name: "com.azure.messaging.servicebus"
|
|
summary: "The Azure Service Bus client library allows Java developers to interact with Azure Service Bus entities by publishing to and/or subscribing from queues and topics/subscriptions."
|
|
classes:
|
|
- "com.azure.messaging.servicebus.ServiceBusClientBuilder"
|
|
- "com.azure.messaging.servicebus.ServiceBusClientBuilder.ServiceBusProcessorClientBuilder"
|
|
- "com.azure.messaging.servicebus.ServiceBusClientBuilder.ServiceBusReceiverClientBuilder"
|
|
- "com.azure.messaging.servicebus.ServiceBusClientBuilder.ServiceBusRuleManagerBuilder"
|
|
- "com.azure.messaging.servicebus.ServiceBusClientBuilder.ServiceBusSenderClientBuilder"
|
|
- "com.azure.messaging.servicebus.ServiceBusClientBuilder.ServiceBusSessionProcessorClientBuilder"
|
|
- "com.azure.messaging.servicebus.ServiceBusClientBuilder.ServiceBusSessionReceiverClientBuilder"
|
|
- "com.azure.messaging.servicebus.ServiceBusConnectionStringProperties"
|
|
- "com.azure.messaging.servicebus.ServiceBusErrorContext"
|
|
- "com.azure.messaging.servicebus.ServiceBusErrorSource"
|
|
- "com.azure.messaging.servicebus.ServiceBusException"
|
|
- "com.azure.messaging.servicebus.ServiceBusFailureReason"
|
|
- "com.azure.messaging.servicebus.ServiceBusMessage"
|
|
- "com.azure.messaging.servicebus.ServiceBusMessageBatch"
|
|
- "com.azure.messaging.servicebus.ServiceBusProcessorClient"
|
|
- "com.azure.messaging.servicebus.ServiceBusReceivedMessage"
|
|
- "com.azure.messaging.servicebus.ServiceBusReceivedMessageContext"
|
|
- "com.azure.messaging.servicebus.ServiceBusReceiverAsyncClient"
|
|
- "com.azure.messaging.servicebus.ServiceBusReceiverClient"
|
|
- "com.azure.messaging.servicebus.ServiceBusRuleManagerAsyncClient"
|
|
- "com.azure.messaging.servicebus.ServiceBusRuleManagerClient"
|
|
- "com.azure.messaging.servicebus.ServiceBusSenderAsyncClient"
|
|
- "com.azure.messaging.servicebus.ServiceBusSenderClient"
|
|
- "com.azure.messaging.servicebus.ServiceBusSessionReceiverAsyncClient"
|
|
- "com.azure.messaging.servicebus.ServiceBusSessionReceiverClient"
|
|
- "com.azure.messaging.servicebus.ServiceBusTransactionContext"
|
|
enums:
|
|
- "com.azure.messaging.servicebus.ServiceBusServiceVersion"
|
|
desc: "The Azure Service Bus client library allows Java developers to interact with Azure Service Bus entities by publishing to and/or subscribing from queues and topics/subscriptions. [Microsoft Azure Service Bus][] is a fully managed enterprise integration message broker. Service Bus can decouple applications and services. Service Bus offers a reliable and secure platform for asynchronous transfer of data and state. Data is transferred between different applications and services using messages.\n\n## Key Concepts ##\n\n * **[Queue][] :** Allows for the sending and receiving of messages, ordered first-in-first-out(FIFO). It is often used for point to point communication.\n * **[Topic][] :** Allows for sending messages to multiple receivers, simultaneously. This is suited for publisher and subscriber scenarios.\n * **[ Subscription][Subscription]:** Receives messages from a topic. Each subscription is independent and receives a copy of every message sent to the topic. Each subscription has a filter. Filters, also known as rules, are applied to each message to determine whether they will be published to the subscription.\n\n## Getting Started ##\n\nService clients are the point of interaction for developers to use Azure Event Hubs. <xref uid=\"com.azure.messaging.servicebus.ServiceBusSenderClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.ServiceBusSenderClient\"></xref> and <xref uid=\"com.azure.messaging.servicebus.ServiceBusSenderAsyncClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.ServiceBusSenderAsyncClient\"></xref> are the sync and async clients for publishing messages to a Service Bus queue or topic. Similarly, <xref uid=\"com.azure.messaging.servicebus.ServiceBusReceiverClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.ServiceBusReceiverClient\"></xref> and <xref uid=\"com.azure.messaging.servicebus.ServiceBusReceiverAsyncClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.ServiceBusReceiverAsyncClient\"></xref> are the sync and async clients for consuming messages from a Service Bus queue or topic. In production scenarios, we recommend customers leverage <xref uid=\"com.azure.messaging.servicebus.ServiceBusProcessorClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.ServiceBusProcessorClient\"></xref> for consuming messages because recovers from transient failures.\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][].\n\n### Publishing Service Bus messages ###\n\nThis library provides two sender clients to publish messages to Azure Service Bus. The async client, <xref uid=\"com.azure.messaging.servicebus.ServiceBusSenderAsyncClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.ServiceBusSenderAsyncClient\"></xref> and its sync version, <xref uid=\"com.azure.messaging.servicebus.ServiceBusSenderClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.ServiceBusSenderClient\"></xref>. The samples below demonstrate basic scenarios, additional snippets can be found in the class documentation for <xref uid=\"com.azure.messaging.servicebus.ServiceBusClientBuilder\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.ServiceBusClientBuilder\"></xref> and any of the clients.\n\n**Sample: Construct a synchronous sender and send messages**\n\nThe following code sample demonstrates the creation and use of the synchronous client <xref uid=\"com.azure.messaging.servicebus.ServiceBusSenderClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.ServiceBusSenderClient\"></xref> to send messages to a queue. When performance is important, consider using <xref uid=\"com.azure.messaging.servicebus.ServiceBusMessageBatch\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.ServiceBusMessageBatch\"></xref> to publish multiple messages at once.\n\n```java\nTokenCredential credential = new DefaultAzureCredentialBuilder().build();\n\n // 'fullyQualifiedNamespace' will look similar to \"{your-namespace}.servicebus.windows.net\"\n ServiceBusSenderClient sender = new ServiceBusClientBuilder()\n .credential(fullyQualifiedNamespace, credential)\n .sender()\n .queueName(queueName)\n .buildClient();\n\n List<ServiceBusMessage> messages = Arrays.asList(\n new ServiceBusMessage(\"test-1\"),\n new ServiceBusMessage(\"test-2\"));\n\n // Creating a batch without options set.\n ServiceBusMessageBatch batch = sender.createMessageBatch();\n for (ServiceBusMessage message : messages) {\n if (batch.tryAddMessage(message)) {\n continue;\n }\n\n // The batch is full. Send the current batch and create a new one.\n sender.sendMessages(batch);\n\n batch = sender.createMessageBatch();\n\n // Add the message we couldn't before.\n if (!batch.tryAddMessage(message)) {\n throw new IllegalArgumentException(\"Message is too large for an empty batch.\");\n }\n }\n\n // Send the final batch if there are any messages in it.\n if (batch.getCount() > 0) {\n sender.sendMessages(batch);\n }\n\n // Continue using the sender and finally, dispose of the sender.\n // Clients should be long-lived objects as they require resources\n // and time to establish a connection to the service.\n sender.close();\n```\n\n### Receiving Service Bus messages ###\n\nThis library provides several clients to receive messages from Azure Service Bus. The async client, <xref uid=\"com.azure.messaging.servicebus.ServiceBusReceiverAsyncClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.ServiceBusReceiverAsyncClient\"></xref> and its sync version, <xref uid=\"com.azure.messaging.servicebus.ServiceBusReceiverClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.ServiceBusReceiverClient\"></xref>. For session-enabled entities, there is <xref uid=\"com.azure.messaging.servicebus.ServiceBusSessionReceiverAsyncClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.ServiceBusSessionReceiverAsyncClient\"></xref> and <xref uid=\"com.azure.messaging.servicebus.ServiceBusSessionReceiverClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.ServiceBusSessionReceiverClient\"></xref>. In production scenarios, <xref uid=\"com.azure.messaging.servicebus.ServiceBusProcessorClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.ServiceBusProcessorClient\"></xref> is recommended because it recovers from transient errors such as temporary network failures.\n\nThe samples below demonstrate basic scenarios, additional snippets can be found in the class documentation.\n\n**Sample: Create a ServiceBusProcessorClient and receive messages**\n\nThe following code sample demonstrates the creation and use of the synchronous client <xref uid=\"com.azure.messaging.servicebus.ServiceBusProcessorClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.ServiceBusProcessorClient\"></xref> to receive messages from a Service Bus queue. By default, messages are received using <xref uid=\"com.azure.messaging.servicebus.models.ServiceBusReceiveMode.PEEK_LOCK\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.models.ServiceBusReceiveMode#PEEK_LOCK\"></xref> and customers must settle their messages using one of the settlement methods on the receiver client. \"[ \"Settling receive operations][_Settling receive operations]\" provides additional information about message settlement. <xref uid=\"com.azure.messaging.servicebus.ServiceBusProcessorClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.ServiceBusProcessorClient\"></xref> continues fetching messages from the queue until the processor is stopped. If it encounters a transient error, it will try to recover, then continue processing messages.\n\n```java\n// Function that gets called whenever a message is received.\n Consumer<ServiceBusReceivedMessageContext> processMessage = context -> {\n final ServiceBusReceivedMessage message = context.getMessage();\n // Randomly complete or abandon each message. Ideally, in real-world scenarios, if the business logic\n // handling message reaches desired state such that it doesn't require Service Bus to redeliver\n // the same message, then context.complete() should be called otherwise context.abandon().\n final boolean success = Math.random() < 0.5;\n if (success) {\n try {\n context.complete();\n } catch (RuntimeException error) {\n System.out.printf(\"Completion of the message %s failed.%n Error: %s%n\",\n message.getMessageId(), error);\n }\n } else {\n try {\n context.abandon();\n } catch (RuntimeException error) {\n System.out.printf(\"Abandoning of the message %s failed.%nError: %s%n\",\n message.getMessageId(), error);\n }\n }\n };\n\n // Sample code that gets called if there's an error\n Consumer<ServiceBusErrorContext> processError = errorContext -> {\n if (errorContext.getException() instanceof ServiceBusException) {\n ServiceBusException exception = (ServiceBusException) errorContext.getException();\n\n System.out.printf(\"Error source: %s, reason %s%n\", errorContext.getErrorSource(),\n exception.getReason());\n } else {\n System.out.printf(\"Error occurred: %s%n\", errorContext.getException());\n }\n };\n\n TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();\n\n // Create the processor client via the builder and its sub-builder\n // 'fullyQualifiedNamespace' will look similar to \"{your-namespace}.servicebus.windows.net\"\n ServiceBusProcessorClient processorClient = new ServiceBusClientBuilder()\n .credential(fullyQualifiedNamespace, tokenCredential)\n .processor()\n .queueName(queueName)\n .receiveMode(ServiceBusReceiveMode.PEEK_LOCK)\n .disableAutoComplete() // Make sure to explicitly opt in to manual settlement (e.g. complete, abandon).\n .processMessage(processMessage)\n .processError(processError)\n .disableAutoComplete()\n .buildProcessorClient();\n\n // Starts the processor in the background. Control returns immediately.\n processorClient.start();\n\n // Stop processor and dispose when done processing messages.\n processorClient.stop();\n processorClient.close();\n```\n\n**Sample: Create a receiver and receive messages**\n\nThe following code sample demonstrates the creation and use of the synchronous client <xref uid=\"com.azure.messaging.servicebus.ServiceBusReceiverClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.ServiceBusReceiverClient\"></xref> to receive messages from a Service Bus subscription. The receive operation returns when either 10 messages are received or 30 seconds has elapsed. By default, messages are received using <xref uid=\"com.azure.messaging.servicebus.models.ServiceBusReceiveMode.PEEK_LOCK\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.servicebus.models.ServiceBusReceiveMode#PEEK_LOCK\"></xref> and customers must settle their messages using one of the settlement methods on the receiver client. \"[ \"Settling receive operations][_Settling receive operations]\" provides additional information about message settlement.\n\n```java\nTokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();\n\n // 'fullyQualifiedNamespace' will look similar to \"{your-namespace}.servicebus.windows.net\"\n ServiceBusReceiverClient receiver = new ServiceBusClientBuilder()\n .credential(fullyQualifiedNamespace, tokenCredential)\n .receiver()\n .topicName(topicName)\n .subscriptionName(subscriptionName)\n .buildClient();\n\n // Receives a batch of messages when 10 messages are received or until 30 seconds have elapsed, whichever\n // happens first.\n IterableStream<ServiceBusReceivedMessage> messages = receiver.receiveMessages(10, Duration.ofSeconds(30));\n messages.forEach(message -> {\n System.out.printf(\"Id: %s. Contents: %s%n\", message.getMessageId(), message.getBody());\n\n // If able to process message, complete it. Otherwise, abandon it and allow it to be\n // redelivered.\n if (isMessageProcessed) {\n receiver.complete(message);\n } else {\n receiver.abandon(message);\n }\n });\n\n // When program ends, or you're done receiving all messages, dispose of the receiver.\n // Clients should be long-lived objects as they\n // require resources and time to establish a connection to the service.\n receiver.close();\n```\n\n\n[Microsoft Azure Service Bus]: https://docs.microsoft.com/azure/service-bus-messaging\n[Queue]: https://docs.microsoft.com/azure/service-bus-messaging/service-bus-messaging-overview#queues\n[Topic]: https://docs.microsoft.com/azure/service-bus-messaging/service-bus-messaging-overview#topics\n[Subscription]: https://docs.microsoft.com/azure/service-bus-messaging/service-bus-queues-topics-subscriptions#topics-and-subscriptions\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\n[_Settling receive operations]: https://learn.microsoft.com/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock"
|
|
metadata: {}
|
|
package: "com.azure.messaging.servicebus"
|
|
artifact: com.azure:azure-messaging-servicebus:7.17.5
|