Guía para desarrolladores de JMS 2.0 de Azure Service Bus

En esta guía se proporciona información detallada que le ayudará a comunicarse correctamente con Azure Service Bus mediante la API de Java Message Service (JMS) 2.0.

Como desarrollador de Java, si no está familiarizado con Azure Service Bus, considere la posibilidad de leer los artículos siguientes.

Modelo de programación de Java Message Service (JMS)

El modelo de programación de la API de Message Service Java se describe en las secciones siguientes:

JMS: bloques de construcción

Use los siguientes bloques de creación para comunicarse con la aplicación JMS.

Fábrica de conexiones

El cliente usa el objeto de generador de conexiones para conectarse al proveedor de JMS. El generador de conexiones encapsula un conjunto de parámetros de configuración de conexión que define el administrador.

Cada generador de conexiones es una instancia de la ConnectionFactoryinterfaz , QueueConnectionFactoryo TopicConnectionFactory .

Para simplificar la conexión a Azure Service Bus, estas interfaces se implementan a través de ServiceBusJmsConnectionFactory, ServiceBusJmsQueueConnectionFactory o ServiceBusJmsTopicConnectionFactory respectivamente.

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

Destino de JMS

Un destino es el objeto que usa un cliente para especificar el destino de los mensajes que genera y el origen de los mensajes que consume.

Los destinos se asignan a entidades de Azure Service Bus: colas (en escenarios de punto a punto) y temas (en escenarios de publicación y suscripción).

Conexiones

Una conexión encapsula una conexión virtual con un proveedor de JMS. Con Azure Service Bus, esto representa una conexión con estado entre la aplicación y Azure Service Bus mediante AMQP.

Cree una conexión desde el generador de conexiones, como se muestra en el ejemplo siguiente:

Connection connection = factory.createConnection();

Sesiones

Una sesión es un contexto de un solo subproceso para generar y consumir mensajes. Úselo para crear mensajes, productores de mensajes y consumidores. También proporciona un contexto transaccional para agrupar los envíos y recibirlos en una unidad atómica de trabajo.

Cree una sesión a partir del objeto de conexión como se muestra en el ejemplo siguiente:

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

Modos de sesión

Cree una sesión con cualquiera de los modos siguientes.

Si no especifica el modo de sesión, el valor predeterminado es Session.AUTO_ACKNOWLEDGE.

JMSContext

JMSContext combina la funcionalidad proporcionada por la conexión y el objeto de sesión. Se crea a partir del objeto de generador de conexiones.

JMSContext context = connectionFactory.createContext();

Modos de JMSContext

Al igual que el objeto Session , puede crear JMSContext con los mismos modos de confirmación que se mencionan en Modos de sesión.

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

Si no especifica un modo, el valor predeterminado es JMSContext.AUTO_ACKNOWLEDGE.

Productores de mensajes de JMS

Un productor de mensajes es un objeto que se crea mediante JMSContext o una sesión. Úselo para enviar mensajes a un destino.

Puede crearlo como un objeto independiente, como se muestra en el ejemplo siguiente:

JMSProducer producer = context.createProducer();

O bien, puede crearlo en tiempo de ejecución cuando necesite enviar un mensaje.

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

Consumidores de mensajes de JMS

Un consumidor de mensajes es un objeto que un JMSContext o una sesión crea. Úselo para recibir mensajes enviados a un destino. Créela como se muestra en el ejemplo siguiente:

JMSConsumer consumer = context.createConsumer(dest);

Recepción sincrónica a través del método receive()

El consumidor de mensajes proporciona una manera sincrónica de recibir mensajes del destino a través del receive() método .

Si no especifica argumentos o tiempo de espera, o especifica un tiempo de espera de 0, el consumidor se bloquea indefinidamente a menos que llegue el mensaje o se interrumpe la conexión (lo que ocurra primero).

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

Cuando se proporciona un argumento positivo distinto de cero, el consumidor se bloquea hasta que expire el temporizador.

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

Recepciones asincrónicas con clientes de escucha de mensajes JMS

Un agente de escucha de mensajes es un objeto que se usa para el control asincrónico de mensajes en un destino. Implementa la interfaz MessageListener, que contiene el método onMessage en el que debe residir la lógica de negocios específica.

Debe instanciar un objeto listener de mensajes y registrarlo en un consumidor de mensajes específico mediante el método setMessageListener.

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

Consumo desde temas

Se crean consumidores de mensajes JMS para un destino, que puede ser una cola o un tópico.

Los consumidores de colas son simplemente objetos del lado cliente que residen dentro del contexto de la sesión (y conexión) entre la aplicación cliente y Azure Service Bus.

Sin embargo, los consumidores de temas tienen dos partes:

• Objeto del lado cliente que reside en el contexto de la sesión (o JMSContext) y
• una suscripción que es una entidad en Azure Service Bus.

Las suscripciones se documentan aquí y pueden ser uno de los siguientes tipos:

• Suscripciones duraderas compartidas
• Suscripciones no duraderas compartidas
• Suscripciones duraderas no compartidas
• Suscripciones no duraderas no compartidas

Exploradores de colas de JMS

La API de JMS proporciona un QueueBrowser objeto que la aplicación puede usar para examinar los mensajes de la cola y mostrar los valores de encabezado de cada mensaje.

Puede crear un queue Browser mediante JMSContext, como se muestra en el ejemplo siguiente:

QueueBrowser browser = context.createBrowser(queue);

Selectores de mensajes de JMS

Las aplicaciones receptoras pueden usar selectores de mensajes para filtrar los mensajes que reciben. Mediante el uso de selectores de mensajes, la aplicación receptora descarga el trabajo de filtrar mensajes al proveedor de JMS (en este caso, Azure Service Bus) en lugar de asumir esa responsabilidad.

Puede usar selectores al crear cualquiera de los consumidores siguientes:

• Suscripción duradera compartida
• Suscripción duradera no compartida
• Suscripción compartida no duradera
• Suscripción no duradera no compartida
• Consumidor de cola
• Explorador de colas

Mensajes programados (retraso de entrega)

JMS 2.0 admite la programación de un mensaje para su entrega futura utilizando el método setDeliveryDelay en un MessageProducer o JMSProducer. Al establecer esta propiedad, Service Bus acepta el mensaje, pero solo hace que sea visible para los consumidores una vez transcurrido el período de retraso.

MessageProducer producer = session.createProducer(queue);

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

Para obtener un ejemplo de trabajo completo, consulte QueueScheduledSend.java en el repositorio azure-servicebus-jms-samples.

Selección y resistencia de la factoría de conexión

Cuando utilice ServiceBusJmsConnectionFactory en Spring Boot u otros marcos que gestionan conexiones JMS, elija la envoltura adecuada de la fábrica de conexiones para remitentes y escuchas para asegurar un funcionamiento confiable.

Configuración recomendada

Qué evitar para los oyentes

CachingConnectionFactory en los contenedores de escucha también puede causar problemas porque las sesiones almacenadas en caché pueden hacer referencia a una conexión subyacente obsoleta. En el caso de los escuchas, la fábrica sin procesar garantiza que cada contenedor pueda crear una conexión nueva de forma independiente.

Valores predeterminados de Spring Cloud Azure

Si usa spring-cloud-azure-starter-servicebus-jms (versión 6.2.0+), el iniciador aplica esta separación de fábrica de forma predeterminada:

En versiones anteriores (anteriores a la versión 6.2.0), los remitentes y los agentes de escucha usan ServiceBusJmsConnectionFactory de forma predeterminada, lo que hace que los remitentes creen una nueva conexión por envío.

Adición de un agente de escucha de excepciones

Sin un listener de excepciones, las interrupciones de conexión son completamente silenciosas. Agregue un elemento jakarta.jms.ExceptionListener a los generadores de remitentes y agentes de escucha para la observabilidad:

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

En Spring Boot, establezca el escuchador de excepciones en CachingConnectionFactory (para remitentes) y DefaultJmsListenerContainerFactory (para escuchadores).

Para ver un ejemplo de trabajo completo que muestra todos estos patrones, consulte el ejemplo de resiliencia de JMS de Spring Boot en el repositorio azure-servicebus-jms-samples.

Colas de mensajes no entregados

Cada cola y suscripción de tema en Azure Service Bus tiene asociada una cola de letras muertas (DLQ). El sistema mueve automáticamente los mensajes que no se pueden entregar ni procesar al DLQ. Por ejemplo, el sistema mueve un mensaje a la DLQ cuando el mensaje supera el número máximo de entregas o expira su período de vida (TTL).

En JMS, se accede al DLQ como un destino independiente construyendo la ruta completa y creando un JmsQueue con ella. No se requiere ninguna API especial.

Formato de ruta de acceso DLQ de cola:

<queue-name>/$deadletterqueue

Formato de ruta de acceso a la DLQ de suscripción a un tema:

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

Ejemplo: consumo desde la cola de mensajes fallidos de una cola:

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

Los mensajes con mensajes fallidos incluyen propiedades de metadatos que describen por qué el mensaje estaba fallido:

Lea estas propiedades mediante message.getStringProperty():

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

Para obtener un ejemplo de trabajo completo, consulte QueueDeadLetterReceive.java en el repositorio azure-servicebus-jms-samples.

Asignación de la operación de Service Bus y eliminación de AMQP

Este es el modo en que una disposición de AMQP se traduce en una operación de 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()

Resumen

En esta guía para desarrolladores se muestra cómo Java las aplicaciones cliente que usan Java Message Service (JMS) pueden conectarse a Azure Service Bus.

Pasos siguientes

Para obtener más información sobre Azure Service Bus y detalles sobre las entidades de Java Message Service (JMS), consulte los siguientes artículos:

• Choose entre JMS y el SDK nativo para Azure Service Bus
• Service Bus: colas, temas y suscripciones
• Service Bus - entidades de Servicio de Mensajería Java
• Compatibilidad con AMQP 1.0 en Azure Service Bus
• Guía del desarrollador de AMQP 1.0 de Service Bus
• Introducción a las colas de Service Bus
• API de Java Message Service (documento externo de Oracle)
• Aprenda a migrar de ActiveMQ a Service Bus