Usar a API do Java Message Service 2.0 com o Azure Service Bus Premium

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

Observações importantes

• O suporte à API JMS 2.0 requer o nível Azure Service Bus Premium e a biblioteca azure-servicebus-jms . Usar outras bibliotecas JMS (por exemplo, qpid-jms-client diretamente) contra um namespace premium resulta no comportamento do JMS 1.1, e algumas funcionalidades do JMS 2.0 podem não funcionar como esperado.
• A biblioteca é open source e construída sobre qpid-jms-client — todas as APIs qpid-jms-client funcionam com ela, por isso não há bloqueio de fornecedores. Também fornece predefinidos para políticas de pré-leitura, políticas de religação, Microsoft Entra ID, suporte a Identidade Gerida e Eliminação Automática em Idle.
• A biblioteca está disponível em duas variantes para Jakarta EE e Java EE. Consulte a documentação de suporte do Jakarta EE e javax para mais detalhes sobre qual artefacto utilizar.

Suporte para Jakarta EE e javax

A azure-servicebus-jms biblioteca está disponível em duas variantes para suportar tanto o antigo Java EE (javax.jms) como o mais recente espaço de nomes da API Jakarta EE (jakarta.jms).

Que artefacto devo usar?

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

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

• Se o teu projeto ainda usa Java EE (importações javax.jms.*), continua a usar o com.microsoft.azure artefacto:

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

Migração de javax para Jacarta

Se estás a atualizar a tua aplicação de Java EE para Jakarta EE:

1. Substitui o ID do teu grupo de dependência Maven de com.microsoft.azure para com.azure e atualiza a versão para 2.0.0 ou uma versão mais recente.
2. Atualize todas as javax.jms.* importações no seu código para jakarta.jms.*.
3. A ServiceBusJmsConnectionFactory API e a configuração mantêm-se as mesmas em ambas as variantes, pelo que não são necessárias alterações de código para além das atualizações de importação e dependência.

Pré-requisitos

Introdução ao Service Bus

Este guia pressupõe que você já tenha um namespace do Service Bus. Caso contrário, crie um namespace e uma fila usando o portal 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 por meio do portal do Azure.

Configurar um ambiente de desenvolvimento Java

Para desenvolver aplicações Java, você precisa configurar o ambiente de desenvolvimento apropriado -

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

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

Quais recursos JMS são suportados?

A tabela a seguir lista os recursos do Java Message Service (JMS) que o Azure Service Bus suporta atualmente. O sistema também mostra recursos que não são suportados.

Download da biblioteca de cliente Java Message Service (JMS)

Para utilizar todas as funcionalidades disponíveis no nível premium, adicione a biblioteca azure-servicebus-jms ao percurso de construção do seu projeto. Este pacote fornece os valores de predefinição necessários, como valores de políticas de pré-busca, políticas de reconexão, Microsoft Entra ID e suporte para Identidade Gerida de forma integrada. Escolha o artefato que corresponda ao espaço de nomes da API do seu projeto (veja Suporte Jakarta EE e javax para detalhes):

Jacarta EE (jacarta.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>

Codificação de aplicações Java

Depois que as dependências são importadas, os aplicativos Java podem ser escritos de maneira agnóstica do provedor JMS.

Conectando-se ao Barramento de Serviço do Azure usando JMS

Para se conectar ao Barramento de Serviço do Azure usando clientes JMS, precisa-se da cadeia de conexão 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 apropriado ServiceBusConnectionString.

   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 a JMSContext (para clientes JMS 2.0)

   JMSContext jmsContext = factory.createContext();
   

   Importante

   Embora com nomes semelhantes, uma 'Sessão' JMS e uma 'Sessão' do Service Bus são completamente independentes uma da outra.

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

   No Service Bus, as sessões são estruturas no lado do serviço e do cliente para habilitar o processamento FIFO em filas e assinaturas.

Escrever o aplicativo JMS

Depois que o Session ou JMSContext é instanciado, seu aplicativo pode usar as APIs JMS familiares para executar operações de gerenciamento e de dados. Consulte a lista de recursos JMS suportados para ver quais APIs são suportadas. Aqui estão alguns trechos de código de exemplo para começar a usar o JMS -

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

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

Receber mensagens de uma subscrição duradoura partilhada sobre 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 mostrou como os aplicativos cliente Java que usam o Java Message Service (JMS) sobre AMQP 1.0 podem interagir com o Barramento de Serviço do Azure.

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

Conteúdos relacionados

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