Utvecklarguide för Azure Service Bus JMS 2.0

Den här guiden innehåller detaljerad information som hjälper dig att kommunicera med Azure Service Bus med hjälp av api:et Java Message Service (JMS) 2.0.

Som Java-utvecklare kan du läsa följande artiklar om du är nybörjare på Azure Service Bus.

programmeringsmodell för Java Message Service (JMS)

Programmeringsmodellen Java Message Service API beskrivs i följande avsnitt:

JMS – byggstenar

Använd följande byggstenar för att kommunicera med JMS-programmet.

Anslutningsfabrik

Klienten använder anslutningsfabriksobjektet för att ansluta till JMS-providern. Anslutningsfabriken kapslar in en uppsättning anslutningskonfigurationsparametrar som administratören definierar.

Varje anslutningsfabrik är en instans av ConnectionFactorygränssnittet , QueueConnectionFactoryeller TopicConnectionFactory .

För att förenkla anslutningen till Azure Service Bus implementeras dessa gränssnitt via ServiceBusJmsConnectionFactory, ServiceBusJmsQueueConnectionFactory eller ServiceBusJmsTopicConnectionFactory respektive.

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-destination

Ett mål är det objekt som en klient använder för att ange målet för de meddelanden som skapas och källan till de meddelanden som den använder.

Mål mappas till entiteter i Azure Service Bus – köer (i punkt-till-punkt-scenarier) och ämnen (i pub-sub-scenarier).

Anslutningar

En anslutning kapslar in en virtuell anslutning med en JMS-provider. Med Azure Service Bus representerar den en tillståndskänslig anslutning mellan programmet och Azure Service Bus via AMQP.

Skapa en anslutning från anslutningsfabriken enligt följande exempel:

Connection connection = factory.createConnection();

Sessioner

En session är en enkeltrådad kontext för att producera och använda meddelanden. Använd den för att skapa meddelanden, meddelandeproducenter och konsumenter. Den tillhandahåller också en transaktionskontext som grupperar sändningar och mottagningar till en enhetlig arbetsoperation.

Skapa en session från anslutningsobjektet enligt följande exempel:

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

Sessionslägen

Skapa en session med något av följande lägen.

Om du inte anger sessionsläget är standardvärdet Session.AUTO_ACKNOWLEDGE.

JMSContext

JMSContext kombinerar de funktioner som tillhandahålls av anslutnings- och sessionsobjektet. Du skapar den från anslutningsfabrikens objekt.

JMSContext context = connectionFactory.createContext();

JMSContext-lägen

Precis som sessionsobjektet kan du skapa JMSContext med samma bekräftelselägen som anges i Sessionslägen.

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

Om du inte anger något läge är standardvärdet JMSContext.AUTO_ACKNOWLEDGE.

JMS-meddelandeproducenter

En meddelandeproducent är ett objekt som du skapar med hjälp av en JMSContext eller en session. Använd den för att skicka meddelanden till ett mål.

Du kan skapa det som ett fristående objekt, som du ser i följande exempel:

JMSProducer producer = context.createProducer();

Du kan också skapa den vid körning när du behöver skicka ett meddelande.

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

JMS-meddelandekonsumenter

En meddelandekonsument är ett objekt som en JMSContext eller en session skapar. Använd den för att ta emot meddelanden som skickas till ett mål. Skapa den som du ser i följande exempel:

JMSConsumer consumer = context.createConsumer(dest);

Synkron mottagning via metoden receive()

Meddelandekonsumenten tillhandahåller ett synkront sätt att ta emot meddelanden från målet via receive() metoden.

Om du inte anger argument eller tidsgräns, eller om du anger en tidsgräns för 0, blockerar konsumenten på obestämd tid såvida inte meddelandet kommer eller anslutningen bryts (beroende på vilket som inträffar tidigare).

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

När du anger ett positivt argument som inte är noll blockerar konsumenten tills timern upphör att gälla.

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

Asynkrona mottagningar med JMS-meddelandelyssnare

En meddelandelyssnare är ett objekt som du använder för asynkron hantering av meddelanden på ett mål. Det implementerar MessageListener gränssnittet, som innehåller den onMessage metod där den specifika affärslogik måste finnas.

Du måste instansiera ett meddelandelyssnarobjekt och registrera det mot en specifik meddelandekonsument med hjälp av setMessageListener-metoden.

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

Använda från ämnen

Du skapar JMS-meddelandekonsumenter mot ett mål, som kan vara en kö eller ett ämne.

Konsumenter i köer är helt enkelt objekt på klientsidan som finns i kontexten för sessionen (och anslutningen) mellan klientprogrammet och Azure Service Bus.

Konsumenter i ämnen har dock två delar -

• Ett objekt på klientsidan som finns i kontexten för sessionen (eller JMSContext) och
• En prenumeration som är en entitet på Azure Service Bus.

Prenumerationerna dokumenteras här och kan vara en av följande typer:

• Delade beständiga prenumerationer
• Delade icke-varaktiga prenumerationer
• Odelade hållbara prenumerationer
• Ej delade icke-varaktiga prenumerationer

JMS-köwebbläsare

JMS-API:et innehåller ett QueueBrowser objekt som programmet kan använda för att bläddra bland meddelandena i kön och visa huvudvärdena för varje meddelande.

Du kan skapa en köwebbläsare med hjälp av JMSContext, som du ser i följande exempel:

QueueBrowser browser = context.createBrowser(queue);

JMS-meddelandeväljare

Mottagande program kan använda meddelandeväljare för att filtrera de meddelanden som de tar emot. Genom att använda meddelandeväljare avlastar det mottagande programmet arbetet med att filtrera meddelanden till JMS-providern (i det här fallet Azure Service Bus) i stället för att ta det ansvaret självt.

Du kan använda valmekanismer när du skapar någon av följande konsumenter:

• Delad varaktig prenumeration
• Ej delad beständig prenumeration
• Delad icke-varaktig prenumeration
• Ej delad icke-varaktig prenumeration
• Kökonsument
• Köwebbläsare

Schemalagda meddelanden (leveransfördröjning)

JMS 2.0 stöder schemaläggning av ett meddelande för framtida leverans med hjälp av setDeliveryDelay metoden på en MessageProducer eller JMSProducer. När du anger den här egenskapen accepterar Service Bus meddelandet men gör det bara synligt för konsumenter efter att fördröjningsperioden har gått ut.

MessageProducer producer = session.createProducer(queue);

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

Ett fullständigt arbetsexempel finns i QueueScheduledSend.java på lagringsplatsen azure-servicebus-jms-samples.

Val och motståndskraft för anslutningsfabrik

När du använder ServiceBusJmsConnectionFactory i Spring Boot eller andra ramverk som hanterar JMS-anslutningar väljer du rätt anslutningsfabriksomslutning för avsändare och lyssnare för att säkerställa tillförlitlig drift.

Rekommenderad konfiguration

Vad du ska undvika för lyssnare

CachingConnectionFactory på lyssnarcontainrar kan också orsaka problem eftersom cachelagrade sessioner kan referera till en inaktuell underliggande anslutning. För lyssnare säkerställer råfabriken att varje container kan skapa en ny anslutning oberoende av varandra.

Standardvärden för Spring Cloud Azure

Om du använder spring-cloud-azure-starter-servicebus-jms (version 6.2.0+) tillämpar startprogrammet den här fabriksavgränsningen som standard:

I äldre versioner (före 6.2.0) använder ServiceBusJmsConnectionFactory både avsändare och lyssnare som standard, vilket gör att avsändare skapar en ny anslutning per sändning.

Lägga till en undantagslyssnare

Utan undantagshanterare är anslutningsavbrott fullständigt tysta. Lägg till en jakarta.jms.ExceptionListener till både avsändare och lyssnarfabriker för observerbarhet:

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

I Spring Boot, sätt undantagslyssnaren på CachingConnectionFactory för sändare och DefaultJmsListenerContainerFactory för lyssnare.

Ett fullständigt arbetsexempel som visar alla dessa mönster finns i Spring Boot JMS Resilience sample i lagringsplatsen azure-servicebus-jms-samples.

Döda bokstavs-köer

Varje kö- och ämnesprenumeration i Azure Service Bus har en associerad dead letter queue (DLQ). Systemet flyttar automatiskt meddelanden som det inte kan leverera eller bearbeta till DLQ. Systemet flyttar till exempel ett meddelande till DLQ när meddelandet överskrider det maximala leveransantalet eller dess TTL (time-to-live) upphör att gälla.

Inom JMS får du tillgång till DLQ som ett separat mål genom att konstruera den fullständiga sökvägen och skapa en JmsQueue med denna. Inget särskilt API krävs.

DLQ-sökvägsformat för kö:

<queue-name>/$deadletterqueue

Ämnesprenumerationens DLQ-sökvägsformat:

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

Exempel – användning från en kös kö med obeställbara meddelanden:

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);

Meddelanden med obeställbara meddelanden innehåller metadataegenskaper som beskriver varför meddelandet var obeställt:

Läs dessa egenskaper med hjälp av message.getStringProperty().

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

Ett fullständigt arbetsexempel finns i QueueDeadLetterReceive.java på lagringsplatsen azure-servicebus-jms-samples.

AMQP-tilldelning och Service Bus-operationers mappning

Så här konverteras en AMQP-disposition till en Service Bus-åtgärd.

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()

Sammanfattning

Den här utvecklarguiden visar hur Java klientprogram som använder Java Message Service (JMS) kan ansluta till Azure Service Bus.

Nästa steg

Mer information om Azure Service Bus och information om JMS-entiteter (Java Message Service) finns i följande artiklar:

• Choose mellan JMS och den interna SDK:t för Azure Service Bus
• Service Bus – köer, ämnen och prenumerationer
• Service Bus – Java Message Service-entiteter
• AMQP 1.0-stöd i Azure Service Bus
• Utvecklarguide för Service Bus AMQP 1.0
• Komma igång med Service Bus-köer
• Java Message Service API (externt Oracle-dokument)
• Lär dig hur du migrerar från ActiveMQ till Service Bus