= AWS DynamoDB Streams Component
:doctitle: AWS DynamoDB Streams
:shortname: aws2-ddbstream
:artifactid: camel-aws2-ddb
:description: Receive messages from AWS DynamoDB Stream.
:since: 3.1
:supportlevel: Stable
:tabs-sync-option:
:component-header: Only consumer is supported
//Manually maintained attributes
:group: AWS
:camel-spring-boot-name: aws2-ddb

*Since Camel {since}*

*{component-header}*

The AWS2 DynamoDB Stream component supports receiving messages from
Amazon DynamoDB Stream service.

Prerequisites

You must have a valid Amazon Web Services developer account, and be
signed up to use Amazon DynamoDB Streams. More information are available
at https://aws.amazon.com/dynamodb/[AWS DynamoDB]

== URI Format

------------------------------------
aws2-ddbstream://table-name[?options]
------------------------------------

The stream needs to be created prior to it being used. +
 You can append query options to the URI in the following format,
?options=value&option2=value&...


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


Required DynamoDBStream component options

You have to provide the DynamoDbStreamsClient in the
Registry with proxies and relevant credentials
configured.

== Sequence Numbers

You can provide a literal string as the sequence number or provide a
bean in the registry. An example of using the bean would be to save your
current position in the change feed and restore it on Camel startup.

It is an error to provide a sequence number that is greater than the
largest sequence number in the describe-streams result, as this will
lead to the AWS call returning an HTTP 400.

== Usage

=== Static credentials, Default Credential Provider and Profile Credentials Provider

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

The order of evaluation for Default Credentials Provider is the following:

 - 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. 
 
You have also the possibility of using Profile Credentials Provider, by specifying the useProfileCredentialsProvider option to true and profileCredentialsName to the profile name.

Only one of static, default and profile credentials could be used at the same time.

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]

=== Coping with Downtime

==== AWS DynamoDB Streams outage of less than 24 hours

The consumer will resume from the last seen sequence number (as
implemented
for https://issues.apache.org/jira/browse/CAMEL-9515[CAMEL-9515]), so
you should receive a flood of events in quick succession, as long as the
outage did not also include DynamoDB itself.

=== AWS DynamoDB Streams outage of more than 24 hours

Given that AWS only retain 24 hours worth of changes, you will have
missed change events no matter what mitigations are in place.

=== Message Body

The Message body is instance of "software.amazon.awssdk.services.dynamodb.model.Record", for more information about it, have a look at the https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/dynamodb/model/Record.html[related javadoc]

== 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-ddb</artifactId>
    <version>${camel-version}</version>
</dependency>
---------------------------------------

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


include::spring-boot:partial$starter.adoc[]
