As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Usar a Biblioteca de Mensagens Java do Amazon SQS
Para começar a usar o Serviço de Mensagens Java (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 do 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 do JMS
Antes de começar, consulte os pré-requisitos em [Pré-requisitos para trabalhar com o JMS e o Amazon SQS](prerequisites.md).
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`. Com os métodos de conexão do 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`.
1. 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](sqs-jms-code-examples.md#example-sender).
### 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 attributes = new HashMap();
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 exatamente uma vez no Amazon SQS](FIFO-queues-exactly-once-processing.md).
## 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);
```
1. 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);
```
1. 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 obter mais informações, consulte [Termos-chave de fila FIFO do Amazon SQS](FIFO-key-terms.md).
```
// 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();
```
1. 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 obter mais informações, consulte [Termos-chave de fila FIFO do Amazon SQS](FIFO-key-terms.md).
```
// 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"));
}
```
1. 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 Java funcionais para usar o JMS com filas padrão do Amazon SQS](sqs-jms-code-examples.md).
Para exemplos completos de envio e recebimento de objetos, consulte [TextMessageSender.java](sqs-jms-code-examples.md#example-sender) e [SyncMessageReceiver.java](sqs-jms-code-examples.md#example-synchronous-message-receiver).
## Recebimento de mensagens de forma assíncrona
No exemplo em [Usar a Biblioteca de Mensagens Java do Amazon SQS](#getting-started), 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.
1. 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 [Usar a Biblioteca de Mensagens Java do Amazon SQS](#getting-started). Para um exemplo completo de um consumidor assíncrono, consulte `AsyncMessageReceiver.java` em [Exemplos de Java funcionais para usar o JMS com filas padrão do Amazon SQS](sqs-jms-code-examples.md).
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 [Usar a Biblioteca de Mensagens Java do Amazon SQS](#getting-started) 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);
```
1. 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 [Usar a Biblioteca de Mensagens Java do Amazon SQS](#getting-started). Para um exemplo completo de um consumidor síncrono com modo de reconhecimento do cliente, consulte `SyncMessageReceiverClientAcknowledge.java` em [Exemplos de Java funcionais para usar o JMS com filas padrão do Amazon SQS](sqs-jms-code-examples.md).
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 obter mais informações, consulte [Uso do modo de reconhecimento do cliente](#using-client-acknowledge-mode).
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](#using-client-acknowledge-mode). 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
```