Usando a biblioteca de mensagens Java do Amazon SQS

Para começar a usar o Java Message Service (JMS) com o Amazon SQS, use os exemplos de código nesta seção. As seções a seguir mostram como criar uma conexão e uma sessão JMS, e como enviar e receber uma mensagem.

O objeto do cliente encapsulado do Amazon SQS incluído na biblioteca de mensagens Java do Amazon SQS verifica se uma fila do Amazon SQS existe. Se a fila não existir, o cliente a criará.

Criação de uma conexão JMS

Antes de começar, veja os pré-requisitos em. Pré-requisitos para trabalhar com o JMS e o Amazon SQS

1. Crie uma connection factory e chame o método createConnection contra a factory.

   // Create a new connection factory with all defaults (credentials and region) set automatically
   SQSConnectionFactory connectionFactory = new SQSConnectionFactory(
           new ProviderConfiguration(),
           AmazonSQSClientBuilder.defaultClient()
           );
    
   // Create the connection.
   SQSConnection connection = connectionFactory.createConnection();

   A classe SQSConnection estende javax.jms.Connection. Junto com os métodos de conexão JMS padrão, SQSConnection oferece métodos adicionais, como getAmazonSQSClient e getWrappedAmazonSQSClient. Os dois métodos permitem que você execute operações administrativas não incluídas na especificação JMS, como a criação de novas filas. Contudo, o método getWrappedAmazonSQSClient também fornece uma versão encapsulada do cliente do Amazon SQS usada pela conexão atual. O wrapper transforma cada exceção de um cliente em um JMSException, permitindo que ele seja mais facilmente usado pelo código existente que espera ocorrências de JMSException.

2. Você pode usar objetos de cliente retornados de getAmazonSQSClient e de getWrappedAmazonSQSClient para executar operações administrativas não incluídas na especificação do JMS (por exemplo, você pode criar uma fila do Amazon SQS).

   Se você tiver um código que espera exceções JMS, deve usar getWrappedAmazonSQSClient:

   • Se você usar getWrappedAmazonSQSClient, o objeto de cliente retornado transformará todas as exceções em exceções JMS.

   • Se você usar getAmazonSQSClient, todas as exceções serão exceções do Amazon SQS.

Criar uma fila do Amazon SQS

O objeto de cliente encapsulado verifica se uma fila do Amazon SQS existe.

Se a fila não existir, o cliente a criará. Se a fila existir, a função não retornará nada. Para obter mais informações, consulte a seção "Criar uma fila, se necessário" no exemplo TextMessageSender.java.

Como criar uma fila padrão

// Get the wrapped client
AmazonSQSMessagingClientWrapper client = connection.getWrappedAmazonSQSClient();
 
// Create an SQS queue named MyQueue, if it doesn't already exist
if (!client.queueExists("MyQueue")) {
    client.createQueue("MyQueue");
}

Para criar uma fila FIFO

// Get the wrapped client
AmazonSQSMessagingClientWrapper client = connection.getWrappedAmazonSQSClient();

// Create an Amazon SQS FIFO queue named MyQueue.fifo, if it doesn't already exist
if (!client.queueExists("MyQueue.fifo")) {
    Map<String, String> attributes = new HashMap<String, String>();
    attributes.put("FifoQueue", "true");
    attributes.put("ContentBasedDeduplication", "true");
    client.createQueue(new CreateQueueRequest().withQueueName("MyQueue.fifo").withAttributes(attributes));
}

nota

O nome de uma fila FIFO deve terminar com o sufixo .fifo.

Para obter mais informações sobre o atributo ContentBasedDeduplication, consulte Processamento de exatamente uma vez na Amazon SQS.

Envio de mensagens de forma síncrona

1. Quando a conexão e a fila do Amazon SQS subjacente estiverem prontas, crie uma sessão JMS sem transação com o modo AUTO_ACKNOWLEDGE.

   // Create the nontransacted session with AUTO_ACKNOWLEDGE mode
   Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);

2. Para enviar uma mensagem de texto para a fila, crie uma identidade de fila JMS e um produtor de mensagem.

   // Create a queue identity and specify the queue name to the session
   Queue queue = session.createQueue("MyQueue");
    
   // Create a producer for the 'MyQueue'
   MessageProducer producer = session.createProducer(queue);

3. Crie uma mensagem de texto e envie-a para a fila.

   • Para enviar uma mensagem para uma fila padrão, você não precisa definir parâmetros adicionais.

     // Create the text message
     TextMessage message = session.createTextMessage("Hello World!");
      
     // Send the message
     producer.send(message);
     System.out.println("JMS Message " + message.getJMSMessageID());

   • Para enviar uma mensagem para uma fila FIFO, você deve definir o ID do grupo de mensagens. Você também pode definir um ID de eliminação de duplicação de mensagem. Para ter mais informações, consulte Termos-chave do Amazon SQS FIFO Queue.

     // Create the text message
     TextMessage message = session.createTextMessage("Hello World!");
     
     // Set the message group ID
     message.setStringProperty("JMSXGroupID", "Default");
     
     // You can also set a custom message deduplication ID
     // message.setStringProperty("JMS_SQS_DeduplicationId", "hello");
     // Here, it's not needed because content-based deduplication is enabled for the queue
     
     // Send the message
     producer.send(message);
     System.out.println("JMS Message " + message.getJMSMessageID());
     System.out.println("JMS Message Sequence Number " + message.getStringProperty("JMS_SQS_SequenceNumber"));

Recebimento de mensagens de forma síncrona

1. Para receber mensagens, crie um consumidor para a mesma fila e invoque o método start.

   Você também pode chamar o método start na conexão a qualquer momento. No entanto, o consumidor não começa a receber mensagens até você chamá-lo.

   // Create a consumer for the 'MyQueue'
   MessageConsumer consumer = session.createConsumer(queue);
   // Start receiving incoming messages
   connection.start();

2. Chame o método receive no consumidor com um tempo limite definido como 1 segundo e imprima o conteúdo da mensagem recebida.

   • Após receber uma mensagem de uma fila padrão, você pode acessar o conteúdo da mensagem.

     // Receive a message from 'MyQueue' and wait up to 1 second
     Message receivedMessage = consumer.receive(1000);
      
     // Cast the received message as TextMessage and display the text
     if (receivedMessage != null) {
         System.out.println("Received: " + ((TextMessage) receivedMessage).getText());
     }

   • Após receber uma mensagem de uma fila FIFO, você pode acessar o conteúdo da mensagem e outros atributos de mensagem específicos à FIFO, como o ID do grupo de mensagens, o ID de eliminação de duplicação de mensagens e o número de sequência. Para ter mais informações, consulte Termos-chave do Amazon SQS FIFO Queue.

     // Receive a message from 'MyQueue' and wait up to 1 second
     Message receivedMessage = consumer.receive(1000);
     
     // Cast the received message as TextMessage and display the text
     if (receivedMessage != null) {
         System.out.println("Received: " + ((TextMessage) receivedMessage).getText());
         System.out.println("Group id: " + receivedMessage.getStringProperty("JMSXGroupID"));
         System.out.println("Message deduplication id: " + receivedMessage.getStringProperty("JMS_SQS_DeduplicationId"));
         System.out.println("Message sequence number: " + receivedMessage.getStringProperty("JMS_SQS_SequenceNumber"));
     }

3. Feche a conexão e a sessão.

   // Close the connection (and the session).
   connection.close();

A saída será semelhante à seguinte:

JMS Message ID:8example-588b-44e5-bbcf-d816example2
Received: Hello World!

nota

Você pode usar o Spring Framework para inicializar esses objetos.

Para obter mais informações, consulte SpringExampleConfiguration.xml, SpringExample.java e as outras classes auxiliares em ExampleConfiguration.java e ExampleCommon.java na seção Exemplos de trabalho em Java para usar o JMS com filas padrão do Amazon SQS.

Para exemplos completos de envio e recebimento de objetos, consulte TextMessageSender.java e SyncMessageReceiver.java.

Recebimento de mensagens de forma assíncrona

No exemplo em Usando a biblioteca de mensagens Java do Amazon SQS, uma mensagem é enviada para MyQueue e recebida de forma síncrona.

O exemplo a seguir mostra como receber as mensagens de forma assíncrona por meio de um listener.

1. Implemente a interface MessageListener.

   class MyListener implements MessageListener {
    
       @Override
       public void onMessage(Message message) {
           try {
               // Cast the received message as TextMessage and print the text to screen.
               System.out.println("Received: " + ((TextMessage) message).getText());
           } catch (JMSException e) {
               e.printStackTrace();
           }
       }
   }

   O método onMessage da interface MessageListener é chamado quando você recebe uma mensagem. Nesta implementação de listener, o texto armazenado na mensagem é impresso.

2. Em vez de explicitamente chamar o método receive no consumidor, defina o listener da mensagem do consumidor como uma instância da implementação MyListener. O thread principal aguarda um segundo.

   // Create a consumer for the 'MyQueue'.
   MessageConsumer consumer = session.createConsumer(queue);
    
   // Instantiate and set the message listener for the consumer.
   consumer.setMessageListener(new MyListener());
    
   // Start receiving incoming messages.
   connection.start();
    
   // Wait for 1 second. The listener onMessage() method is invoked when a message is received.
   Thread.sleep(1000);

As demais etapas são idênticas às do exemplo Usando a biblioteca de mensagens Java do Amazon SQS. Para um exemplo completo de um consumidor assíncrono, consulte AsyncMessageReceiver.java em Exemplos de trabalho em Java para usar o JMS com filas padrão do Amazon SQS.

A saída deste exemplo é similar ao seguinte:

JMS Message ID:8example-588b-44e5-bbcf-d816example2
Received: Hello World!

Uso do modo de reconhecimento do cliente

O exemplo em Usando a biblioteca de mensagens Java do Amazon SQS usa o modo AUTO_ACKNOWLEDGE em que cada mensagem recebida é confirmada automaticamente (e, portanto, excluída da fila do Amazon SQS subjacente).

1. Para explicitamente reconhecer as mensagens depois de processadas, você deve criar a sessão com o modo CLIENT_ACKNOWLEDGE.

   // Create the non-transacted session with CLIENT_ACKNOWLEDGE mode.
   Session session = connection.createSession(false, Session.CLIENT_ACKNOWLEDGE);

2. Quando a mensagem é recebida, exiba-a e confirme-a explicitamente.

   // Cast the received message as TextMessage and print the text to screen. Also acknowledge the message.
   if (receivedMessage != null) {
       System.out.println("Received: " + ((TextMessage) receivedMessage).getText());
       receivedMessage.acknowledge();
       System.out.println("Acknowledged: " + message.getJMSMessageID());
   }

   nota

   Nesse modo, quando uma mensagem é confirmada, todas as mensagens recebidas antes desta mensagem são implicitamente confirmadas. Por exemplo, se 10 mensagens são recebidas e apenas a 10ª mensagem é reconhecida (na ordem em que as mensagens são recebidas), todas as nove mensagens anteriores também são reconhecidas.

As demais etapas são idênticas às do exemplo Usando a biblioteca de mensagens Java do Amazon SQS. Para um exemplo completo de um consumidor síncrono com modo de reconhecimento do cliente, consulte SyncMessageReceiverClientAcknowledge.java em Exemplos de trabalho em Java para usar o JMS com filas padrão do Amazon SQS.

A saída deste exemplo é similar ao seguinte:

JMS Message ID:4example-aa0e-403f-b6df-5e02example5
Received: Hello World!
Acknowledged: ID:4example-aa0e-403f-b6df-5e02example5

Uso do modo de reconhecimento não ordenado

Ao usar o modo CLIENT_ACKNOWLEDGE, todas as mensagens recebidas antes de uma mensagem explicitamente reconhecida são automaticamente reconhecidas. Para ter mais informações, consulte Uso do modo de reconhecimento do cliente.

A biblioteca de mensagens Java do Amazon SQS fornece outro modo de confirmação. Ao usar o modo UNORDERED_ACKNOWLEDGE, todas as mensagens recebidas devem ser individual e explicitamente reconhecidas pelo cliente, independentemente de sua ordem de recebimento. Para fazer isso, cria uma sessão com o modo UNORDERED_ACKNOWLEDGE.

// Create the non-transacted session with UNORDERED_ACKNOWLEDGE mode.
Session session = connection.createSession(false, SQSSession.UNORDERED_ACKNOWLEDGE);

As etapas restantes são idênticas às do exemplo Uso do modo de reconhecimento do cliente. Para um exemplo completo de um consumidor síncrono com o modo UNORDERED_ACKNOWLEDGE, consulte SyncMessageReceiverUnorderedAcknowledge.java.

Neste exemplo, a saída é similar ao seguinte:

JMS Message ID:dexample-73ad-4adb-bc6c-4357example7
Received: Hello World!
Acknowledged: ID:dexample-73ad-4adb-bc6c-4357example7