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 Mon, 21 Mar 2011 23:27:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/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/~muellerc">Christian
Mueller</a>
    </h4>
        <br/>
                         <h4>Changes (29)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-unchanged" >h2. SNS Component <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >The SNS component allows messages
to be sent to <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">or
consumed from</span> an [Amazon Simple Notification|http://aws.amazon.com/sns] Topic.
The implementation of the Amazon API is provided by the&amp;nbsp;[AWS SDK|http://aws.amazon.com/sdkforjava/].
<br></td></tr>
            <tr><td class="diff-unchanged" > <br>{info:title=Prerequisites}
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > <br>h3. URI Format <br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-changed-words">{code}aws-sns://topicName<span
class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">/yourTopicName</span>?options{code}</span>
<br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The
&quot;topicName/&quot; 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: <br>{code}aws-sns://arn:aws:sns:us-east-1:123456789012:yourTopicName?options{code}
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">The
topic will be created if they don&#39;t already exists. <br></td></tr>
            <tr><td class="diff-unchanged" >You can append query options to the
URI in the following format, {{?options=value&amp;option2=value&amp;...}} <br>
<br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3.
Endpoint Properties <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3.
URI Options <br>|| Name || Default Value || Context || Description || <br>|amazonSNSClient
| {{null}} | Producer | Reference to a com.amazonaws.services.sqs.AmazonSNSClient in the [Registry].
| <br>|accessKey | {{null}} | Producer | Amazon AWS Access Key | <br>|secretKey
| {{null}} | Producer | Amazon AWS Secret Key | <br>|subject | {{null}} | Producer |
The subject which is used if the message header &#39;CamelAwsSnsSubject&#39; is not
present. | <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">
<br>h4. Common Properties\\ <br>| *Property* | *Default* | *Description* | <br>|
accessKey | \- | AWS access key | <br>| secretKey | \- | AWS secret key | <br>|
amazonSNSClient | \- | Amazon AWS SNS Client | <br>| amazonSQSClient | \- | Amazon AWS
SQS Client | <br>| deleteTopicOnStop | false | Deletes the topic when the component
stops | <br> <br></td></tr>
            <tr><td class="diff-unchanged" >{info:title=Required SNS component
options} <br></td></tr>
            <tr><td class="diff-changed-lines" >You have to provide the amazonSNSClient
<span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">and
amazonSQSClient (consumer only)</span> in the [Registry] or your accessKey and secretKey
to access the [Amazon&#39;s SNS|http://aws.amazon.com/sns]. <br></td></tr>
            <tr><td class="diff-unchanged" >{info} <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3.
Consumer Only Properties\\ <br>| *Property* | *Required* | *Default* | *Description*
| <br>| queueName | \- | \- | Name of the queue to use for the callback | <br>|
queueArn | \- | \- | SQS ARN to use for the callback | <br>| idempotent | \- | false
| If true, consumer will avoid processing messages that it has already processed | <br>|
delay | \- | 500 | Frequency of polling on the queue to check for new messages | <br>|
deleteQueueOnStop | \- | false | Deletes the queue when the component stops | <br>|
verify | \- | false | Verifies each of the messages using the signature in the message. Invalid
messages are deleted | <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3.
Usage <br>h4. Message headers evaluated by the producer <br></td></tr>
            <tr><td class="diff-changed-lines" ><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;">{div:class=confluenceTableSmall}</span>
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">||
Header || Type || Description || <br>| {{CamelAwsSnsSubject}} | {{String}} | The Amazon
SNS message subject. If not set, the subject from the {{SnsConfiguration}} is used. | <br>{div}
<br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3.
Producer Only Properties\\ <br>| *Property* | *Required* | *Default* | *Description*
| <br>| subject | \- | \- | default subject to use for the message being sent if not
overridden in the camel message header with &quot;SNS:Subject&quot; | <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h4.
Message headers set by the producer <br></td></tr>
            <tr><td class="diff-changed-lines" ><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;">{div:class=confluenceTableSmall}</span>
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">||
Header || Type || Description || <br>| {{CamelAwsSnsMessageId}} | {{String}} | The Amazon
SNS message ID. | <br>{div} <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h2.
Consumer Use Cases <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h4.
Advanced AmazonSNSClient configuration <br>If your Camel Application is running behind
a firewall or if you need to have more control over the AmazonSNSClient configuration, you
can create your own instance: <br>{code} <br>AWSCredentials awsCredentials = new
BasicAWSCredentials(&quot;myAccessKey&quot;, &quot;mySecretKey&quot;); <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3.
Subscribing to a topic\\ <br>| *Topic* | *Subscription Endpoint* | *Test Case* | <br>|
topic name | SQS name | SubscribeByTopicNameAndQueueNameTest.java | <br>| topic name
| SQS ARN | SubscribeByTopicNameAndQueueArnTest.java | <br>| topic ARN | SQS name |
SubscribeByTopicArnAndQueueNameTest.java | <br>| topic ARN | SQS ARN | SubscribeByTopicArnAndQueueArnTest.java
| <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">ClientConfiguration
clientConfiguration = new ClientConfiguration(); <br></td></tr>
            <tr><td class="diff-changed-lines" ><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;">clientConfiguration.setProxyHost(&quot;http://myProxyHost&quot;);</span>
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">clientConfiguration.setProxyPort(8080);
<br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3.
Topic Permissions <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">AmazonSNSClient
client = new AmazonSNSClient(awsCredentials, clientConfiguration); <br>{code} <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">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. <br> <br>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. <br> <br>h3.
Queue Permissions <br> <br>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. <br>
<br>Note that the documentation for SQS states that the policy may take up to&amp;nbsp;*60
seconds*&amp;nbsp;to propagate although in practice it appears to be taking over&amp;nbsp;*90
seconds*. 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.
<br> <br>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. <br>
<br>h3. Unsubscribing <br> <br>The consumer will automatically unsubscribe
from the topic once it is stopped. <br> <br>h3. Topic/Queue deletion <br>
<br>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&amp;nbsp;[DeleteQueueOnStopTest.java|http://code.google.com/p/camel-sns/source/browse/trunk/camel-sns/src/test/java/com/massfords/aws/sns/DeleteQueueOnStopTest.java]&amp;nbsp;and&amp;nbsp;[DeleteTopicOnStopTest.java|http://code.google.com/p/camel-sns/source/browse/trunk/camel-sns/src/test/java/com/massfords/aws/sns/DeleteTopicOnStopTest.java]&amp;nbsp;for
examples. <br> <br>h3. Message Mapping between SNS and Camel <br> <br>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 &quot;SNS:&quot;.
The available properties on the message are as follow:\\ <br>| [SNS:MessageId|http://code.google.com/p/camel-sns/w/edit/MessageId]
| A Universally Unique Identifier, unique for each notification published | <br>| SNS:Timestamp
| The time (in GMT) at which the notification was published. | <br>| [SNS:TopicArn|http://code.google.com/p/camel-sns/w/edit/TopicArn]
| The topic to which this message was published | <br>| SNS:Type | The type of the delivery
message, set to “Notification” for notification deliveries. | <br>| SNS:UnsubscribeURL
| A link to unsubscribe the end-point from this topic, and prevent receiving any further notifications.
| <br>| SNS:Message | The payload (body) of the message, as received from the publisher
| <br>| SNS:Subject | The Subject field -- if one was included as an optional parameter
to the publish API call along with the message. | <br>| SNS:Signature | Base64-encoded
“SHA1withRSA” signature of the Message, MessageId[?|http://code.google.com/p/camel-sns/w/edit/MessageId],
Subject (if present), Type, Timestamp, and Topic values. | <br>| [SNS:SignatureVersion|http://code.google.com/p/camel-sns/w/edit/SignatureVersion]
| Version of the Amazon SNS signature used. | <br>\\ <br> <br>These properties
can be used to filter messages in the route.  <br> <br>h3. Producer Use Cases
<br> <br>* Publish by topic name <br>* Publish by topic ARN <br> <br>h3.
AWS Unit Tests <br> <br>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. <br> <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">and
refer to it in your Camel aws-sns component configuration: <br></td></tr>
            <tr><td class="diff-unchanged" >{code} <br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">awscreds.propertiesaccessKey=${env.accessKey}</span>
<span class="diff-added-words"style="background-color: #dfd;">from(&quot;direct:start&quot;)</span>
<br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">secretKey=${env.secretKey}</span>
<span class="diff-added-words"style="background-color: #dfd;">.to(&quot;aws-sns://MyTopic?amazonSNSClient=#amazonSNSClient&quot;);</span>
<br></td></tr>
            <tr><td class="diff-unchanged" >{code} <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Sample
command line: <br>{code}mvn clean install -DaccessKey=YOUR-ACCESS-KEY -DsecreteKey=YOUR-SECRET-KEY
<br>{code} <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h3. Dependencies <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 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">aws-sns:<span class="code-comment">//topicName?options</span></pre>
</div></div>
<p>The topic will be created if they don't already exists.<br/>
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-URIOptions"></a>URI Options</h3>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Name </th>
<th class='confluenceTh'> Default Value </th>
<th class='confluenceTh'> Context </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'>amazonSNSClient </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> Producer </td>
<td class='confluenceTd'> Reference to a com.amazonaws.services.sqs.AmazonSNSClient
in the <a href="/confluence/display/CAMEL/Registry" title="Registry">Registry</a>.
</td>
</tr>
<tr>
<td class='confluenceTd'>accessKey </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> Producer </td>
<td class='confluenceTd'> Amazon AWS Access Key </td>
</tr>
<tr>
<td class='confluenceTd'>secretKey </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> Producer </td>
<td class='confluenceTd'> Amazon AWS Secret Key </td>
</tr>
<tr>
<td class='confluenceTd'>subject </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> Producer </td>
<td class='confluenceTd'> The subject which is used if the message header 'CamelAwsSnsSubject'
is not present. </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 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-Usage"></a>Usage</h3>
<h4><a name="aws-sns-Messageheadersevaluatedbytheproducer"></a>Message headers
evaluated by the producer</h4>
<div class="confluenceTableSmall"><div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Header </th>
<th class='confluenceTh'> Type </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>CamelAwsSnsSubject</tt> </td>
<td class='confluenceTd'> <tt>String</tt> </td>
<td class='confluenceTd'> The Amazon SNS message subject. If not set, the subject from
the <tt>SnsConfiguration</tt> is used. </td>
</tr>
</tbody></table>
</div>
</div>

<h4><a name="aws-sns-Messageheaderssetbytheproducer"></a>Message headers
set by the producer</h4>
<div class="confluenceTableSmall"><div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Header </th>
<th class='confluenceTh'> Type </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>CamelAwsSnsMessageId</tt> </td>
<td class='confluenceTd'> <tt>String</tt> </td>
<td class='confluenceTd'> The Amazon SNS message ID. </td>
</tr>
</tbody></table>
</div>
</div>

<h4><a name="aws-sns-AdvancedAmazonSNSClientconfiguration"></a>Advanced
AmazonSNSClient configuration</h4>
<p>If your Camel Application is running behind a firewall or if you need to have more
control over the AmazonSNSClient configuration, you can create your own instance:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
AWSCredentials awsCredentials = <span class="code-keyword">new</span> BasicAWSCredentials(<span
class="code-quote">"myAccessKey"</span>, <span class="code-quote">"mySecretKey"</span>);

ClientConfiguration clientConfiguration = <span class="code-keyword">new</span>
ClientConfiguration();
clientConfiguration.setProxyHost(<span class="code-quote">"http:<span class="code-comment">//myProxyHost"</span>);
</span>clientConfiguration.setProxyPort(8080);

AmazonSNSClient client = <span class="code-keyword">new</span> AmazonSNSClient(awsCredentials,
clientConfiguration);
</pre>
</div></div>

<p>and refer to it in your Camel aws-sns component configuration:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"direct:start"</span>)
.to(<span class="code-quote">"aws-sns:<span class="code-comment">//MyTopic?amazonSNSClient=#amazonSNSClient"</span>);</span>
</pre>
</div></div>

<h3><a name="aws-sns-Dependencies"></a>Dependencies</h3>
<p>Maven users will need to add the following dependency to their pom.xml.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>pom.xml</b></div><div class="codeContent
panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;dependency&gt;</span>
    <span class="code-tag">&lt;groupId&gt;</span>org.apache.camel<span
class="code-tag">&lt;/groupId&gt;</span>
    <span class="code-tag">&lt;artifactId&gt;</span>camel-aws<span
class="code-tag">&lt;/artifactId&gt;</span>
    <span class="code-tag">&lt;version&gt;</span>${camel-version}<span
class="code-tag">&lt;/version&gt;</span>
<span class="code-tag">&lt;/dependency&gt;</span>
</pre>
</div></div>

<p>where <tt>${camel-version</tt>} must be replaced by the actual version
of Camel (2.6 or higher).</p>

<h3><a name="aws-sns-SeeAlso"></a>See Also</h3>
<ul>
	<li><a href="/confluence/display/CAMEL/Configuring+Camel" title="Configuring Camel">Configuring
Camel</a></li>
	<li><a href="/confluence/display/CAMEL/Component" title="Component">Component</a></li>
	<li><a href="/confluence/display/CAMEL/Endpoint" title="Endpoint">Endpoint</a></li>
	<li><a href="/confluence/display/CAMEL/Getting+Started" title="Getting Started">Getting
Started</a></li>
</ul>

<ul class="alternate" type="square">
	<li><a href="/confluence/display/CAMEL/aws" title="aws">AWS Component</a></li>
</ul>

    </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=18&originalVersion=17">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