Amazon SQS Cloud Connector

Amazon SQS (Simple Queue Service) is a hosted and highly scalable distributed message queue service.

To get the correct version of the artifact to use in your application (since it depends on a specific version of the Amazon Web Services Java SDK), please follow the instructions detailed in Versioning.

Once deployed, a message similar to this one should be printed out to the server’s output:

[fish.payara.cloud.connectors.amazonsqs.api.inbound.AmazonSQSResourceAdapter] [tid: _ThreadID=1 _ThreadName=main] [timeMillis: 1495398495490] [levelValue: 800] Amazon SQS Resource Adapter Started..

Sending messages

Sending messages to Amazon SQS can be done via the JCA and an Amazon specific API. In order to start using this API to send messages, a resource has to be defined via the JCA API; a connection factory.

The connection factory has to be given a name, which can be any name that is valid for JNDI. The java:app namespace is typically recommended to be used. The type of the connection factory to be used for Amazon SQS is fish.payara.cloud.connectors.amazonsqs.api.AmazonSQSConnectionFactory, and we have to specify the resource adapter name which is here amazon-sqs-rar-2.1.0.rar.

Finally, the AWS account details have to be specified in the properties of the corresponding JMS resource definitions.

The following gives an example:

@ConnectionFactoryDefinition (
  name = "java:app/amazonsqs/factory",
  interfaceName = "fish.payara.cloud.connectors.amazonsqs.api.AmazonSQSConnectionFactory",
  resourceAdapter = "amazon-sqs-rar-2.1.0",
  properties = {"awsAccessKeyId=<accessKeyID>", "awsSecretKey=<secretKey>", "region=eu-west-2"}
)
public class SendSQSMessage {
}

With the above definition in place, the following code shows an example of sending a message:

@Singleton
@Startup
public class SendSQSMessage {

 @Resource(lookup = "java:app/amazonsqs/factory")
 private AmazonSQSConnectionFactory factory;

 @PostConstruct
 public void init() {
    try (AmazonSQSConnection connection = factory.createConnection()) {
        SendMessageRequest sendMsgRequest = SendMessageRequest.builder()
                        .queueUrl("<queueURL>")
                        .messageBody("Hello World")
                        .build();
        connection.sendMessage(sendMsgRequest);
    }
    catch (Exception ex) {
    }
 }
}

Receiving messages

Messages can be received from Amazon SQS by creating an MDB (Message Driven Bean) that implements the fish.payara.cloud.connectors.amazonsqs.api.AmazonSQSListener marker interface and has a single method annotated with @OnSQSMessage and the method signature void method(Message message).

The following gives an example:

@MessageDriven(activationConfig = {
    @ActivationConfigProperty(propertyName = "awsAccessKeyId", propertyValue = "someKey"),
    @ActivationConfigProperty(propertyName = "awsSecretKey", propertyValue = "someSecretKey"),
    @ActivationConfigProperty(propertyName = "queueURL", propertyValue = "someQueueURL"),
    @ActivationConfigProperty(propertyName = "pollInterval", propertyValue = "1"),
    @ActivationConfigProperty(propertyName = "region", propertyValue = "eu-west-2")
})
public class ReceiveSQSMessage implements AmazonSQSListener {

    @OnSQSMessage
    public void receiveMessage(Message message) {
     // Handle message
    }
}

Large Message Support

By default, the AWS Java SDK has a message size limitation of 256KB, which can be restrictive for certain use cases.

To address this limitation, the Payara Cloud Connector offers enhanced support for sending and receiving larger messages, surpassing the 256KB restriction by leveraging Amazon S3 storage. To enable this feature, configure the S3 bucket name using the s3BucketName property.

Prerequisites for Larger message support

Before testing the larger message support feature, ensure the following prerequisites are met:

  1. Create an S3 Bucket in AWS:

    • Create a new Amazon S3 bucket in your AWS account where larger messages will be stored.

  2. IAM Role Permissions:

    • Add AmazonS3FullAccess or related permissions to the IAM role associated with your application.

    • This permission ensures that your application has the necessary access to the S3 bucket for storing and retrieving larger messages.

Sending Large Messages

To send messages larger than 256KB, include the s3BucketName property in the connection factory definition. Specify the desired AWS S3 bucket name to store these larger messages.

For example:

@ConnectionFactoryDefinition (
    name = "java:app/amazonsqs/factory",
    interfaceName = "fish.payara.cloud.connectors.amazonsqs.api.AmazonSQSConnectionFactory",
    resourceAdapter = "amazon-sqs-rar-2.1.0",
    properties = {"awsAccessKeyId=<accessKeyID>", "awsSecretKey=<secretKey>", "region=eu-west-2", "s3BucketName=MyS3Bucket"}
)
@Singleton
@Startup
public class SendSQSMessage {
}

After configuring the connection factory with the S3 bucket name, you can send larger messages using the provided Amazon SQS API, as demonstrated in the previous examples.

Receiving Large Messages

To receive larger messages, update the Message Driven Bean (MDB) configuration with the s3BucketName property:

@MessageDriven(activationConfig = {
    @ActivationConfigProperty(propertyName = "awsAccessKeyId", propertyValue = "someKey"),
    @ActivationConfigProperty(propertyName = "awsSecretKey", propertyValue = "someSecretKey"),
    @ActivationConfigProperty(propertyName = "queueURL", propertyValue = "someQueueURL"),
    @ActivationConfigProperty(propertyName = "pollInterval", propertyValue = "1"),
    @ActivationConfigProperty(propertyName = "region", propertyValue = "eu-west-2"),
    @ActivationConfigProperty(propertyName = "s3BucketName", propertyValue = "MyS3Bucket"),
    @ActivationConfigProperty(propertyName = "s3FetchMessage", propertyValue = "true")
})
public class ReceiveSQSMessage implements AmazonSQSListener {

    @OnSQSMessage
    public void receiveMessage(Message message) {
     // Handle larger message
    }
}

Configure the s3BucketName property along with other properties to specify the AWS S3 bucket where larger messages are stored.

Configuration Properties

The full list of configuration properties is given below:

Config Property Name Type Default Notes

awsAccessKeyId

String

None

Must be set to the access key of your AWS account

awsSecretKey

String

None

Must be set to the secret key of your AWS account

queueURL

String

None

Must be set to the URL for an SQS queue

region

String

None

Must be set to the AWS region name of your queue

maxMessages

Integer

10

The maximum number of messages to download on a poll

initialPollDelay

Integer

1

The delay (in seconds) before polling the queue after MDB activation (MDB only)

pollInterval

Integer

3

How often should the adapter poll for messages (in seconds) (MDB Only)

messageAttributeNames

String

All

The list of message attribute names that should be fetched with the message (MDB Only)

attributeNames

String

All

The list of attribute names that should be fetched with the message (MDB Only)

s3BucketName

String

None

AWS S3 bucket name for storing larger messages

s3SizeThreshold

Integer

0

AWS S3 size threshold for storing messages (in bytes)

s3KeyPrefix

String

None

AWS S3 key prefix for organizing stored messages

s3FetchMessage

Boolean

true

Flag to fetch the full message from S3 when it exceeds the size threshold. If set to false, only the message metadata for larger messages, including the bucket name and message key, will be returned instead of the full message.