docs/components/modules/ROOT/pages/nitrite-component.adoc

[[nitrite-component]]
= Nitrite Component
//THIS FILE IS COPIED: EDIT THE SOURCE FILE:
:page-source: components/camel-nitrite/src/main/docs/nitrite-component.adoc
:docTitle: Nitrite
:artifactId: camel-nitrite
:description: Access Nitrite databases.
:since: 3.0
:supportLevel: Stable
:component-header: Both producer and consumer are supported

*Since Camel {since}*

*{component-header}*

Nitrite component is used to access https://github.com/dizitart/nitrite-database[Nitrite NoSQL database]

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-nitrite</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>
----

== Options

// component options: START
The Nitrite component supports 3 options, which are listed below.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *bridgeErrorHandler* (consumer) | Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. | false | boolean
| *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean
| *basicPropertyBinding* (advanced) | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean
|===
// component options: END

// endpoint options: START
The Nitrite endpoint is configured using URI syntax:

----
nitrite:database
----

with the following path and query parameters:

=== Path Parameters (1 parameters):


[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *database* | *Required* Path to database file. Will be created if not exists. |  | String
|===


=== Query Parameters (11 parameters):


[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *collection* (common) | Name of Nitrite collection. Cannot be used in combination with repositoryClass option. |  | String
| *repositoryClass* (common) | Class of Nitrite ObjectRepository. Cannot be used in combination with collection option. |  | Class
| *repositoryName* (common) | Optional name of ObjectRepository. Can be only used in combination with repositoryClass, otherwise have no effect |  | String
| *bridgeErrorHandler* (consumer) | Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. | false | boolean
| *exceptionHandler* (consumer) | To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this option is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored. |  | ExceptionHandler
| *exchangePattern* (consumer) | Sets the exchange pattern when the consumer creates an exchange. The value can be one of: InOnly, InOut, InOptionalOut |  | ExchangePattern
| *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean
| *basicPropertyBinding* (advanced) | Whether the endpoint should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean
| *synchronous* (advanced) | Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported). | false | boolean
| *password* (security) | Password for Nitrite database. Required, if option username specified. |  | String
| *username* (security) | Username for Nitrite database. Database is not secured if option not specified. |  | String
|===
// endpoint options: END



== Message headers

=== Consumer headers

The following headers are available when consuming from Nitrite.
[width="100%",cols="2m,2m,1m,5",options="header"]
|===
| Header constant | Header value | Type | Description
| NitriteConstants.CHANGE_TIMESTAMP | "CamelNitriteChangeTimestamp" | Long | Event timestamp in Epoch millis
| NitriteConstants.CHANGE_TYPE | "CamelNitriteChangeType" | org.dizitart.no2.event.ChangeType | Type of event
|===

=== Producer headers

The following headers are available when producing to Nitrite.
[width="100%",cols="2m,2m,1m,5",options="header"]
|===
| Header constant | Header value | Type | Description
| NitriteConstants.OPERATION | "CamelNitriteOperation" | AbstractNitriteOperation | Operation to invoke on Collection or Repository. Defaults to `UpsertOperation` if not specified
| NitriteConstants.WRITE_RESULT | "CamelNitriteWriteResult" | org.dizitart.no2.WriteResult | Result of data modifying operation
|===

== Producer operations
The following Operations are available to specify as NitriteConstants.OPERATION when producing to Nitrite.
[width="100%",cols="2m,2m,1m,5",options="header"]
|===
| Class | Type | Parameters | Description
| FindCollectionOperation | collection | Filter(optional), FindOptions(optional) | Find Documents in collection by Filter. If not specified, returns all documents
| RemoveCollectionOperation | collection | Filter(required), RemoveOptions(optional) | Remove documents matching Filter
| UpdateCollectionOperation | collection | Filter(required), UpdateOptions(optional), Document(optional) | Update documents matching Filter. If Document not specified, the message body is used
| CreateIndexOperation | common | field:String(required), IndexOptions(required) | Create index with IndexOptions on field
| DropIndexOperation | common | field:String(required) | Drop index on field
| ExportDatabaseOperation | common | ExportOptions(optional) | Export full database to JSON and stores result in body - see Nitrite docs for details about format
| GetAttributesOperation | common | | Get attributes of collection
| GetByIdOperation | common | NitriteId | Get Document by _id
| ImportDatabaseOperation | common | | Import full database from JSON in body
| InsertOperation | common | payload(optional) | Insert document to collection or object to ObjectRepository. If parameter not specified, inserts message body
| ListIndicesOperation | common | | List indexes in collection and stores `List<Index>` in message body
| RebuildIndexOperation | common | field (required), async (optional) | Rebuild existing index on field
| UpdateOperation | common | payload(optional) | Update document in collection or object in ObjectRepository. If parameter not specified, updates document from message body
| UpsertOperation | common | payload(optional) | Upsert (Insert or Update) document in collection or object in ObjectRepository. If parameter not specified, updates document from message body
| FindRepositoryOperation | repository | ObjectFilter(optional), FindOptions(optional) | Find objects in ObjectRepository by ObjectFilter. If not specified, returns all objects in repository
| RemoveRepositoryOperation | repository | ObjectFilter(required), RepoveOptions(optional) | Remove objects in ObjectRepository matched by ObjectFilter
| UpdateRepositoryOperation | repository | ObjectFilter(required), UpdateOptions(optional), payload(optional) | Update objects matching ObjectFilter. If payload not specified, the message body is used
|===

== Examples

=== Consume changes in collection.

[source,java]
----
from("nitrite:/path/to/database.db?collection=myCollection")
    .to("log:change")
----

=== Consume changes in object repository.

[source,java]
----
from("nitrite:/path/to/database.db?repositoryClass=my.project.MyPersistentObject")
    .to("log:change")
----

[source,java]
----
package my.project;

@Indices({
        @Index(value = "key1", type = IndexType.NonUnique)
})
public class MyPersistentObject {
    @Id
    private long id;
    private String key1;
    // Getters, setters
}
----

=== Insert or update document

[source,java]
----
from("direct:upsert")
    .setBody(constant(Document.createDocument("key1", "val1")))
    .to("nitrite:/path/to/database.db?collection=myCollection")
----

=== Get Document by id

[source,java]
----
from("direct:getByID")
    .setHeader(NitriteConstants.OPERATION, () -> new GetByIdOperation(NitriteId.createId(123L)))
    .to("nitrite:/path/to/database.db?collection=myCollection")
    .to("log:result")
----

=== Find Document in collection

[source,java]
----
from("direct:getByID")
    .setHeader(NitriteConstants.OPERATION, () -> new FindCollectionOperation(Filters.eq("myKey", "withValue")))
    .to("nitrite:/path/to/database.db?collection=myCollection")
    .to("log:result");
----

include::camel-spring-boot::page$nitrite-starter.adoc[]