Summary: Configuration | Message Processors | Message Sources

org.mule.modules

mule-module-amazon

Namespace	http://www.mulesoft.org/schema/mule/sqs
Schema Location	http://www.mulesoft.org/schema/mule/sqs/current/mule-sqs.xsd (View Schema)
Schema Version	1.0
Minimum Mule Version	3.2

Module Overview

Amazon Simple Queue Service (Amazon SQS) is a distributed queue messaging service introduced by Amazon.com in April of 2006. It supports programmatic sending of messages via web service applications as a way to communicate over the internet. The intent of SQS is to provide a highly scalable hosted message queue that resolves issues arising from the common producer-consumer problem or connectivity between producer and consumer.

This connector does not provide a method for creating a queue. The reason being that it will automatically create it when its needed instead of having to manually specify so.

Summary

Configuration
<sqs:config> Configure an instance of this module

Message Processors
<sqs:add-permission> Adds a permission to this message queue.
<sqs:delete-message> Deletes the message identified by message object on the queue this object represents.
<sqs:delete-queue> Deletes the message queue represented by this object.
<sqs:get-approximate-number-of-messages> Gets the visibility timeout for the queue.
<sqs:get-queue-attributes> Gets queue attributes.
<sqs:get-url> This method provides the URL for the message queue represented by this object.
<sqs:remove-permission> Removes a permission from this message queue.
<sqs:send-message> Sends a message to a specified queue.
<sqs:set-queue-attribute> Sets a queue attribute.

Message Sources
<sqs:receive-messages> Attempts to receive a message from the queue.

Configuration

To use the this module within a flow the namespace to the module must be included. The resulting flow will look similar to the following:

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:sqs="http://www.mulesoft.org/schema/mule/sqs"
      xsi:schemaLocation="
               http://www.mulesoft.org/schema/mule/core
               http://www.mulesoft.org/schema/mule/core/current/mule.xsd
               http://www.mulesoft.org/schema/mule/sqs
               http://www.mulesoft.org/schema/mule/sqs/current/mule-sqs.xsd">

      <!-- here goes your flows and configuration elements -->

</mule>

This module is configured using the config element. This element must be placed outside of your flows and at the root of your Mule application. You can create as many configurations as you deem necessary as long as each carries its own name.

Each message processor, message source or transformer carries a config-ref attribute that allows the invoker to specify which configuration to use.

Attributes
Type	Name	Default Value	Description
xs:string	name		Optional. Give a name to this configuration so it can be later referenced.
xs:string	accessKey		AWS access id
xs:string	secretAccessKey		AWS secret access id

Connection Pool

This connector offers automatic connection management via the use of a connection pool. The pool will act a storage mechanism for all the connections that are in-use by the user of this connector.

Prior to execution of a processor, the connector will attempt to lookup an already established connection and if one doesn't exists it will create one. That lookup mechanism is done in the connection pool via the use of connection variables declared as keys.

The user of the connector can configure the pool by adding a connection-pooling-profile to the connector configuration like this:

    <sqs:connection-pooling-profile maxActive="10" maxIdle="10"
                             exhaustedAction="WHEN_EXHAUSTED_GROW" maxWait="120"/>

The following is a list of connection attributes, each connection attribute can be configured at the config element level or they can also be added to each processor. If they are used at the processor level they get the benefit of full expression resolution.

Connection Attributes
Name	Description
queueName	The name of the queue to connect to

Also this connector offers automatic retry for certain operations. There are a couple of situations in which a retry may solve the problem at hand, like for example if the system is currently busy or if the session has expired. Those kind of situations are solvable by reacquiring a connection and retrying the operation.

By default, the connector will automatically attempt to retry the operation only once. You can at your choosing specify a greater ammount of retries by using the retryMax attribute on each operation.

    ... retryMax="3"/>

Message Processors

<sqs:add-permission>

Adds a permission to this message queue.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description
config-ref		Optional. Specify which configuration to use.
label		A name for this permission
accountId		The AWS account ID for the account to share this queue with
action		A value to indicate how much to share (SendMessage, ReceiveMessage, ChangeMessageVisibility, DeleteMessage, GetQueueAttributes)
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
queueName		Optional. The name of the queue to connect to
Retry and Reconnect This message processor supports automatic retry and reconnect. If the API call fail for a known error then the API will be automatically retried. This does not happen on every type of error, only a few that has been selected and are known to be recoverable from.
retryMax	1	Optional. Specify how many times this operation can be retried automatically

Child Elements

Exception Payloads

Payload Class	Description
SQSException	wraps checked exceptions

<sqs:delete-message>

Deletes the message identified by message object on the queue this object represents.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description
config-ref		Optional. Specify which configuration to use.
receiptHandle	#[header:inbound:sqs.message.receipt.handle]	Optional. Receipt handle of the message to be deleted
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
queueName		Optional. The name of the queue to connect to
Retry and Reconnect This message processor supports automatic retry and reconnect. If the API call fail for a known error then the API will be automatically retried. This does not happen on every type of error, only a few that has been selected and are known to be recoverable from.
retryMax	1	Optional. Specify how many times this operation can be retried automatically

Child Elements

Exception Payloads

Payload Class	Description
SQSException

<sqs:delete-queue>

Deletes the message queue represented by this object. Will delete non-empty queue.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description
config-ref		Optional. Specify which configuration to use.
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
queueName		Optional. The name of the queue to connect to
Retry and Reconnect This message processor supports automatic retry and reconnect. If the API call fail for a known error then the API will be automatically retried. This does not happen on every type of error, only a few that has been selected and are known to be recoverable from.
retryMax	1	Optional. Specify how many times this operation can be retried automatically

Child Elements

Exception Payloads

Payload Class	Description
SQSException	wraps checked exceptions

<sqs:get-approximate-number-of-messages>

Gets the visibility timeout for the queue.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description
config-ref		Optional. Specify which configuration to use.
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
queueName		Optional. The name of the queue to connect to
Retry and Reconnect This message processor supports automatic retry and reconnect. If the API call fail for a known error then the API will be automatically retried. This does not happen on every type of error, only a few that has been selected and are known to be recoverable from.
retryMax	1	Optional. Specify how many times this operation can be retried automatically

Child Elements

Return Payload

the approximate number of messages in the queue

Exception Payloads

Payload Class	Description
SQSException	wraps checked exceptions

<sqs:get-queue-attributes>

Gets queue attributes. This is provided to expose the underlying functionality. Currently supported attributes are; ApproximateNumberOfMessages CreatedTimestamp LastModifiedTimestamp VisibilityTimeout RequestPayer Policy

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description
config-ref		Optional. Specify which configuration to use.
attribute		Attribute to get
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
queueName		Optional. The name of the queue to connect to
Retry and Reconnect This message processor supports automatic retry and reconnect. If the API call fail for a known error then the API will be automatically retried. This does not happen on every type of error, only a few that has been selected and are known to be recoverable from.
retryMax	1	Optional. Specify how many times this operation can be retried automatically

Child Elements

Return Payload

a map of attributes and their values

Exception Payloads

Payload Class	Description
SQSException	wraps checked exceptions

<sqs:get-url>

This method provides the URL for the message queue represented by this object.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description
config-ref		Optional. Specify which configuration to use.
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
queueName		Optional. The name of the queue to connect to
Retry and Reconnect This message processor supports automatic retry and reconnect. If the API call fail for a known error then the API will be automatically retried. This does not happen on every type of error, only a few that has been selected and are known to be recoverable from.
retryMax	1	Optional. Specify how many times this operation can be retried automatically

Child Elements

Return Payload

generated queue service url

<sqs:remove-permission>

Removes a permission from this message queue.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description
config-ref		Optional. Specify which configuration to use.
label		A name for the permission to be removed
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
queueName		Optional. The name of the queue to connect to
Retry and Reconnect This message processor supports automatic retry and reconnect. If the API call fail for a known error then the API will be automatically retried. This does not happen on every type of error, only a few that has been selected and are known to be recoverable from.
retryMax	1	Optional. Specify how many times this operation can be retried automatically

Child Elements

Exception Payloads

Payload Class	Description
SQSException	wraps checked exceptions

<sqs:send-message>

Sends a message to a specified queue. The message must be between 1 and 256K bytes long.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description
config-ref		Optional. Specify which configuration to use.
message	#[payload]	Optional. The message to send. Defaults to the payload of the Mule message.
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
queueName		Optional. The name of the queue to connect to
Retry and Reconnect This message processor supports automatic retry and reconnect. If the API call fail for a known error then the API will be automatically retried. This does not happen on every type of error, only a few that has been selected and are known to be recoverable from.
retryMax	1	Optional. Specify how many times this operation can be retried automatically

Child Elements

Exception Payloads

Payload Class	Description
SQSException	if something goes wrong

<sqs:set-queue-attribute>

Sets a queue attribute. This is provided to expose the underlying functionality, although the only attribute at this time is visibility timeout.

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description
config-ref		Optional. Specify which configuration to use.
attribute		Name of the attribute being set
value		The value being set for this attribute
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
queueName		Optional. The name of the queue to connect to
Retry and Reconnect This message processor supports automatic retry and reconnect. If the API call fail for a known error then the API will be automatically retried. This does not happen on every type of error, only a few that has been selected and are known to be recoverable from.
retryMax	1	Optional. Specify how many times this operation can be retried automatically

Child Elements

Exception Payloads

Payload Class	Description
SQSException	wraps checked exceptions

Message Sources

<sqs:receive-messages>

Attempts to receive a message from the queue. Every attribute of the incoming message will be added as an inbound property. Also the following properties will also be added:

sqs.message.id = containing the message identification sqs.message.receipt.handle = containing the message identification

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description
config-ref		Optional. Specify which configuration to use.
callback		Callback to call when a new message is available.
visibilityTimeout		Optional. The duration (in seconds) the retrieved message is hidden from subsequent calls to retrieve.
preserveMessages	false	Optional. Flag that indicates if you want to preserve the messages in the queue. False by default, so the messages are going to be deleted.
pollPeriod	1000	Optional. Time in milliseconds to wait between polls. Default period is 1000 ms.
numberOfMessages	1	Optional. The number of messages to be retrieved on each call (10 messages max). By default, 1 message will be retrieved.
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
queueName		Optional. The name of the queue to connect to

Child Elements

Exception Payloads

Payload Class	Description
SQSException