components/camel-couchdb/src/main/docs/couchdb-component.adoc

= CouchDB Component
:doctitle: CouchDB
:shortname: couchdb
:artifactid: camel-couchdb
:description: Consume changesets for inserts, updates and deletes in a CouchDB database, as well as get, save, update and delete documents from a CouchDB database.
:since: 2.11
:supportlevel: Stable
:tabs-sync-option:
:component-header: Both producer and consumer are supported
//Manually maintained attributes
:camel-spring-boot-name: couchdb

*Since Camel {since}*

*{component-header}*

The *couchdb:* component allows you to treat
http://couchdb.apache.org/[CouchDB] instances as a producer or consumer
of messages. Using the lightweight LightCouch API, this camel component
has the following features:

* As a consumer, monitors couch changesets for inserts, updates and
deletes and publishes these as messages into camel routes.
* As a producer, can save, update, delete (by using CouchDbMethod with DELETE value)
documents and get documents by id (by using CouchDbMethod with GET value) into couch.
* Can support as many endpoints as required, eg for multiple databases
across multiple instances.
* Ability to have events trigger for only deletes, only inserts/updates
or all (default).
* Headers set for sequenceId, document revision, document id, and HTTP
method type.

NOTE: CouchDB 3.x is not supported.

Maven users will need to add the following dependency to their `pom.xml`
for this component:

[source,xml]
------------------------------------------------------------
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-couchdb</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>
------------------------------------------------------------

== URI format

-------------------------------------------------
couchdb:http://hostname[:port]/database?[options]
-------------------------------------------------

Where *hostname* is the hostname of the running couchdb instance. Port
is optional and if not specified then defaults to 5984.


// 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

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

Headers are set by the consumer once the message is received. The
producer will also set the headers for downstream processors once the
insert/update has taken place. Any headers set prior to the producer are
ignored. That means for example, if you set CouchDbId as a header, it
will not be used as the id for insertion, the id of the document will
still be used.

== Message Body

The component will use the message body as the document to be inserted.
If the body is an instance of String, then it will be marshalled into a
GSON object before insert. This means that the string must be valid JSON
or the insert / update will fail. If the body is an instance of a
com.google.gson.JsonElement then it will be inserted as is. Otherwise
the producer will throw an exception of unsupported body type.

NOTE: To update a CouchDB document, it's _id and _rev field must be part of the json payload routed to CouchDB by Camel.

== Samples

For example if you wish to consume all inserts, updates and deletes from
a CouchDB instance running locally, on port 9999 then you could use the
following:

[source,java]
-------------------------------------------------------------
from("couchdb:http://localhost:9999").process(someProcessor);
-------------------------------------------------------------

If you were only interested in deletes, then you could use the following

[source,java]
---------------------------------------------------------------------------
from("couchdb:http://localhost:9999?updates=false").process(someProcessor);
---------------------------------------------------------------------------

If you wanted to insert a message as a document, then the body of the
exchange is used

[source,java]
----------------------------------------------------------------------------------------
from("someProducingEndpoint").process(someProcessor).to("couchdb:http://localhost:9999")
----------------------------------------------------------------------------------------

To start tracking the changes immediately after an update sequence, implement a custom resume strategy. To do so, it is necessary to implement a CouchDbResumeStrategy and use the resumable to set the last (update) offset to start tracking the changes:

```
public class CustomSequenceResumeStrategy implements CouchDbResumeStrategy {
    @Override
    public void resume(CouchDbResumable resumable) {
        resumable.setLastOffset("custom-last-update");
    }
}
```


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