Guia do desenvolvedor de JMS 2.0 do Barramento de Serviço do Azure

  • Artigo

Este guia contém informações detalhadas para ajudá-lo a ter sucesso na comunicação com o Barramento de Serviço do Azure usando a API de Serviço de Mensagens Java (JMS) 2.0.

Como desenvolvedor Java, se você for novo no Barramento de Serviço do Azure, considere ler os artigos a seguir.

Introdução Conceitos

Modelo de programação do Serviço de Mensagens Java

O modelo de programação da API do Serviço de Mensagem Java é mostrado nas seguintes seções:

Observação

A camada Premium do Barramento de Serviço do Azure dá suporte a JMS 1.1 e JMS 2.0.

O Barramento de serviço do Azure – camada Standard dá suporte à funcionalidade limitada do JMS 1.1. Para obter mais detalhes, consulte esta documentação.

JMS – Blocos de construção

Os blocos de construção abaixo estão disponíveis para comunicação com o aplicativo JMS.

Observação

O guia a seguir foi adaptado do tutorial do Oracle Java EE 6 para Java Message Service (JMS)

É recomendável referir-se a este tutorial para compreender melhor o Serviço de Mensagens Java (JMS).

Fábrica de conexões

O objeto da fábrica de conexões é usado pelo cliente para se conectar ao provedor JMS. A fábrica de conexões encapsula um conjunto de parâmetros de configuração de conexão que são definidos pelo administrador.

Cada fábrica de conexões é uma instância da interface ConnectionFactory, QueueConnectionFactory ou TopicConnectionFactory.

Para simplificar a conexão com o Barramento de Serviço do Azure, essas interfaces são implementadas por meio do ServiceBusJmsConnectionFactory, ServiceBusJmsQueueConnectionFactory ou ServiceBusJmsTopicConnectionFactory respectivamente.

Importante

Os aplicativos Java que aproveitam a API do JMS 2.0 podem se conectar ao Barramento de Serviço do Azure usando a cadeia de conexão ou usar uma TokenCredential para aproveitar a autenticação com suporte do Microsoft Entra. Ao usar a autenticação com suporte do Microsoft Entra, certifique-se de atribuir funções e permissões à identidade conforme necessário.

Crie uma identidade gerenciada atribuída pelo sistema no Azure e use essa identidade para criar um TokenCredential.

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

O Alocador de conexões pode ser instanciado com os parâmetros abaixo.

  • Credencial de token – representa uma credencial capaz de fornecer um token OAuth.
  • Host – o nome do host do namespace da camada Barramento de Serviço do Azure Premium.
  • Recipiente de propriedade ServiceBusJmsConnectionFactorySettings que contém
    • connectionIdleTimeoutMS – tempo limite de conexão ocioso em milissegundos.
    • traceFrames – sinalizador booliano para coletar quadros de rastreamento AMQP para depuração.
    • Outros parâmetros de configuração

O alocador pode ser criado como mostrado aqui. A credencial de token e o host são parâmetros necessários, mas as outras propriedades são opcionais.

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

Destino JMS

Um destino é o objeto que um cliente usa para especificar o destino das mensagens que produz e a origem das mensagens que consome.

Os destinos são mapeados para entidades no Barramento de Serviço do Azure – filas (em cenários ponto a ponto) e tópicos (em cenários pub-sub).

conexões

Uma conexão encapsula uma conexão virtual com um provedor JMS. Com o Barramento de Serviço do Azure, isso representa uma conexão com estado entre o aplicativo e o Barramento de Serviço do Azure através do AMQP.

Uma conexão é criada a partir da fábrica de conexões, conforme mostrado no exemplo a seguir:

Connection connection = factory.createConnection();

Sessões

Uma sessão é um contexto de thread único para produzir e consumir mensagens. Ele pode ser utilizado para criar mensagens, produtores de mensagens e consumidores, mas também fornece um contexto transacional para permitir o agrupamento de envios e recebimentos em uma unidade de trabalho atômica.

Uma sessão pode ser criada a partir do objeto de conexão, conforme mostrado no exemplo a seguir:

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

Observação

A API do JMS não dá suporte ao recebimento de mensagens de filas ou tópicos do barramento de serviço com sessões de mensagens habilitadas.

Modos de sessão

Uma sessão pode ser criada com qualquer um dos modos abaixo.

Modos de sessão Comportamento
Session.AUTO_ACKNOWLEDGE A sessão confirma automaticamente o recebimento de uma mensagem do cliente quando a sessão é retornada com êxito de uma chamada para recebimento ou quando o ouvinte de mensagem que a sessão chamou para processar a mensagem é retornado com êxito.
Session.CLIENT_ACKNOWLEDGE O cliente reconhece uma mensagem consumida chamando o método de confirmação da mensagem.
Session.DUPS_OK_ACKNOWLEDGE Esse modo de confirmação instrui a sessão a reconhecer lentamente a entrega de mensagens.
Session.SESSION_TRANSACTED Esse valor pode ser passado como o argumento para o método CreateSession (int SessionMode) no objeto de conexão para especificar que a sessão deve usar uma transação local.

Quando o modo de sessão não é especificado, o Session.AUTO_ACKNOWLEDGE é escolhido por padrão.

JMSContext

Observação

JMSContext é definido como parte da especificação JMS 2.0.

JMSContext combina a funcionalidade fornecida pelo objeto de conexão e de sessão. Ele pode ser criado a partir do objeto da fábrica de conexões.

JMSContext context = connectionFactory.createContext();

Modos de JMSContext

Assim como o objeto Sessão, o JMSContext pode ser criado com os mesmos modos de reconhecimento, conforme mencionado nos Modos de sessão.

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

Quando o modo de sessão não é especificado, o JMSContext.AUTO_ACKNOWLEDGE é escolhido por padrão.

Produtores de mensagem JMS

Um produtor de mensagem é um objeto criado usando um JMSContext ou uma sessão e usado para enviar mensagens para um destino.

Ele pode ser criado como um objeto autônomo, conforme mostrado no exemplo a seguir:

JMSProducer producer = context.createProducer();

Ou criado em tempo de execução quando uma mensagem precisa ser enviada.

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

Consumidores de mensagem JMS

Um consumidor de mensagens é um objeto que é criado por um JMSContext ou uma sessão e usado para receber mensagens enviadas a um destino. Ele pode ser criado conforme mostrado neste exemplo:

JMSConsumer consumer = context.createConsumer(dest);

Recebimentos síncronos por meio do método receive()

O consumidor da mensagem fornece uma maneira síncrona de receber mensagens do destino por meio do método receive().

Se nenhum argumento/tempo limite for especificado ou um tempo limite de '0' for especificado, o consumidor será bloqueado indefinidamente, a menos que a mensagem chegue ou a conexão seja interrompida (o que ocorrer antes).

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

Quando um argumento positivo diferente de zero é fornecido, o consumidor é bloqueado até que o temporizador expire.

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

Recebimentos assíncronos com ouvintes de mensagem JMS

Um ouvinte de mensagem é um objeto usado para manipulação assíncrona de mensagens em um destino. Ele implementa a interface MessageListener, que contém o método onMessage onde a lógica de negócios específica deve residir.

Um objeto de ouvinte de mensagem deve ser instanciado e registrado em um consumidor de mensagem específico usando o método setMessageListener.

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

Consumo de tópicos

Os Consumidores de mensagens JMS são criados em um destino que pode ser uma fila ou um tópico.

Os consumidores nas filas são simplesmente objetos do lado do cliente que residem no contexto da sessão (e conexão) entre o aplicativo cliente e o barramento de Serviço do Azure.

No entanto, os consumidores de tópicos têm duas partes –

  • Um objeto do lado do cliente que reside no contexto da sessão (ou JMSContext) e,
  • Uma assinatura que é uma entidade no Barramento de Serviço do Azure.

As assinaturas estão documentadas aqui e podem ser uma das seguintes:

  • Assinaturas duráveis compartilhadas
  • Assinaturas não duráveis compartilhadas
  • Assinaturas duráveis não compartilhadas
  • Assinaturas não duráveis não compartilhadas

Navegadores de fila JMS

A API JMS fornece um objeto QueueBrowser que permite que o aplicativo procure as mensagens na fila e exiba os valores de cabeçalho para cada mensagem.

Um Navegador de Filas pode ser criado usando o JMSContext como no exemplo a seguir:

QueueBrowser browser = context.createBrowser(queue);

Observação

A API JMS não fornece uma API para procurar um tópico.

Isso ocorre porque o próprio tópico não armazena as mensagens. Assim que a mensagem é enviada para o tópico, ela é encaminhada para as assinaturas apropriadas.

Seletores de mensagem JMS

Os seletores de mensagem podem ser usados pelo recebimento de aplicativos para filtrar as mensagens recebidas. Com os seletores de mensagem, o aplicativo de recebimento descarrega o trabalho de filtragem de mensagens para o provedor JMS (nesse caso, o Barramento de Serviço do Azure) em vez de assumir a responsabilidade propriamente dita.

Os seletores podem ser utilizados ao criar qualquer um dos consumidores abaixo –

  • Assinatura durável compartilhada
  • Assinatura durável não compartilhada
  • Assinatura não durável compartilhada
  • Assinatura não durável não compartilhada
  • Navegador de filas

Disposição do Advanced Message Queuing Protocol e mapeamento da operação de Barramento de Serviço

Veja como uma disposição AMQP é convertida em uma operação do Barramento de Serviço:

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

Resumo

Este guia do desenvolvedor demonstra como os aplicativos cliente Java que usam o Java Message Service (JMS) podem se conectar com o Barramento de Serviço do Azure.

Próximas etapas

Para obter mais informações sobre o Barramento de Serviço do Azure e detalhes sobre as entidades do Serviço de Mensagens Java (JMS), confira os artigos a seguir: