Guide du développeur JMS 2.0 pour Azure Service Bus

Ce guide fournit des informations détaillées pour vous aider à communiquer avec Azure Service Bus à l’aide de l’API Java Message Service (JMS) 2.0.

En tant que développeur Java, si vous débutez avec Azure Service Bus, envisagez de lire les articles suivants.

modèle de programmation Java Message Service (JMS)

Le modèle de programmation de l’API Java Message Service est décrit dans les sections suivantes :

JMS - Blocs de construction

Utilisez les blocs de construction suivants pour communiquer avec l’application JMS.

Fabrique de connexion

Le client utilise l'objet factory de connexion pour se connecter au fournisseur JMS. L'usine de connexions encapsule un ensemble des paramètres de configuration de connexion que l’administrateur définit.

Chaque fabrique de connexion est une instance de l’interface ConnectionFactory, QueueConnectionFactory ou TopicConnectionFactory.

Pour simplifier la connexion à Azure Service Bus, ces interfaces sont implémentées via ServiceBusJmsConnectionFactory, ServiceBusJmsQueueConnectionFactory ou ServiceBusJmsTopicConnectionFactory respectivement.

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

Destination JMS

Une destination est l’objet qu’un client utilise pour spécifier la cible des messages qu’il produit et la source des messages qu’il consomme.

Les destinations sont mappées vers les entités dans les files d’attente (dans les scénarios point à point) et les rubriques (dans les scénarios publication-abonnement) d’Azure Service Bus.

Connexions

Une connexion encapsule une connexion virtuelle avec un fournisseur JMS. Avec Azure Service Bus, cela représente une connexion avec état entre l’application et Azure Service Bus par AMQP.

Créez une connexion à partir de l'usine de connexions, comme indiqué dans l’exemple suivant :

Connection connection = factory.createConnection();

Séances

Une session est un contexte à thread unique pour la production et la consommation de messages. Utilisez-le pour créer des messages, des producteurs de messages et des consommateurs. Il fournit également un contexte transactionnel pour regrouper les envois et les réceptions dans une unité atomique de travail.

Créez une session à partir de l’objet de connexion, comme illustré dans l’exemple suivant :

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

Modes de session

Créez une session avec l’un des modes suivants.

Si vous ne spécifiez pas le mode session, la valeur par défaut est Session.AUTO_ACKNOWLEDGE.

JMSContext

JMSContext combine les fonctionnalités fournies par l’objet de connexion et de session. Vous le créez à partir de l’objet de fabrique de connexion.

JMSContext context = connectionFactory.createContext();

Modes JMSContext

Tout comme l’objet Session, vous pouvez créer le JMSContext avec les mêmes modes d’accusé de réception que ceux indiqués dans Modes de session.

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

Si vous ne spécifiez pas de mode, la valeur par défaut est JMSContext.AUTO_ACKNOWLEDGE.

Producteurs de messages JMS

Un producteur de messages est un objet que vous créez à l’aide d’un JMSContext ou d’une session. Utilisez-le pour envoyer des messages à une destination.

Vous pouvez le créer en tant qu’objet autonome, comme illustré dans l’exemple suivant :

JMSProducer producer = context.createProducer();

Vous pouvez également le créer au moment de l’exécution lorsque vous devez envoyer un message.

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

Consommateurs de messages JMS

Un consommateur de messages est un objet créé par un JMSContext ou une session. Utilisez-la pour recevoir des messages envoyés à une destination. Créez-le comme indiqué dans l’exemple suivant :

JMSConsumer consumer = context.createConsumer(dest);

Réceptions synchrones via la méthode receive()

Le consommateur de messages fournit un moyen synchrone de recevoir des messages de la destination via la receive() méthode.

Si vous ne spécifiez pas d’arguments ou de délai d’expiration, ou si vous spécifiez un délai d’expiration 0, le consommateur bloque indéfiniment, sauf si le message arrive, ou si la connexion est interrompue (selon ce qui est antérieur).

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

Lorsque vous fournissez un argument positif différent de zéro, le consommateur se bloque jusqu’à ce que le temporisateur expire.

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

Réceptions asynchrones avec les écouteurs de messages JMS

Un écouteur de message est un objet que vous utilisez pour la gestion asynchrone des messages sur une destination. Il implémente l’interface MessageListener , qui contient la méthode dans laquelle la onMessage logique métier spécifique doit vivre.

Vous devez instancier un objet écouteur de message et l’inscrire auprès d’un consommateur de messages spécifique à l’aide de la méthode setMessageListener.

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

Utilisation à partir de rubriques

Vous créez les consommateurs de messages JMS à partir d’une destination, qui peut être une file d’attente ou un topic.

Les consommateurs sur les files d’attente sont simplement des objets côté client qui vivent dans le contexte de la session (et de la connexion) entre l’application cliente et Azure Service Bus.

En revanche, les consommateurs sur les topics comportent deux parties :

• Objet côté client qui réside dans le contexte de la session (ou JMSContext) et
• Un abonnement qui est une entité sur Azure Service Bus.

Les abonnements sont documentés ici et peuvent être l’un des types suivants :

• Abonnements durables partagés
• Abonnements non durables partagés
• Abonnements durables non partagés
• Abonnements non durables non partagés

Explorateurs de files d’attente JMS

L’API JMS fournit un QueueBrowser objet que l’application peut utiliser pour parcourir les messages dans la file d’attente et afficher les valeurs d’en-tête pour chaque message.

Vous pouvez créer un navigateur de files d’attente à l’aide de JMSContext, comme illustré dans l’exemple suivant :

QueueBrowser browser = context.createBrowser(queue);

Sélecteurs de messages JMS

Les applications de réception peuvent utiliser des sélecteurs de messages pour filtrer les messages qu'elles reçoivent. En utilisant des sélecteurs de messages, l’application de réception décharge le travail de filtrage des messages vers le fournisseur JMS (dans ce cas, Azure Service Bus) au lieu de prendre cette responsabilité elle-même.

Vous pouvez utiliser des sélecteurs lors de la création d’un des consommateurs suivants :

• Abonnement durable partagé
• Abonnement durable non partagé
• Abonnement non durable partagé
• Abonnement non durable non partagé
• Consommateur de file d’attente
• Navigateur de file d’attente

Messages planifiés (délai de remise)

JMS 2.0 prend en charge la planification d’un message pour une remise ultérieure en utilisant la méthode setDeliveryDelay sur un MessageProducer ou un JMSProducer. Lorsque vous définissez cette propriété, Service Bus accepte le message, mais le rend visible uniquement aux consommateurs une fois la période de retard écoulée.

MessageProducer producer = session.createProducer(queue);

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

Pour obtenir un exemple de travail complet, consultez QueueScheduledSend.java dans le référentiel azure-servicebus-jms-samples.

Sélection et résilience de l'usine de connexion

Lorsque vous utilisez ServiceBusJmsConnectionFactory dans Spring Boot ou d’autres frameworks qui gèrent les connexions JMS, choisissez le wrapper de fabrique de connexion approprié pour les émetteurs et les écouteurs afin de garantir un fonctionnement fiable.

Configuration recommandée

Ce qu'il faut éviter pour les auditeurs

CachingConnectionFactory sur les conteneurs de l’écouteur peut également entraîner des problèmes, car les sessions mises en cache peuvent référencer une connexion sous-jacente obsolète. Pour les écouteurs, la fabrique brute garantit que chaque conteneur peut créer une nouvelle connexion indépendamment.

Spring Cloud Azure valeurs par défaut

Si vous utilisez spring-cloud-azure-starter-servicebus-jms (version 6.2.0+), le démarrage applique cette séparation de fabrique par défaut :

Sur les versions antérieures (pré-6.2.0), les expéditeurs et les écouteurs utilisent ServiceBusJmsConnectionFactory par défaut, ce qui entraîne la création d’une connexion par envoi.

Ajout d’un écouteur d’exception

Sans gestionnaire d'exceptions, les interruptions de connexion se produisent sans aucune notification. Ajoutez un jakarta.jms.ExceptionListener aux fabriques d’émetteurs et d’écouteurs afin d’améliorer l’observabilité :

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

Dans Spring Boot, définissez l'écouteur d’exception sur le CachingConnectionFactory (pour les émetteurs) et le DefaultJmsListenerContainerFactory (pour les auditeurs).

Pour obtenir un exemple de travail complet montrant tous ces modèles, consultez l’exemple Spring Boot JMS Resilience dans le référentiel azure-servicebus-jms-samples.

Files d’attente de lettres mortes

Chaque file d’attente et chaque abonnement à un topic dans Azure Service Bus possède une file d’attente de lettres mortes (DQL) associée. Le système déplace automatiquement les messages qu’il ne peut pas remettre ou traiter vers la DLQ. Par exemple, le système déplace un message vers la DLQ lorsque le message dépasse le nombre maximal de remises ou sa durée de vie (TTL) expire.

Dans JMS, vous accédez au DLQ en tant que destination distincte en construisant le chemin complet et en créant un JmsQueue en utilisant celui-ci. Aucune API spéciale n’est requise.

Format de chemin DLQ de file d’attente :

<queue-name>/$deadletterqueue

Format du chemin de la DLQ pour un abonnement à un topic :

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

Exemple - consommation depuis la file d’attente de lettres mortes d’une file d’attente :

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

Les messages à lettres mortes incluent des propriétés de métadonnées qui décrivent pourquoi le message a été mis en lettres mortes :

Lisez ces propriétés à l’aide de message.getStringProperty():

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

Pour obtenir un exemple de travail complet, consultez QueueDeadLetterReceive.java dans le référentiel azure-servicebus-jms-samples.

Mappage entre une disposition AMQP et une opération Service Bus

Voici comment une disposition AMQP se traduit par une opération Service Bus :

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

Résumé

Ce guide de développement montre comment Java applications clientes qui utilisent Java Message Service (JMS) peuvent se connecter à Azure Service Bus.

Étapes suivantes

Pour plus d’informations sur Azure Service Bus et des détails sur les entités Java Message Service (JMS), consultez les articles suivants :

• Choose entre JMS et le SDK natif pour Azure Service Bus
• Service Bus - Files d’attente, rubriques et abonnements
• Service Bus – Entités Java Message Service
• Prise en charge d’AMQP 1.0 dans Azure Service Bus
• Guide du développeur sur l’utilisation de Service Bus avec AMQP 1.0
• Prise en main des files d’attente Service Bus
• API Java Message Service (documentation externe d'Oracle)
• Découvrez comment migrer d’ActiveMQ vers Service Bus