Usar a API do Serviço de Mensagens do Java 2.0 com o Barramento de Serviço Premium do Azure

Este artigo explica como usar a API do popular Serviço de Mensagens Java (JMS) 2.0 para interagir com o Barramento de Serviço do Azure por meio do protocolo AMQP 1.0 (Advanced Message Queueing Protocol).

Notas importantes

• O suporte à API do JMS 2.0 requer o Barramento de Serviço do Azure na camada Premium e a biblioteca azure-servicebus-jms. Usar outras bibliotecas JMS (por exemplo, qpid-jms-client diretamente) em um namespace premium resulta no comportamento do JMS 1.1 e alguns recursos do JMS 2.0 podem não funcionar conforme o esperado.
• A biblioteca é de software livre e foi criada sobre qpid-jms-client — todas as APIs qpid-jms-client funcionam com ela, portanto, não há nenhum bloqueio de fornecedor. Ele também fornece padrões para políticas de pré-busca, políticas de reconexão, Microsoft Entra ID, suporte à Identidade Gerenciada e Exclusão Automática no Ocioso.
• A biblioteca está disponível em duas variantes para Jakarta EE e Java EE. Consulte o suporte do Jakarta EE e javax para obter detalhes sobre qual artefato usar.

Suporte a Jakarta EE e javax

A azure-servicebus-jms biblioteca está disponível em duas variantes para dar suporte ao Java EE herdado (javax.jms) e aos namespaces de API Jakarta EE (jakarta.jms) mais recentes.

Qual artefato devo usar?

• Se o projeto usar Jakarta EE 9 ou posterior (por exemplo, Spring Boot 3.x, Quarkus 3.x ou qualquer estrutura que importe jakarta.jms.*), use o com.azure artefato:

  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-servicebus-jms</artifactId>
    <version>2.1.0</version>
  </dependency>
  

• Se o seu projeto ainda estiver usando Java EE (importações javax.jms.*), continue usando o artefato com.microsoft.azure:

  <dependency>
    <groupId>com.microsoft.azure</groupId>
    <artifactId>azure-servicebus-jms</artifactId>
    <version>1.0.2</version>
  </dependency>
  

Migrando do javax para Jacarta

Se você estiver atualizando seu aplicativo do Java EE para o Jakarta EE:

1. Substitua o ID do grupo da dependência do Maven de com.microsoft.azure para com.azure e atualize a versão para 2.0.0 ou posterior.
2. Atualize todas as javax.jms.* importações em seu código para jakarta.jms.*.
3. A ServiceBusJmsConnectionFactory API e a configuração permanecem as mesmas em ambas as variantes, portanto, nenhuma alteração de código é necessária além das atualizações de importação e dependência.

Pré-requisitos

Introdução ao Barramento de Serviço

Este guia pressupõe que você já tenha um namespace do barramento de serviço. Caso contrário, crie um namespace e uma fila usando o Portal do Azure. Para obter mais informações sobre como criar namespaces e filas do Barramento de Serviço, consulte Introdução às filas do Barramento de Serviço no portal do Azure.

Configurar um ambiente de desenvolvimento Java

Para desenvolver aplicativos Java, você precisa configurar o ambiente de desenvolvimento apropriado -

• O JDK (Java Development Kit) ou o JRE (Java Runtime Environment) têm de estar instalados.
• O JDK ou o JRE são adicionados ao caminho de compilação e às variáveis de sistema apropriadas.
• Um Java IDE é instalado para utilizar o JDK ou o JRE. Por exemplo, Eclipse ou IntelliJ.

Para saber mais sobre como preparar o seu ambiente de desenvolvedor para Java no Azure, utilize este guia.

Quais recursos do Serviço de Mensagens do Java têm suporte?

A tabela a seguir lista os recursos do JMS (Java Message Service) que o Barramento de Serviço do Azure suporta atualmente. Ele também mostra funcionalidades não suportadas.

Baixando a biblioteca de cliente do Serviço de Mensagens do Java (JMS)

Para utilizar todos os recursos disponíveis na camada premium, adicione a biblioteca azure-servicebus-jms ao caminho de build do seu projeto. Esse pacote fornece os padrões necessários, como valores de política de pré-busca, políticas de reconexão, Microsoft Entra ID e suporte à Identidade Gerenciada prontos para uso. Escolha o artefato que corresponde ao namespace da API do projeto (consulte Jakarta EE e o suporte a javax para obter detalhes):

Jakarta EE (jakarta.jms):

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-servicebus-jms</artifactId>
  <version>2.1.0</version>
</dependency>

Java EE (javax.jms):

<dependency>
  <groupId>com.microsoft.azure</groupId>
  <artifactId>azure-servicebus-jms</artifactId>
  <version>1.0.2</version>
</dependency>

Codificando os aplicativos Java

Depois que as dependências são importadas, os aplicativos Java podem ser gravados de maneira independente do provedor JMS.

Conectando-se ao barramento de serviço do Azure usando o JMS

Para se conectar ao barramento de serviço do Azure usando clientes do JMS, você precisa da cadeia de conexão que está disponível nas 'Políticas de Acesso Compartilhado' no portal do Azure em Cadeia de Conexão Primária.

1. Instanciar o ServiceBusJmsConnectionFactorySettings

   ServiceBusJmsConnectionFactorySettings connFactorySettings = new ServiceBusJmsConnectionFactorySettings();
   connFactorySettings.setConnectionIdleTimeoutMS(20000);
   

2. Instancie o ServiceBusJmsConnectionFactory com o ServiceBusConnectionString apropriado.

   String ServiceBusConnectionString = "<SERVICE_BUS_CONNECTION_STRING_WITH_MANAGE_PERMISSIONS>";
   ConnectionFactory factory = new ServiceBusJmsConnectionFactory(ServiceBusConnectionString, connFactorySettings);
   

3. Use o ConnectionFactory para criar um Connection e, em seguida, um Session,

   Connection connection = factory.createConnection();
   Session session = connection.createSession();
   

   ou então um JMSContext (para clientes do JMS 2.0)

   JMSContext jmsContext = factory.createContext();
   

   Importante

   Embora tenham nomes parecidos, a ‘Sessão’ do JMS e a ‘Sessão’ do Barramento de Serviço são completamente independentes uma da outra.

   No JMS 1.1, Session é um bloco de construção fundamental da API que permite a criação do MessageProducer, do MessageConsumer e do próprio Message. Para obter mais detalhes, examine o modelo de programação da API do JMS

   No Barramento de Serviço, as sessões são constructos no lado do cliente e do serviço para habilitar o processamento de PEPS em filas e assinaturas.

Escrever o aplicativo JMS

Depois que o Session ou JMSContext for instanciado, seu aplicativo poderá usar as APIs JMS familiares para executar operações de gerenciamento e de dados. Consulte a lista de recursos de JMS com suporte e veja quais APIs têm suporte. Confira aqui alguns trechos de código de exemplo para começar a usar o JMS –

Enviando mensagens para uma fila e um tópico

// Create the queue and topic
Queue queue = jmsContext.createQueue("basicQueue");
Topic topic = jmsContext.createTopic("basicTopic");
// Create the message
Message msg = jmsContext.createMessage();

// Create the JMS message producer
JMSProducer producer = jmsContext.createProducer();

// send the message to the queue
producer.send(queue, msg);
// send the message to the topic
producer.send(topic, msg);

Recebendo mensagens de uma fila

// Create the queue
Queue queue = jmsContext.createQueue("basicQueue");

// Create the message consumer
JMSConsumer consumer = jmsContext.createConsumer(queue);

// Receive the message
Message msg = (Message) consumer.receive();

Como receber mensagens de uma assinatura durável compartilhada em um tópico

// Create the topic
Topic topic = jmsContext.createTopic("basicTopic");

// Create a shared durable subscriber on the topic
JMSConsumer sharedDurableConsumer = jmsContext.createSharedDurableConsumer(topic, "sharedDurableConsumer");

// Receive the message
Message msg = (Message) sharedDurableConsumer.receive();

Resumo

Este guia demonstrou como os aplicativos de cliente Java que usam o Serviço de Mensagens do Java (JMS) por meio do protocolo AMQP 1.0 podem se conectar ao Barramento de Serviço do Azure.

Você também pode usar o AMQP 1.0 do Service Bus de outras linguagens, incluindo .NET, C, Python e PHP. Os componentes criados com essas diferentes linguagens podem trocar mensagens de forma confiável e com total fidelidade usando o suporte do AMQP 1.0 no Service Bus.

Conteúdo relacionado

• Usar JMS no Spring para acessar o Barramento de Serviço do Azure
• Usar o Barramento de Serviço do Azure com o JMS