Azure Service Bus JMS 2.0-Entwicklerhandbuch

Dieses Handbuch enthält detaillierte Informationen, die Ihnen helfen, mithilfe der Java Message Service (JMS) 2.0-API erfolgreich mit Azure Service Bus zu kommunizieren.

Als Java-Entwickler sollten Sie, wenn Sie mit Azure Service Bus noch nicht vertraut sind, die folgenden Artikel lesen.

programmiermodell des Java Message Service (JMS)

Das Java Api-Programmiermodell für den Nachrichtendienst wird in den folgenden Abschnitten beschrieben:

JMS - Bausteine

Verwenden Sie die folgenden Bausteine, um mit der JMS-Anwendung zu kommunizieren.

Verbindungsfactory

Der Client verwendet das Verbindungsfactoryobjekt, um eine Verbindung mit dem JMS-Anbieter herzustellen. Die Verbindungsfabrik setzt eine Reihe von Verbindungskonfigurationsparametern, die der Administrator definiert, zusammen.

Jede Verbindungsfactory ist eine Instanz der ConnectionFactory, QueueConnectionFactory oder TopicConnectionFactory Schnittstelle.

Um die Verbindung mit Azure Service Bus zu vereinfachen, werden diese Schnittstellen über ServiceBusJmsConnectionFactory, ServiceBusJmsQueueConnectionFactory oder ServiceBusJmsTopicConnectionFactory implementiert.

TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

String host = "<YourNamespaceName>.servicebus.windows.net";
ConnectionFactory factory = new ServiceBusJmsConnectionFactory(tokenCredential, host, null); 

TokenCredential tokenCredential = new DefaultAzureCredentialBuilder()
                                                .managedIdentityClientId("<clientIDOfUserAssignedIdentity>")
                                                .build();

String host = "<YourNamespaceName>.servicebus.windows.net";
ConnectionFactory factory = new ServiceBusJmsConnectionFactory(tokenCredential, host, null); 

TokenCredential tokenCredential = new ClientSecretCredentialBuilder()
                .tenantId("")
                .clientId("")
                .clientSecret("")
                .build();

ConnectionFactory factory = new ServiceBusJmsConnectionFactory(SERVICE_BUS_CONNECTION_STRING, null);

JMS-Ziel

Ein Ziel ist das Objekt, das ein Client verwendet, um das Ziel der von ihr erzeugten Nachrichten und die Quelle der von ihr verbrauchten Nachrichten anzugeben.

Ziele sind Entitäten in Azure Service Bus zugeordnet: Warteschlangen (in Punkt-zu-Punkt-Szenarien) und Themen (in Szenarien mit dem Muster „Veröffentlichen-Abonnieren“).

Verbindungen

Eine Verbindung umfasst eine virtuelle Verbindung zu einem JMS-Anbieter. Mit Azure Service Bus stellt es eine zustandsbehaftete Verbindung zwischen der Anwendung und dem Azure Service Bus über AMQP dar.

Erstellen Sie eine Verbindung aus der Verbindungsfabrik, wie im folgenden Beispiel gezeigt:

Connection connection = factory.createConnection();

Sitzungen

Eine Sitzung ist ein Einzelthreadkontext zum Erstellen und Nutzen von Nachrichten. Zum Erstellen von Nachrichten, Nachrichtenproduzenten und Verbrauchern verwenden. Darüber hinaus bietet sie einen transaktionsbezogenen Kontext zum Gruppieren von Sende- und Empfängen in eine atomische Arbeitseinheit.

Erstellen Sie eine Sitzung aus dem Verbindungsobjekt, wie im folgenden Beispiel gezeigt:

Session session = connection.createSession(false, Session.CLIENT_ACKNOWLEDGE);

Sitzungsmodi

Erstellen Sie eine Sitzung mit einem der folgenden Modi.

Wenn Sie den Sitzungsmodus nicht angeben, ist die Standardeinstellung Session.AUTO_ACKNOWLEDGE.

JMSContext

JMSContext kombiniert die vom Verbindungs- und Sitzungsobjekt bereitgestellte Funktionalität. Sie erstellen das Objekt aus dem Verbindungsfabrik-Objekt.

JMSContext context = connectionFactory.createContext();

JMSContext-Modi

Genau wie das Session-Objekt können Sie den JMSContext mit den gleichen Bestätigungsmodi erstellen wie im Sitzungsmodus erwähnt.

JMSContext context = connectionFactory.createContext(JMSContext.AUTO_ACKNOWLEDGE);

Wenn Sie keinen Modus angeben, wird der Standardwert JMSContext.AUTO_ACKNOWLEDGE.

JMS-Nachrichtenproduzenten

Ein Nachrichtenproduzent ist ein Objekt, das Sie mit einem JMSContext oder einer Session erstellen. Verwenden Sie sie, um Nachrichten an ein Ziel zu senden.

Sie können es wie im folgenden Beispiel gezeigt als eigenständiges Objekt erstellen:

JMSProducer producer = context.createProducer();

Sie können sie auch zur Laufzeit erstellen, wenn Sie eine Nachricht senden müssen.

context.createProducer().send(destination, message);

JMS-Nachrichtenconsumer

Ein Nachrichtenanwender ist ein Objekt, das von einem JMSContext oder einer Session erstellt wird. Verwenden Sie sie zum Empfangen von Nachrichten, die an ein Ziel gesendet werden. Erstellen Sie sie wie im folgenden Beispiel gezeigt:

JMSConsumer consumer = context.createConsumer(dest);

Synchrone Empfangsvorgänge über receive()-Methode

Der Nachrichtenanwender bietet eine synchrone Möglichkeit, Nachrichten vom Ziel über die receive() Methode zu empfangen.

Wenn keine Argumente oder Timeouts angegeben werden oder ein Timeout von 0 angegeben wird, blockiert der Verbraucher auf unbestimmte Zeit. Es sei denn, die Nachricht trifft ein oder die Verbindung wird unterbrochen (je nachdem, was zuerst eintritt).

Message m = consumer.receive();
Message m = consumer.receive(0);

Wenn ein positives Argument ungleich 0 bereitgestellt wird, blockiert der Verbraucher so lange, bis dieser Timer abgelaufen ist.

Message m = consumer.receive(1000); // time out after one second.

Asynchroner Empfang mit JMS-Nachrichtenlistenern

Ein Nachrichtenlistener ist ein Objekt, das Sie für die asynchrone Behandlung von Nachrichten auf einem Ziel verwenden. Es implementiert die MessageListener Schnittstelle, die die Methode onMessage enthält, in der die spezifische Geschäftslogik ausgeführt werden muss.

Sie müssen ein Nachrichtenlistenerobjekt instanziieren und mithilfe der setMessageListener Methode für einen bestimmten Nachrichtenanwender registrieren.

Listener myListener = new Listener();
consumer.setMessageListener(myListener);

Nutzen von Themen

Sie erstellen JMS-Nachrichtenkonsumenten für ein Ziel, das eine Warteschlange oder ein Thema sein kann.

Verbraucher in Warteschlangen sind einfach clientseitige Objekte, die sich im Kontext der Sitzung (und Verbindung) zwischen der Clientanwendung und Azure Service Bus befinden.

Verbraucher für Themen bestehen jedoch aus zwei Teilen:

• Ein clientseitiges Objekt , das sich im Kontext der Sitzung (oder JMSContext) befindet, und
• Ein Abonnement , das eine Entität in Azure Service Bus ist.

Die Abonnements sind hier dokumentiert und können eine der folgenden Typen sein:

• Gemeinsam genutzte persistente Abonnements
• Gemeinsame Kurzlebige Abonnements
• Ungeteilte dauerhafte Abonnements
• Nicht geteilte temporäre Abonnements

JMS-Warteschlangenbrowser

Die JMS-API stellt ein QueueBrowser Objekt bereit, mit dem die Anwendung die Nachrichten in der Warteschlange durchsuchen und die Kopfzeilenwerte für jede Nachricht anzeigen kann.

Sie können einen Warteschlangenbrowser mithilfe von JMSContext erstellen, wie im folgenden Beispiel gezeigt:

QueueBrowser browser = context.createBrowser(queue);

JMS-Nachrichtenselektoren

Empfangende Anwendungen können Nachrichtenselektoren verwenden, um die empfangenen Nachrichten zu filtern. Durch die Verwendung von Nachrichtenselektoren entlädt die empfangende Anwendung die Arbeit des Filterns von Nachrichten an den JMS-Anbieter (in diesem Fall Azure Service Bus), anstatt diese Verantwortung selbst zu übernehmen.

Sie können Selektoren verwenden, wenn Sie einen der folgenden Consumer erstellen:

• Geteiltes dauerhaftes Abonnement
• Ungeteiltes dauerhaftes Abonnement
• Geteiltes temporäres Abonnement
• Nicht geteiltes, nicht dauerhaftes Abonnement
• Consumer in der Warteschlange
• Warteschlangenbrowser

Geplante Nachrichten (Zustellungsverzögerung)

JMS 2.0 unterstützt die Planung von Nachrichten für die zukünftige Zustellung mithilfe der setDeliveryDelay-Methode auf einem MessageProducer oder JMSProducer. Wenn Sie diese Eigenschaft festlegen, akzeptiert Service Bus die Nachricht, macht sie aber erst nach Ablauf des Verzögerungszeitraums für Verbraucher sichtbar.

MessageProducer producer = session.createProducer(queue);

// Schedule a message for delivery 30 seconds from now
producer.setDeliveryDelay(30000);
producer.send(session.createTextMessage("Scheduled message"));

Ein vollständiges Arbeitsbeispiel finden Sie unter QueueScheduledSend.java im Repository azure-servicebus-jms-samples.

Auswahl der Werksverbindungseinstellung und Resilienz

Wenn Sie im Spring Boot oder anderen Frameworks zum Verwalten von JMS-Verbindungen verwenden ServiceBusJmsConnectionFactory , wählen Sie den richtigen Verbindungsfactorywrapper für Absender und Listener aus, um einen zuverlässigen Betrieb sicherzustellen.

Empfohlene Konfiguration

Was für Listener zu vermeiden ist

CachingConnectionFactory bei Listenercontainern kann auch Probleme verursachen, da zwischengespeicherte Sitzungen möglicherweise auf eine veraltete zugrunde liegende Verbindung verweisen. Für Hörer stellt die Rohfabrik sicher, dass jeder Container unabhängig eine neue Verbindung aufbauen kann.

Standardeinstellungen für Spring Cloud Azure

Wenn Sie spring-cloud-azure-starter-servicebus-jms (Version 6.2.0 oder höher) verwenden, wendet der Starter diese Factory-Trennung standardmäßig an.

In älteren Versionen (pre-6.2.0) verwenden ServiceBusJmsConnectionFactory sowohl Absender als auch Listener standardmäßig, wodurch Absender eine neue Verbindung pro Senden erstellen.

Hinzufügen eines Ausnahmelisteners

Ohne Ausnahmelistener erfolgen Verbindungsabbrüche vollständig lautlos. Sowohl der Absender- als auch der Hörer-Fabrik ein jakarta.jms.ExceptionListener hinzufügen, um die Beobachtbarkeit zu verbessern.

connection.setExceptionListener(exception -> {
    log.error("JMS connection error: {}", exception.getMessage(), exception);
});

Legen Sie im Spring Boot den Ausnahmelistener für die CachingConnectionFactory (für Absender) und die DefaultJmsListenerContainerFactory (für Listener) fest.

Ein vollständiges Arbeitsbeispiel mit all diesen Mustern finden Sie im Beispiel Spring Boot JMS Resilience im Repository azure-servicebus-jms-samples.

Warteschlangen für unzustellbare Nachrichten

Jedes Warteschlangen- und Themenabonnement in Azure Service Bus verfügt über eine zugeordnete Warteschlange nicht zustellbarer Nachrichten (DLQ). Das System verschiebt automatisch Nachrichten, die er nicht an den DLQ übermitteln oder verarbeiten kann. Beispielsweise verschiebt das System eine Nachricht in den DLQ, wenn die Nachricht die maximale Anzahl der Übermittlungen überschreitet oder die Ablaufzeit (TTL) abläuft.

In JMS können Sie auf den DLQ als separates Ziel zugreifen, indem Sie den vollständigen Pfad konstruieren und dann ein JmsQueue damit erzeugen. Es ist keine spezielle API erforderlich.

DLQ-Pfadformat der Warteschlange:

<queue-name>/$deadletterqueue

Das Format des DLQ-Pfads für Themenabonnements:

<topic-name>/Subscriptions/<subscription-name>/$deadletterqueue

Beispiel – Verbrauch von einer Warteschlange für unzustellbare Nachrichten:

import org.apache.qpid.jms.JmsQueue;

// Construct the DLQ path for a queue named "orders"
String dlqPath = "orders/$deadletterqueue";
JmsQueue dlqDestination = new JmsQueue(dlqPath);

// Create a consumer on the DLQ and receive messages
MessageConsumer dlqConsumer = session.createConsumer(dlqDestination);
Message message = dlqConsumer.receive(5000);

Nachrichten, die totbriefmarkiert sind, enthalten Metadateneigenschaften, die beschreiben, warum die Nachricht totbriefmarkiert wurde.

Lesen Sie diese Eigenschaften mithilfe von message.getStringProperty():

String reason = message.getStringProperty("DeadLetterReason");
String description = message.getStringProperty("DeadLetterErrorDescription");

Ein vollständiges Arbeitsbeispiel finden Sie unter QueueDeadLetterReceive.java im Repository azure-servicebus-jms-samples.

AMQP-Disposition und Service Bus-Vorgangszuordnung

Hier erfahren Sie, wie eine AMQP-Disposition in einen ServiceBus-Vorgang übersetzt wird:

ACCEPTED = 1; -> Complete()
REJECTED = 2; -> DeadLetter()
RELEASED = 3; (just unlock the message in service bus, will then get redelivered)
MODIFIED_FAILED = 4; -> Abandon() which increases delivery count
MODIFIED_FAILED_UNDELIVERABLE = 5; -> Defer()

Zusammenfassung

Dieses Entwicklerhandbuch zeigt, wie Java Clientanwendungen, die Java Message Service (JMS) verwenden, eine Verbindung mit Azure Service Bus herstellen können.

Nächste Schritte

Weitere Informationen zu Azure Service Bus und Details zu Java Message Service (JMS)-Entitäten finden Sie in den folgenden Artikeln:

• Choose zwischen JMS und dem nativen SDK für Azure Service Bus
• Servicebus – Warteschlangen, Themen und Abonnements
• Service Bus – Java Message Service-Entitäten
• AMQP 1.0-Unterstützung in Azure Service Bus
• Service Bus AMQP 1.0-Entwicklerhandbuch
• Erste Schritte mit Service Bus-Warteschlangen
• Java Message Service-API(externes Oracle-Dokument)
• Erfahren Sie, wie Sie von ActiveMQ zu Service Bus migrieren