Compartilhar via

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

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 Java Message Service (JMS) 2.0.

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

Como começar Conceitos

Modelo de programação do JMS (Java Message Service)

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 ao JMS 1.1 e ao JMS 2.0.

Barramento de Serviço do Azure – A 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 se comunicar com o aplicativo JMS.

Observação

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

Fazer referência a este tutorial é recomendável para entender melhor o JMS (Serviço de Mensagens Java).

Fábrica de conexões

O objeto de 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 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 de 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 apoiada pelo 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 uma TokenCredential.

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

Em seguida, a fábrica de conexões pode ser instanciada 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 ociosa em milissegundos.
    • traceFrames – sinalizador booliano para coletar quadros de rastreamento AMQP para depuração.
    • outros parâmetros de configuração

A fábrica pode ser criada conforme 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 do JMS

Um destino é o objeto que um cliente usa para especificar o destino das mensagens que ele produz e a origem das mensagens que ele 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 atômica de trabalho.

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 reconhece automaticamente o recebimento de uma mensagem de um cliente quando retorna com sucesso de uma chamada de recebimento ou quando o ouvinte de mensagens que a sessão chamou para processar a mensagem retorna com sucesso.
Session.CLIENT_ACKNOWLEDGE O cliente reconhece uma mensagem consumida chamando o método de reconhecimento da mensagem.
Session.DUPS_OK_ACKNOWLEDGE Esse modo de confirmação instrui a sessão a reconhecer de forma preguiçosa a entrega de mensagens.
Session.SESSION_TRANSACTED Esse valor pode ser passado como o argumento para o método createSession(int sessionMode) no objeto Connection 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.

O JMSContext combina a funcionalidade fornecida pelo objeto de conexão e 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 Session , o JMSContext pode ser criado com os mesmos modos de confirmação mencionados nos modos de sessão.

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

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

Produtores de mensagens do JMS

Um produtor de mensagens é 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 mensagem é um objeto criado por um JMSContext ou uma Sessão e usado para receber mensagens enviadas para 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 receive() método.

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 for anterior).

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 mensagens é um objeto usado para tratamento assíncrono 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 estar.

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 do JMS fornece um QueueBrowser objeto que permite que o aplicativo navegue pelas 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 do JMS não fornece uma API para procurar um tópico.

Isso ocorre porque o tópico em si 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 receptor delega a tarefa de filtragem de mensagens ao provedor JMS (nesse caso, o Barramento de Serviço do Azure) em vez de assumir essa responsabilidade por conta própria.

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
  • Consumidor da fila
  • Navegador de filas

Observação

Os seletores do Barramento de Serviço não dão suporte a palavras-chave SQL "LIKE" e "BETWEEN".

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 mostrou como os aplicativos cliente Java usando o JMS (Java Message Service) 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 entidades do JMS (Serviço de Mensagens Java), confira os seguintes artigos:

  • Last updated on