= AWS Kinesis Component
:doctitle: AWS Kinesis
:shortname: aws2-kinesis
:artifactid: camel-aws2-kinesis
:description: Consume and produce records from and to AWS Kinesis Streams using AWS SDK version 2.x.
:since: 3.2
:supportlevel: Stable
:component-header: Both producer and consumer are supported
//Manually maintained attributes
:group: AWS
:camel-spring-boot-name: aws2-kinesis

*Since Camel {since}*

*{component-header}*

The AWS2 Kinesis component supports receiving messages from and sending messages to Amazon Kinesis (no Batch supported)
service.

Prerequisites

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


== URI Format

-----------------------------------
aws2-kinesis://stream-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-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 Kinesis component options

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

== Batch Consumer

This component implements the Batch Consumer.

This allows you for instance to know how many messages exists in this
batch and for instance let the Aggregator
aggregate this number of messages.

== 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 set by the Kinesis consumer

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

|`CamelAwsKinesisSequenceNumber` |`String` |The sequence number of the record. This is represented as a String as it
size is not defined by the API. If it is to be used as a numerical type then use

|`CamelAwsKinesisApproximateArrivalTimestamp` |`String` |The time AWS assigned as the arrival time of the record.

|`CamelAwsKinesisPartitionKey` |`String` |Identifies which shard in the stream the data record is assigned to.
|=======================================================================

=== AmazonKinesis configuration

You then have to reference the KinesisClient in the `amazonKinesisClient` URI option.

[source,java]
--------------------------------------------------------------------------------------------------------------------
from("aws2-kinesis://mykinesisstream?amazonKinesisClient=#kinesisClient")
  .to("log:out?showAll=true");
--------------------------------------------------------------------------------------------------------------------

=== Providing AWS Credentials

It is recommended that the credentials are obtained by using the
http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/DefaultAWSCredentialsProviderChain.html[DefaultAWSCredentialsProviderChain]
that is the default when creating a new ClientConfiguration instance,
however, a
different http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/AWSCredentialsProvider.html[AWSCredentialsProvider]
can be specified when calling createClient(...).

=== Message headers used by the Kinesis producer to write to Kinesis.  The producer expects that the message body is a `byte[]`.

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

|`CamelAwsKinesisPartitionKey` |`String` |The PartitionKey to pass to Kinesis to store this record.

|`CamelAwsKinesisSequenceNumber` |`String` |Optional paramter to indicate the sequence number of this record.

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

=== Message headers set by the Kinesis producer on successful storage of a Record

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

|`CamelAwsKinesisSequenceNumber` |`String` |The sequence number of the record, as defined in
http://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html#API_PutRecord_ResponseSyntax[Response Syntax]

|`CamelAwsKinesisShardId` |`String` |The shard ID of where the Record was stored


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

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

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



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