<commit_before>= AWS Simple Notification System (SNS) Component
:doctitle: AWS Simple Notification System (SNS)
:shortname: aws2-sns
:artifactid: camel-aws2-sns
:description: Send messages to an AWS Simple Notification Topic using AWS SDK version 2.x.
:since: 3.1
:supportlevel: Stable
:component-header: Only producer is supported
include::{cq-version}@camel-quarkus:ROOT:partial$reference/components/aws2-sns.adoc[opts=optional]
//Manually maintained attributes
:group: AWS

*Since Camel {since}*

*{component-header}*

The AWS2 SNS component allows messages to be sent to an
https://aws.amazon.com/sns[Amazon Simple Notification] Topic. The
implementation of the Amazon API is provided by
the https://aws.amazon.com/sdkforjava/[AWS SDK].

Prerequisites

You must have a valid Amazon Web Services developer account, and be
signed up to use Amazon SNS. More information is available at
https://aws.amazon.com/sns[Amazon SNS].

== URI Format

-----------------------------
aws2-sns://topicNameOrArn[?options]
-----------------------------

The topic will be created if they don't already exists. +
 You can append query options to the URI in the following format,
`?options=value&option2=value&...`

== URI Options

// component-configure options: START

// component-configure options: END

// component options: START
include::partial$component-configure-options.adoc[]
include::partial$component-endpoint-options.adoc[]
// component options: END

// endpoint options: START

// endpoint options: END


Required SNS component options

You have to provide the amazonSNSClient in the
Registry or your accessKey and secretKey to access
the https://aws.amazon.com/sns[Amazon's SNS].

== Usage

=== Static credentials vs Default Credential Provider

You have the possibility of avoiding the usage of explicit static credentials, by specifying the useDefaultCredentialsProvider option and set it to true.

 - Java system properties - aws.accessKeyId and aws.secretKey
 - Environment variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
 - Web Identity Token from AWS STS.
 - The shared credentials and config files.
 - Amazon ECS container credentials - loaded from the Amazon ECS if the environment variable AWS_CONTAINER_CREDENTIALS_RELATIVE_URI is set.
 - Amazon EC2 Instance profile credentials. 

For more information about this you can look at https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials.html[AWS credentials documentation]

=== Message headers evaluated by the SNS producer

[width="100%",cols="10%,10%,80%",options="header",]
|=======================================================================
|Header |Type |Description

|`CamelAwsSnsSubject` |`String` |The Amazon SNS message subject. If not set, the subject from the
`SnsConfiguration` is used.
|=======================================================================

=== Message headers set by the SNS producer

[width="100%",cols="10%,10%,80%",options="header",]
|=======================================================================
|Header |Type |Description

|`CamelAwsSnsMessageId` |`String` |The Amazon SNS message ID.
|=======================================================================

=== Advanced AmazonSNS configuration

If you need more control over the `SnsClient` instance configuration you
can create your own instance and refer to it from the URI:

[source,java]
-------------------------------------------------
from("direct:start")
.to("aws2-sns://MyTopic?amazonSNSClient=#client");
-------------------------------------------------

The `#client` refers to a `AmazonSNS` in the
Registry.

=== Create a subscription between an AWS SNS Topic and an AWS SQS Queue

You can create a subscription of an SQS Queue to an SNS Topic in this way:

[source,java]
-------------------------------------------------
from("direct:start")
.to("aws2-sns://test-camel-sns1?amazonSNSClient=#amazonSNSClient&subscribeSNStoSQS=true&queueUrl=https://sqs.eu-central-1.amazonaws.com/780410022472/test-camel");
-------------------------------------------------

The `#amazonSNSClient` refers to a `SnsClient` in the Registry.
By specifying `subscribeSNStoSQS` to true and a `queueUrl` of an existing SQS Queue,
you'll be able to subscribe your SQS Queue to your SNS Topic.

At this point you can consume messages coming from SNS Topic through your SQS Queue

[source,java]
-------------------------------------------------
from("aws2-sqs://test-camel?amazonSQSClient=#amazonSQSClient&delay=50&maxMessagesPerPoll=5")
    .to(...);
-------------------------------------------------

== Topic Autocreation

With the option `autoCreateTopic` users are able to avoid the autocreation of an SNS Topic in case it doesn't exist. The default for this option is `true`.
If set to false any operation on a not-existent topic in AWS won't be successful and an error will be returned.

== SNS FIFO

SNS FIFO are supported. While creating the SQS queue you will subscribe to the SNS topic there is an important point to remember, you'll need to make possible for the SNS Topic to send message to the SQS Queue.

This is clear with an example.

Suppose you created an SNS FIFO Topic called Order.fifo and an SQS Queue called QueueSub.fifo.

In the access Policy of the QueueSub.fifo you should submit something like this

[source,json]
-------------------------------------------------
{
  "Version": "2008-10-17",
  "Id": "__default_policy_ID",
  "Statement": [
    {
      "Sid": "__owner_statement",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::780560123482:root"
      },
      "Action": "SQS:*",
      "Resource": "arn:aws:sqs:eu-west-1:780560123482:QueueSub.fifo"
    },
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "sns.amazonaws.com"
      },
      "Action": "SQS:SendMessage",
      "Resource": "arn:aws:sqs:eu-west-1:780560123482:QueueSub.fifo",
      "Condition": {
        "ArnLike": {
          "aws:SourceArn": "arn:aws:sns:eu-west-1:780410022472:Order.fifo"
        }
      }
    }
  ]
}
-------------------------------------------------

This is a critical step to make the subscription work correctly.

=== SNS Fifo Topic Message group Id Strategy and message Deduplication Id Strategy

When sending something to the FIFO topic you'll need to always set up a message group Id strategy.

If the content-based message deduplication has been enabled on the SNS Fifo topic, where won't be the need of setting a message deduplication id strategy, otherwise you'll have to set it.

== Dependencies

Maven users will need to add the following dependency to their pom.xml.

*pom.xml*

[source,xml]
---------------------------------------
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-aws2-sns</artifactId>
    <version>${camel-version}</version>
</dependency>
---------------------------------------

where `$\{camel-version}` must be replaced by the actual version of Camel.


include::{page-component-version}@camel-spring-boot::page$aws2-sns-starter.adoc[]<commit_msg>CAMEL-16849 - Add at least one example for component in docs - Camel-AWS2-SNS<commit_after>= AWS Simple Notification System (SNS) Component
:doctitle: AWS Simple Notification System (SNS)
:shortname: aws2-sns
:artifactid: camel-aws2-sns
:description: Send messages to an AWS Simple Notification Topic using AWS SDK version 2.x.
:since: 3.1
:supportlevel: Stable
:component-header: Only producer is supported
include::{cq-version}@camel-quarkus:ROOT:partial$reference/components/aws2-sns.adoc[opts=optional]
//Manually maintained attributes
:group: AWS

*Since Camel {since}*

*{component-header}*

The AWS2 SNS component allows messages to be sent to an
https://aws.amazon.com/sns[Amazon Simple Notification] Topic. The
implementation of the Amazon API is provided by
the https://aws.amazon.com/sdkforjava/[AWS SDK].

Prerequisites

You must have a valid Amazon Web Services developer account, and be
signed up to use Amazon SNS. More information is available at
https://aws.amazon.com/sns[Amazon SNS].

== URI Format

-----------------------------
aws2-sns://topicNameOrArn[?options]
-----------------------------

The topic will be created if they don't already exists. +
 You can append query options to the URI in the following format,
`?options=value&option2=value&...`

== URI Options

// component-configure options: START

// component-configure options: END

// component options: START
include::partial$component-configure-options.adoc[]
include::partial$component-endpoint-options.adoc[]
// component options: END

// endpoint options: START

// endpoint options: END


Required SNS component options

You have to provide the amazonSNSClient in the
Registry or your accessKey and secretKey to access
the https://aws.amazon.com/sns[Amazon's SNS].

== Usage

=== Static credentials vs Default Credential Provider

You have the possibility of avoiding the usage of explicit static credentials, by specifying the useDefaultCredentialsProvider option and set it to true.

 - Java system properties - aws.accessKeyId and aws.secretKey
 - Environment variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
 - Web Identity Token from AWS STS.
 - The shared credentials and config files.
 - Amazon ECS container credentials - loaded from the Amazon ECS if the environment variable AWS_CONTAINER_CREDENTIALS_RELATIVE_URI is set.
 - Amazon EC2 Instance profile credentials. 

For more information about this you can look at https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials.html[AWS credentials documentation]

=== Message headers evaluated by the SNS producer

[width="100%",cols="10%,10%,80%",options="header",]
|=======================================================================
|Header |Type |Description

|`CamelAwsSnsSubject` |`String` |The Amazon SNS message subject. If not set, the subject from the
`SnsConfiguration` is used.
|=======================================================================

=== Message headers set by the SNS producer

[width="100%",cols="10%,10%,80%",options="header",]
|=======================================================================
|Header |Type |Description

|`CamelAwsSnsMessageId` |`String` |The Amazon SNS message ID.
|=======================================================================

=== Advanced AmazonSNS configuration

If you need more control over the `SnsClient` instance configuration you
can create your own instance and refer to it from the URI:

[source,java]
-------------------------------------------------
from("direct:start")
.to("aws2-sns://MyTopic?amazonSNSClient=#client");
-------------------------------------------------

The `#client` refers to a `AmazonSNS` in the
Registry.

=== Create a subscription between an AWS SNS Topic and an AWS SQS Queue

You can create a subscription of an SQS Queue to an SNS Topic in this way:

[source,java]
-------------------------------------------------
from("direct:start")
.to("aws2-sns://test-camel-sns1?amazonSNSClient=#amazonSNSClient&subscribeSNStoSQS=true&queueUrl=https://sqs.eu-central-1.amazonaws.com/780410022472/test-camel");
-------------------------------------------------

The `#amazonSNSClient` refers to a `SnsClient` in the Registry.
By specifying `subscribeSNStoSQS` to true and a `queueUrl` of an existing SQS Queue,
you'll be able to subscribe your SQS Queue to your SNS Topic.

At this point you can consume messages coming from SNS Topic through your SQS Queue

[source,java]
-------------------------------------------------
from("aws2-sqs://test-camel?amazonSQSClient=#amazonSQSClient&delay=50&maxMessagesPerPoll=5")
    .to(...);
-------------------------------------------------

== Topic Autocreation

With the option `autoCreateTopic` users are able to avoid the autocreation of an SNS Topic in case it doesn't exist. The default for this option is `true`.
If set to false any operation on a not-existent topic in AWS won't be successful and an error will be returned.

== SNS FIFO

SNS FIFO are supported. While creating the SQS queue you will subscribe to the SNS topic there is an important point to remember, you'll need to make possible for the SNS Topic to send message to the SQS Queue.

This is clear with an example.

Suppose you created an SNS FIFO Topic called Order.fifo and an SQS Queue called QueueSub.fifo.

In the access Policy of the QueueSub.fifo you should submit something like this

[source,json]
-------------------------------------------------
{
  "Version": "2008-10-17",
  "Id": "__default_policy_ID",
  "Statement": [
    {
      "Sid": "__owner_statement",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::780560123482:root"
      },
      "Action": "SQS:*",
      "Resource": "arn:aws:sqs:eu-west-1:780560123482:QueueSub.fifo"
    },
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "sns.amazonaws.com"
      },
      "Action": "SQS:SendMessage",
      "Resource": "arn:aws:sqs:eu-west-1:780560123482:QueueSub.fifo",
      "Condition": {
        "ArnLike": {
          "aws:SourceArn": "arn:aws:sns:eu-west-1:780410022472:Order.fifo"
        }
      }
    }
  ]
}
-------------------------------------------------

This is a critical step to make the subscription work correctly.

=== SNS Fifo Topic Message group Id Strategy and message Deduplication Id Strategy

When sending something to the FIFO topic you'll need to always set up a message group Id strategy.

If the content-based message deduplication has been enabled on the SNS Fifo topic, where won't be the need of setting a message deduplication id strategy, otherwise you'll have to set it.

== Examples

=== Producer Examples

Sending to a topic

[source,java]
--------------------------------------------------------------------------------
from("direct:start")
  .to("aws2-sns://camel-topic?subject=The+subject+message&autoCreateTopic=true");
--------------------------------------------------------------------------------

== Dependencies

Maven users will need to add the following dependency to their pom.xml.

*pom.xml*

[source,xml]
---------------------------------------
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-aws2-sns</artifactId>
    <version>${camel-version}</version>
</dependency>
---------------------------------------

where `$\{camel-version}` must be replaced by the actual version of Camel.


include::{page-component-version}@camel-spring-boot::page$aws2-sns-starter.adoc[]
{'fraction_non_alphanumeric': 0.2121776306716315, 'fraction_numerical': 0.01551510136532892, 'mean_word_length': 3.0681626928471246, 'pattern_counts': {'":': 34, '<': 19, '<?xml version=': 0, '>': 19, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 6}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6001879', 'n_tokens_mistral': 4221, 'n_tokens_neox': 3915, 'n_words': 1391}