org.mule.modules

mule-module-amazon

config

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 Sources
<sqs:receive-messages> Attempts to receive a message from the queue.

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.

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	Java Type	MIME Type	Encoding
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	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
queueName		The name of the queue to connect to	String	/	UTF-8

Reconnection Strategies

Reconnection Strategies specify how a connector behaves when its connection fails. You can control how Mule attempts to reconnect by specifying a number of criteria:

The type of exception
Number and frequency of reconnection attempts
The notifications generated, and more

With a reconnection strategy, you can better control the behavior of a failed connection, by configuring it, for example, to re-attempt the connection only once every 15 minutes, and to give up after 30 attempts. You can also send an automatic notification to your IT administrator whenever this reconnection strategy goes into effect. You can even define a strategy that attempts to reconnect only during business hours. Such a setting can prove useful if your server is frequently shut down for nightly maintenance.

Configuration

A reconnection strategy that allows the user to configure how many times a reconnection should be attempted and how long to wait between attempts.

    <sqs:config>
         <reconnect count="5" frequency="1000"/>
    </sqs:config>

Reconnect Attributes
Name	Default Value	Description
frequency	2000	Optional. How often (in ms) to reconnect
count	2	Optional. How many reconnection attempts to make

For more information about reconnection strategies in Mule, or even how to write your own custom reconnection strategy please check this section.

Message Processors

<sqs:add-permission>

Adds a permission to this message queue.

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
label	A name for this permission	String	/	UTF-8
accountId	The AWS account ID for the account to share this queue with	String	/	UTF-8
action	A value to indicate how much to share (SendMessage, ReceiveMessage, ChangeMessageVisibility, DeleteMessage, GetQueueAttributes)	String	/	UTF-8
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	String	/	UTF-8

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	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
receiptHandle	#[header:inbound:sqs.message.receipt.handle]	Optional. Receipt handle of the message to be deleted	String	/	UTF-8
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	String	/	UTF-8

Exception Payloads

Payload Class	Description
SQSException	wraps checked exceptions

<sqs:delete-queue>

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

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
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	String	/	UTF-8

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	Description	Java Type	MIME Type	Encoding
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	String	/	UTF-8

Returns

Return Type	Description
int	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	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
attribute	Attribute to get	QueueAttribute	/
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	String	/	UTF-8

Returns

Return Type	Description
Map<String, String>	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	Description	Java Type	MIME Type	Encoding
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	String	/	UTF-8

Returns

Return Type	Description
URL	generated queue service url

<sqs:remove-permission>

Removes a permission from this message queue.

XML Sample

INCLUDE_ERROR

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
label	A name for the permission to be removed	String	/	UTF-8
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	String	/	UTF-8

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	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
message	#[payload]	Optional. The message to send. Defaults to the payload of the Mule message.	String	/	UTF-8
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	String	/	UTF-8

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	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
attribute	Name of the attribute being set	QueueAttribute	/
value	The value being set for this attribute	String	/	UTF-8
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	String	/	UTF-8

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	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
callback		Callback to call when a new message is available.	SourceCallback	/
visibilityTimeout	30	Optional. The duration (in seconds) the retrieved message is hidden from subsequent calls to retrieve.	Integer	/
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.	Boolean	/
pollPeriod	1000	Optional. Time in milliseconds to wait between polls (when no messages were retrieved). Default period is 1000 ms.	Long	/
numberOfMessages	1	Optional. The number of messages to be retrieved on each call (10 messages max). By default, 1 message will be retrieved.	Integer	/
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	String	/	UTF-8

Exception Payloads

Payload Class	Description
SQSException	wraps checked exceptions

mule-module-amazon

Module Overview

Summary

Configuration

Connection Pool

Reconnection Strategies

Configuration

Message Processors

<sqs:add-permission>

XML Sample

Attributes

Exception Payloads

<sqs:delete-message>

XML Sample

Attributes

Exception Payloads

<sqs:delete-queue>

XML Sample

Attributes

Exception Payloads

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

XML Sample

Attributes

Returns

Exception Payloads

<sqs:get-queue-attributes>

XML Sample

Attributes

Returns

Exception Payloads

<sqs:get-url>

XML Sample

Attributes

Returns

<sqs:remove-permission>

XML Sample

Attributes

Exception Payloads

<sqs:send-message>

XML Sample

Attributes

Exception Payloads

<sqs:set-queue-attribute>

XML Sample

Attributes

Exception Payloads

Message Sources

<sqs:receive-messages>

XML Sample

Attributes

Exception Payloads

Transformers