= AWS DynamoDB Component
:doctitle: AWS DynamoDB
:shortname: aws2-ddb
:artifactid: camel-aws2-ddb
:description: Store and retrieve data from AWS DynamoDB service using AWS SDK version 2.x.
:since: 3.1
:supportlevel: Stable
:component-header: Only producer is supported
//Manually maintained attributes
:group: AWS
:camel-spring-boot-name: aws2-ddb

*Since Camel {since}*

*{component-header}*

The AWS2 DynamoDB component supports storing and retrieving data from/to
https://aws.amazon.com/dynamodb[Amazon's DynamoDB] service.

Prerequisites

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


== URI Format

------------------------------
aws2-ddb://domainName[?options]
------------------------------

You can append query options to the URI in the following format,
?options=value&option2=value&...


// 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 DDB component options

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

== 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 DDB producer

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

|`CamelAwsDdbBatchItems` |`Map<String, KeysAndAttributes>` |A map of the table name and corresponding items to get by primary key.

|`CamelAwsDdbTableName` |`String` |Table Name for this operation.

|`CamelAwsDdbKey` |`Key` |The primary key that uniquely identifies each item in a table.

|`CamelAwsDdbReturnValues` |`String` |Use this parameter if you want to get the attribute name-value pairs
before or after they are modified(NONE, ALL_OLD, UPDATED_OLD, ALL_NEW,
UPDATED_NEW).

|`CamelAwsDdbUpdateCondition` |`Map<String, ExpectedAttributeValue>` |Designates an attribute for a conditional modification.

|`CamelAwsDdbAttributeNames` |`Collection<String>` |If attribute names are not specified then all attributes will be
returned.

|`CamelAwsDdbConsistentRead` |`Boolean` |If set to true, then a consistent read is issued, otherwise eventually
consistent is used.

|`CamelAwsDdbIndexName` |`String` |If set will be used as Secondary Index for Query operation.

|`CamelAwsDdbItem` |`Map<String, AttributeValue>` |A map of the attributes for the item, and must include the primary key
values that define the item.

|`CamelAwsDdbExactCount` |`Boolean` |If set to true, Amazon DynamoDB returns a total number of items that
match the query parameters, instead of a list of the matching items and
their attributes.

|`CamelAwsDdbKeyConditions` |`Map<String, Condition>` |This header specify the selection criteria for the
query, and merge together the two old headers *CamelAwsDdbHashKeyValue*
and *CamelAwsDdbScanRangeKeyCondition*

|`CamelAwsDdbStartKey` |`Key` |Primary key of the item from which to continue an earlier query.

|`CamelAwsDdbHashKeyValue` |`AttributeValue` |Value of the hash component of the composite primary key.

|`CamelAwsDdbLimit` |`Integer` |The maximum number of items to return.

|`CamelAwsDdbScanRangeKeyCondition` |`Condition` |A container for the attribute values and comparison operators to use for
the query.

|`CamelAwsDdbScanIndexForward` |`Boolean` |Specifies forward or backward traversal of the index.

|`CamelAwsDdbScanFilter` |`Map<String, Condition>` |Evaluates the scan results and returns only the desired values.

|`CamelAwsDdbUpdateValues` |`Map<String, AttributeValueUpdate>` |Map of attribute name to the new value and action for the update.
|=======================================================================

=== Message headers set during BatchGetItems operation

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

|`CamelAwsDdbBatchResponse` |`Map<String,BatchResponse>` |Table names and the respective item attributes from the tables.

|`CamelAwsDdbUnprocessedKeys` |`Map<String,KeysAndAttributes>` |Contains a map of tables and their respective keys that were not
processed with the current response.
|=======================================================================

=== Message headers set during DeleteItem operation

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

|`CamelAwsDdbAttributes` |`Map<String, AttributeValue>` |The list of attributes returned by the operation.
|=======================================================================

=== Message headers set during DeleteTable operation

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

|`CamelAwsDdbProvisionedThroughput`| | 

|`ProvisionedThroughputDescription` | |The value of the ProvisionedThroughput property for this table

|`CamelAwsDdbCreationDate` |`Date` |Creation DateTime of this table.

|`CamelAwsDdbTableItemCount` |`Long` |Item count for this table.

|`CamelAwsDdbKeySchema` |`KeySchema` |The KeySchema that identifies the primary key for this table. 
*From Camel 2.16.0 the type of this header is List<KeySchemaElement> and not KeySchema*

|`CamelAwsDdbTableName` |`String` |The table name. 

|`CamelAwsDdbTableSize` |`Long` |The table size in bytes. 

|`CamelAwsDdbTableStatus` |`String` |The status of the table: CREATING, UPDATING, DELETING, ACTIVE
|=======================================================================

=== Message headers set during DescribeTable operation

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

|`CamelAwsDdbProvisionedThroughput` |{\{ProvisionedThroughputDescription}} |The value of the ProvisionedThroughput property for this table

|`CamelAwsDdbCreationDate` |`Date` |Creation DateTime of this table.

|`CamelAwsDdbTableItemCount` |`Long` |Item count for this table.

|`CamelAwsDdbKeySchema` |{\{KeySchema}} |The KeySchema that identifies the primary key for this table.


|`CamelAwsDdbTableName` |`String` |The table name.

|`CamelAwsDdbTableSize` |`Long` |The table size in bytes.

|`CamelAwsDdbTableStatus` |`String` |The status of the table: CREATING, UPDATING, DELETING, ACTIVE

|`CamelAwsDdbReadCapacity` |`Long` |ReadCapacityUnits property of this table.

|`CamelAwsDdbWriteCapacity` |`Long` |WriteCapacityUnits property of this table.
|=======================================================================

=== Message headers set during GetItem operation

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

|`CamelAwsDdbAttributes` |`Map<String, AttributeValue>` |The list of attributes returned by the operation.

|=======================================================================

=== Message headers set during PutItem operation

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

|`CamelAwsDdbAttributes` |`Map<String, AttributeValue>` |The list of attributes returned by the operation.

|=======================================================================

=== Message headers set during Query operation

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

|`CamelAwsDdbItems` |`List<java.util.Map<String,AttributeValue>>` |The list of attributes returned by the operation.

|`CamelAwsDdbLastEvaluatedKey` |`Key` |Primary key of the item where the query operation stopped, inclusive of
the previous result set.

|`CamelAwsDdbConsumedCapacity` |`Double` |The number of Capacity Units of the provisioned throughput of the table
consumed during the operation.

|`CamelAwsDdbCount` |`Integer` |Number of items in the response.
|=======================================================================

=== Message headers set during Scan operation

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

|`CamelAwsDdbItems` |`List<java.util.Map<String,AttributeValue>>` |The list of attributes returned by the operation.

|`CamelAwsDdbLastEvaluatedKey` |`Key` |Primary key of the item where the query operation stopped, inclusive of
the previous result set.

|`CamelAwsDdbConsumedCapacity` |`Double` |The number of Capacity Units of the provisioned throughput of the table
consumed during the operation.

|`CamelAwsDdbCount` |`Integer` |Number of items in the response.

|`CamelAwsDdbScannedCount` |`Integer` |Number of items in the complete scan before any filters are applied.
|=======================================================================

=== Message headers set during UpdateItem operation

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

|`CamelAwsDdbAttributes` |`Map<String, AttributeValue>` |The list of attributes returned by the operation.

|=======================================================================

=== Advanced AmazonDynamoDB configuration

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

[source,java]
----------------------------------------------------
from("direct:start")
.to("aws2-ddb://domainName?amazonDDBClient=#client");
----------------------------------------------------

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

== Supported producer operations

- BatchGetItems
- DeleteItem
- DeleteTable
- DescribeTable
- GetItem
- PutItem
- Query
- Scan
- UpdateItem
- UpdateTable

== Dependencies

== Examples

=== Producer Examples

- PutItem: this operation will create an entry into DynamoDB

[source,java]
--------------------------------------------------------------------------------
from("direct:start")
  .setHeader(Ddb2Constants.OPERATION, Ddb2Operations.PutItem)
  .setHeader(Ddb2Constants.CONSISTENT_READ, "true")
  .setHeader(Ddb2Constants.RETURN_VALUES, "ALL_OLD")
  .setHeader(Ddb2Constants.ITEM, attributeMap)
  .setHeader(Ddb2Constants.ATTRIBUTE_NAMES, attributeMap.keySet());
  .to("aws2-ddb://" + tableName + "?keyAttributeName=" + attributeName + "&keyAttributeType=" + KeyType.HASH
  + "&keyScalarType=" + ScalarAttributeType.S
  + "&readCapacity=1&writeCapacity=1");
--------------------------------------------------------------------------------

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[]
