camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Camel > aws-sns
Date Sat, 15 Jan 2011 03:32:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/9/1/_/styles/combined.css?spaceKey=CAMEL&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/CAMEL/aws-sns">aws-sns</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~tjsnell">Tracy
Snell</a>
    </h4>
        <br/>
                         <h4>Changes (4)</h4>
                                 
    
<div id="page-diffs">
            <table class="diff" cellpadding="0" cellspacing="0">
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h4. Common Properties\\ <br>|
*Property* | *Required* | *Default* | *Description* | <br></td></tr>
            <tr><td class="diff-changed-lines" >| accessKey | yes <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">|</span>
<span class="diff-added-words"style="background-color: #dfd;">(see note)|</span>
\- | AWS access key | <br></td></tr>
            <tr><td class="diff-changed-lines" >| secretKey | yes <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">|</span>
<span class="diff-added-words"style="background-color: #dfd;">(see note)|</span>
\- | AWS secret key | <br></td></tr>
            <tr><td class="diff-changed-lines" >| amazonSNSClient | yes <span
class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">|</span>
<span class="diff-added-words"style="background-color: #dfd;">(see note)|</span>
\- | Amazon AWS SNS Client | <br></td></tr>
            <tr><td class="diff-changed-lines" >| amazonSQSClient | yes <span
class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">|</span>
<span class="diff-added-words"style="background-color: #dfd;">(see note)|</span>
\- | Amazon AWS SQS Client | <br></td></tr>
            <tr><td class="diff-unchanged" >| deleteTopicOnStop | \- | false |
Deletes the topic when the component stops | <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
        </table>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h2><a name="aws-sns-SNSComponent"></a>SNS Component</h2>

<p>The SNS component allows messages to be sent to or consumed from an <a href="http://aws.amazon.com/sns"
class="external-link" rel="nofollow">Amazon Simple Notification</a> Topic. The implementation
of the Amazon API is provided by the&nbsp;<a href="http://aws.amazon.com/sdkforjava/"
class="external-link" rel="nofollow">AWS SDK</a>.</p>

<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/information.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Prerequisites</b><br
/>You must have a valid Amazon Web Services developer account, and be signed up to use
Amazon SNS. More information are available at <a href="http://aws.amazon.com/sns" class="external-link"
rel="nofollow">Amazon SNS</a>.</td></tr></table></div>

<h3><a name="aws-sns-URIFormat"></a>URI Format</h3>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">sns:<span class="code-comment">//topicName/yourTopicName?options</span></pre>
</div></div>
<p>The "topicName/" path is a flag that the value following the slash is a topic name
that should be created or one that already exists. Alternatively, you can access existing
topics by their Amazon Resource Name (ARN) as follows:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">sns:<span class="code-comment">//arn:aws:sns:us-east-1:123456789012:yourTopicName?options</span></pre>
</div></div>
<p>You can append query options to the URI in the following format, <tt>?options=value&amp;option2=value&amp;...</tt></p>

<h3><a name="aws-sns-EndpointProperties"></a>Endpoint Properties</h3>


<h4><a name="aws-sns-CommonProperties%5C%5C"></a>Common Properties<br
class="atl-forced-newline" /></h4>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'> <b>Property</b> </td>
<td class='confluenceTd'> <b>Required</b> </td>
<td class='confluenceTd'> <b>Default</b> </td>
<td class='confluenceTd'> <b>Description</b> </td>
</tr>
<tr>
<td class='confluenceTd'> accessKey </td>
<td class='confluenceTd'> yes (see note)</td>
<td class='confluenceTd'> &#45; </td>
<td class='confluenceTd'> AWS access key </td>
</tr>
<tr>
<td class='confluenceTd'> secretKey </td>
<td class='confluenceTd'> yes (see note)</td>
<td class='confluenceTd'> &#45; </td>
<td class='confluenceTd'> AWS secret key </td>
</tr>
<tr>
<td class='confluenceTd'> amazonSNSClient </td>
<td class='confluenceTd'> yes (see note)</td>
<td class='confluenceTd'> &#45; </td>
<td class='confluenceTd'> Amazon AWS SNS Client </td>
</tr>
<tr>
<td class='confluenceTd'> amazonSQSClient </td>
<td class='confluenceTd'> yes (see note)</td>
<td class='confluenceTd'> &#45; </td>
<td class='confluenceTd'> Amazon AWS SQS Client </td>
</tr>
<tr>
<td class='confluenceTd'> deleteTopicOnStop </td>
<td class='confluenceTd'> &#45; </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> Deletes the topic when the component stops </td>
</tr>
</tbody></table>
</div>


<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/information.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Required
SNS component options</b><br />You have to provide the amazonSNSClient and amazonSQSClient
(consumer only) in the <a href="/confluence/display/CAMEL/Registry" title="Registry">Registry</a>
or your accessKey and secretKey to access the <a href="http://aws.amazon.com/sns" class="external-link"
rel="nofollow">Amazon's SNS</a>.</td></tr></table></div>

<h3><a name="aws-sns-ConsumerOnlyProperties%5C%5C"></a>Consumer Only Properties<br
class="atl-forced-newline" /></h3>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'> <b>Property</b> </td>
<td class='confluenceTd'> <b>Required</b> </td>
<td class='confluenceTd'> <b>Default</b> </td>
<td class='confluenceTd'> <b>Description</b> </td>
</tr>
<tr>
<td class='confluenceTd'> queueName </td>
<td class='confluenceTd'> &#45; </td>
<td class='confluenceTd'> &#45; </td>
<td class='confluenceTd'> Name of the queue to use for the callback </td>
</tr>
<tr>
<td class='confluenceTd'> queueArn </td>
<td class='confluenceTd'> &#45; </td>
<td class='confluenceTd'> &#45; </td>
<td class='confluenceTd'> SQS ARN to use for the callback </td>
</tr>
<tr>
<td class='confluenceTd'> idempotent </td>
<td class='confluenceTd'> &#45; </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> If true, consumer will avoid processing messages that it has
already processed </td>
</tr>
<tr>
<td class='confluenceTd'> delay </td>
<td class='confluenceTd'> &#45; </td>
<td class='confluenceTd'> 500 </td>
<td class='confluenceTd'> Frequency of polling on the queue to check for new messages
</td>
</tr>
<tr>
<td class='confluenceTd'> deleteQueueOnStop </td>
<td class='confluenceTd'> &#45; </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> Deletes the queue when the component stops </td>
</tr>
<tr>
<td class='confluenceTd'> verify </td>
<td class='confluenceTd'> &#45; </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> Verifies each of the messages using the signature in the message.
Invalid messages are deleted </td>
</tr>
</tbody></table>
</div>

<p><br class="atl-forced-newline" /></p>

<h3><a name="aws-sns-ProducerOnlyProperties%5C%5C"></a>Producer Only Properties<br
class="atl-forced-newline" /></h3>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'> <b>Property</b> </td>
<td class='confluenceTd'> <b>Required</b> </td>
<td class='confluenceTd'> <b>Default</b> </td>
<td class='confluenceTd'> <b>Description</b> </td>
</tr>
<tr>
<td class='confluenceTd'> subject </td>
<td class='confluenceTd'> &#45; </td>
<td class='confluenceTd'> &#45; </td>
<td class='confluenceTd'> default subject to use for the message being sent if not overridden
in the camel message header with "SNS:Subject" </td>
</tr>
</tbody></table>
</div>

<p><br class="atl-forced-newline" /></p>

<h2><a name="aws-sns-ConsumerUseCases"></a>Consumer Use Cases</h2>

<h3><a name="aws-sns-Subscribingtoatopic%5C%5C"></a>Subscribing to a topic<br
class="atl-forced-newline" /></h3>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'> <b>Topic</b> </td>
<td class='confluenceTd'> <b>Subscription Endpoint</b> </td>
<td class='confluenceTd'> <b>Test Case</b> </td>
</tr>
<tr>
<td class='confluenceTd'> topic name </td>
<td class='confluenceTd'> SQS name </td>
<td class='confluenceTd'> SubscribeByTopicNameAndQueueNameTest.java </td>
</tr>
<tr>
<td class='confluenceTd'> topic name </td>
<td class='confluenceTd'> SQS ARN </td>
<td class='confluenceTd'> SubscribeByTopicNameAndQueueArnTest.java </td>
</tr>
<tr>
<td class='confluenceTd'> topic ARN </td>
<td class='confluenceTd'> SQS name </td>
<td class='confluenceTd'> SubscribeByTopicArnAndQueueNameTest.java </td>
</tr>
<tr>
<td class='confluenceTd'> topic ARN </td>
<td class='confluenceTd'> SQS ARN </td>
<td class='confluenceTd'> SubscribeByTopicArnAndQueueArnTest.java </td>
</tr>
</tbody></table>
</div>

<p><br class="atl-forced-newline" /></p>

<h3><a name="aws-sns-TopicPermissions"></a>Topic Permissions</h3>

<p>If the topic is referenced by its name then the caller is assumed to be the owner
of the topic. The create topic API call is used to create the topic by name or return the
topic if it already exists.</p>

<p>If the topic is referenced by its Amazon Resource Name (ARN) then it is assumed that
the caller has access to subscribe to the topic.</p>

<h3><a name="aws-sns-QueuePermissions"></a>Queue Permissions</h3>

<p>The only supported subscriber endpoint at the moment is an Amazon Simple Queue Service
(SQS). If the queue is referenced by its name, then the caller is assumed to be the owner
of the queue. The create queue API call is used to create the queue by name or return the
queue if it already exists. When the queue is created, its default policy is overridden to
allow the SNS ARN to send messages to the queue.</p>

<p>Note that the documentation for SQS states that the policy may take up to&nbsp;<b>60
seconds</b>&nbsp;to propagate although in practice it appears to be taking over&nbsp;<b>90
seconds</b>. The result is that the SQS endpoint will not begin receiving messages until
the policy is propagated. The unit tests that alter the policy of a queue sleep for 2 minutes
to ensure that the policy has been applied. This will be revisited when the SQS service changes.</p>

<p>If the queue is references by its ARN then it is assumed that the queue exists and
has sufficient permissions on it to receive messages from the topic.</p>

<h3><a name="aws-sns-Unsubscribing"></a>Unsubscribing</h3>

<p>The consumer will automatically unsubscribe from the topic once it is stopped.</p>

<h3><a name="aws-sns-Topic%2FQueuedeletion"></a>Topic/Queue deletion</h3>

<p>The consumer will optionally delete the topic or queue when it is stopped. See the
above for info on controlling this and other behavior with endpoint properties. See&nbsp;<a
href="http://code.google.com/p/camel-sns/source/browse/trunk/camel-sns/src/test/java/com/massfords/aws/sns/DeleteQueueOnStopTest.java"
class="external-link" rel="nofollow">DeleteQueueOnStopTest.java</a>&nbsp;and&nbsp;<a
href="http://code.google.com/p/camel-sns/source/browse/trunk/camel-sns/src/test/java/com/massfords/aws/sns/DeleteTopicOnStopTest.java"
class="external-link" rel="nofollow">DeleteTopicOnStopTest.java</a>&nbsp;for
examples.</p>

<h3><a name="aws-sns-MessageMappingbetweenSNSandCamel"></a>Message Mapping
between SNS and Camel</h3>

<p>The component will unwrap the message payload from its JSON format and put the message
field into the camel message payload and add all of the other fields as headers prefixed with
"SNS:". The available properties on the message are as follow:<br class="atl-forced-newline"
/></p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'> <a href="http://code.google.com/p/camel-sns/w/edit/MessageId"
class="external-link" rel="nofollow">SNS:MessageId</a> </td>
<td class='confluenceTd'> A Universally Unique Identifier, unique for each notification
published </td>
</tr>
<tr>
<td class='confluenceTd'> SNS:Timestamp </td>
<td class='confluenceTd'> The time (in GMT) at which the notification was published.
</td>
</tr>
<tr>
<td class='confluenceTd'> <a href="http://code.google.com/p/camel-sns/w/edit/TopicArn"
class="external-link" rel="nofollow">SNS:TopicArn</a> </td>
<td class='confluenceTd'> The topic to which this message was published </td>
</tr>
<tr>
<td class='confluenceTd'> SNS:Type </td>
<td class='confluenceTd'> The type of the delivery message, set to “Notification”
for notification deliveries. </td>
</tr>
<tr>
<td class='confluenceTd'> SNS:UnsubscribeURL </td>
<td class='confluenceTd'> A link to unsubscribe the end-point from this topic, and prevent
receiving any further notifications. </td>
</tr>
<tr>
<td class='confluenceTd'> SNS:Message </td>
<td class='confluenceTd'> The payload (body) of the message, as received from the publisher
</td>
</tr>
<tr>
<td class='confluenceTd'> SNS:Subject </td>
<td class='confluenceTd'> The Subject field &#8211; if one was included as an optional
parameter to the publish API call along with the message. </td>
</tr>
<tr>
<td class='confluenceTd'> SNS:Signature </td>
<td class='confluenceTd'> Base64-encoded “SHA1withRSA” signature of the Message,
MessageId<a href="http://code.google.com/p/camel-sns/w/edit/MessageId" class="external-link"
rel="nofollow">?</a>, Subject (if present), Type, Timestamp, and Topic values. </td>
</tr>
<tr>
<td class='confluenceTd'> <a href="http://code.google.com/p/camel-sns/w/edit/SignatureVersion"
class="external-link" rel="nofollow">SNS:SignatureVersion</a> </td>
<td class='confluenceTd'> Version of the Amazon SNS signature used. </td>
</tr>
</tbody></table>
</div>

<p><br class="atl-forced-newline" /></p>

<p>These properties can be used to filter messages in the route. </p>

<h3><a name="aws-sns-ProducerUseCases"></a>Producer Use Cases</h3>

<ul>
	<li>Publish by topic name</li>
	<li>Publish by topic ARN</li>
</ul>


<h3><a name="aws-sns-AWSUnitTests"></a>AWS Unit Tests</h3>

<p>The unit tests that invoke the AWS services require valid credentials in order to
work. These credentials are set in a file in the test directory (src/test/resources/awscreds.properties).
Either modify this file to contain the correct accessKey and secretKey or pass these values
in via the command line or export as system properties.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
awscreds.propertiesaccessKey=${env.accessKey}
secretKey=${env.secretKey}
</pre>
</div></div>
<p>Sample command line:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">mvn clean install -DaccessKey=YOUR-ACCESS-KEY -DsecreteKey=YOUR-SECRET-KEY
</pre>
</div></div>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/CAMEL/aws-sns">View Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=24838293&revisedVersion=13&originalVersion=12">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CAMEL/aws-sns?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message