[[Dropbox-CamelDropboxcomponent]]
Camel Dropbox component
~~~~~~~~~~~~~~~~~~~~~~~

*Available as of Camel 2.14*

The *dropbox:* component allows you to treat
https://www.dropbox.com[Dropbox] remote folders as a producer or
consumer of messages. Using the
http://dropbox.github.io/dropbox-sdk-java/api-docs/v1.7.x/[Dropbox Java
Core API] (reference version for this component is 1.7.x), this camel
component has the following features:

* As a consumer, download files and search files by queries
* As a producer, download files, move files between remote directories,
delete files/dir, upload files and search files by queries

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

[[Dropbox-URIformat]]
URI format
^^^^^^^^^^

[source,java]
-------------------------------
dropbox://[operation]?[options]
-------------------------------

Where *operation* is the specific action (typically is a CRUD action) to
perform on Dropbox remote folder.

[[Dropbox-Operations]]
Operations
^^^^^^^^^^

[width="100%",cols="40%,60%",options="header",]
|=======================================================================
|Operation |Description

|`del` |deletes files or directories on Dropbox

|`get` |download files from Dropbox

|`move` |move files from folders on Dropbox

|`put` |upload files on Dropbox

|`search` |search files on Dropbox based on string queries
|=======================================================================

*Operations* require additional options to work, some are mandatory for
the specific operation.

[[Dropbox-Options]]
Options
^^^^^^^

In order to work with Dropbox API you need to obtain an *accessToken*
and a *clientIdentifier.* +
You can refer to the
https://www.dropbox.com/developers/core/start/java[Dropbox
documentation] that expalins how to get them.  

Below are listed the mandatory options for all operations:

[width="100%",cols="20%,20%,60%",options="header",]
|=======================================================================
|Property |Mandatory |Description

|`accessToken` |`true` |The access token to make API requests for a specific Dropbox user

|`clientIdentifier` |`true` |Name of the app registered to make API requests
|=======================================================================

[[Dropbox-Deloperation]]
Del operation
^^^^^^^^^^^^^

Delete files on Dropbox.

Works only as Camel producer.

Below are listed the options for this operation:

[width="100%",cols="20%,20%,60%",options="header",]
|=======================================================================
|Property |Mandatory |Description

|`remotePath` |`true` |Folder or file to delete on Dropbox
|=======================================================================

[[Dropbox-Samples]]
Samples
+++++++

[source,java]
-------------------------------
from("direct:start").to("dropbox://del?accessToken=XXX&clientIdentifier=XXX&remotePath=/root/folder1").to("mock:result");

from("direct:start").to("dropbox://del?accessToken=XXX&clientIdentifier=XXX&remotePath=/root/folder1/file1.tar.gz").to("mock:result");
-------------------------------

[[Dropbox-ResultMessageHeaders]]
Result Message Headers
++++++++++++++++++++++

The following headers are set on message result:

[width="100%",cols="50%,50%",options="header",]
|=======================================================================
|Property |Value

|`DELETED_PATH` |name of the path deleted on dropbox
|=======================================================================

[[Dropbox-ResultMessageBody]]
Result Message Body
+++++++++++++++++++

The following objects are set on message body result:

[width="100%",cols="50%,50%",options="header",]
|=======================================================================
|Object type |Description

|`String` |name of the path deleted on dropbox
|=======================================================================

[[Dropbox-Getoperation]]
Get (download) operation
^^^^^^^^^^^^^^^^^^^^^^^^

Download files from Dropbox.

Works as Camel producer or Camel consumer.

Below are listed the options for this operation:

[width="100%",cols="20%,20%,60%",options="header",]
|=======================================================================
|Property |Mandatory |Description

|`remotePath` |`true` |Folder or file to download from Dropbox
|=======================================================================

[[Dropbox-Samples.1]]
Samples
+++++++

[source,java]
-------------------------------
from("direct:start").to("dropbox://get?accessToken=XXX&clientIdentifier=XXX&remotePath=/root/folder1/file1.tar.gz").to("file:///home/kermit/?fileName=file1.tar.gz");

from("direct:start").to("dropbox://get?accessToken=XXX&clientIdentifier=XXX&remotePath=/root/folder1").to("mock:result");

from("dropbox://get?accessToken=XXX&clientIdentifier=XXX&remotePath=/root/folder1").to("file:///home/kermit/");
-------------------------------

[[Dropbox-ResultMessageHeaders.1]]
Result Message Headers
++++++++++++++++++++++

The following headers are set on message result:

[width="100%",cols="50%,50%",options="header",]
|=======================================================================
|Property |Value

|`DOWNLOADED_FILE` |in case of single file download, path of the remote file downloaded

|`DOWNLOADED_FILES` |in case of multiple files download, path of the remote files downloaded
|=======================================================================

[[Dropbox-ResultMessageBody.1]]
Result Message Body
+++++++++++++++++++

The following objects are set on message body result:

[width="100%",cols="50%,50%",options="header",]
|=======================================================================
|Object type |Description

|`ByteArrayOutputStream` |in case of single file download, stream representing the file downloaded

|`Map<String, ByteArrayOutputStream>` |in case of multiple files download, a map with as key the path of the
remote file downloaded and as value the stream representing the file
downloaded
|=======================================================================

[[Dropbox-Moveoperation]]
Move operation
^^^^^^^^^^^^^^

Move files on Dropbox between one folder to another.

Works only as Camel producer.

Below are listed the options for this operation:

[width="100%",cols="20%,20%,60%",options="header",]
|=======================================================================
|Property |Mandatory |Description

|`remotePath` |`true` |Original file or folder to move

|`newRemotePath` |`true` |Destination file or folder
|=======================================================================

[[Dropbox-Samples.2]]
Samples
+++++++

[source,java]
-------------------------------
from("direct:start").to("dropbox://move?accessToken=XXX&clientIdentifier=XXX&remotePath=/root/folder1&newRemotePath=/root/folder2").to("mock:result");
-------------------------------

[[Dropbox-ResultMessageHeaders.2]]
Result Message Headers
++++++++++++++++++++++

The following headers are set on message result:

[width="100%",cols="50%,50%",options="header",]
|=======================================================================
|Property |Value

|`MOVED_PATH` |name of the path moved on dropbox
|=======================================================================

[[Dropbox-ResultMessageBody.2]]
Result Message Body
+++++++++++++++++++

The following objects are set on message body result:

[width="100%",cols="50%,50%",options="header",]
|=======================================================================
|Object type |Description

|`String` |name of the path moved on dropbox
|=======================================================================

[[Dropbox-Putoperation]]
Put (upload) operation
^^^^^^^^^^^^^^^^^^^^^^

Upload files on Dropbox.

Works as Camel producer.

Below are listed the options for this operation:

[width="100%",cols="20%,20%,60%",options="header",]
|=======================================================================
|Property |Mandatory |Description

|`uploadMode` |`true` |add or force this option specifies how a file should be saved on
dropbox: in case of "add" the new file will be renamed if a file with the same
name already exists on dropbox. In case of "force" if a file with the same name already exists on
dropbox, this will be overwritten.

|`localPath` |`true` |Folder or file to upload on Dropbox from the local filesystem .

|`remotePath` |`false` |Folder destination on Dropbox. If the property is not set, the component
will upload the file on a remote path equal to the local path.
|=======================================================================

[[Dropbox-Samples.3]]
Samples
+++++++

[source,java]
-------------------------------
from("direct:start").to("dropbox://put?accessToken=XXX&clientIdentifier=XXX&uploadMode=add&localPath=/root/folder1").to("mock:result");

from("direct:start").to("dropbox://put?accessToken=XXX&clientIdentifier=XXX&uploadMode=add&localPath=/root/folder1&remotePath=/root/folder2").to("mock:result");
-------------------------------

[[Dropbox-ResultMessageHeaders.3]]
Result Message Headers
++++++++++++++++++++++

The following headers are set on message result:

[width="100%",cols="50%,50%",options="header",]
|=======================================================================
|Property |Value

|`UPLOADED_FILE` |in case of single file upload, path of the remote path uploaded

|`UPLOADED_FILES` |in case of multiple files upload, string with the remote paths uploaded
|=======================================================================

[[Dropbox-ResultMessageBody.3]]
Result Message Body
+++++++++++++++++++

The following objects are set on message body result:

[width="100%",cols="50%,50%",options="header",]
|=======================================================================
|Object type |Description

|`String` |in case of single file upload, result of the upload operation, OK or KO

|`Map<String, DropboxResultCode>` |in case of multiple files upload, a map with as key the path of the
remote file uploaded and as value the result of the upload operation, OK
or KO
|=======================================================================

[[Dropbox-Searchoperation]]
Search operation
^^^^^^^^^^^^^^^^

Search inside a remote Dropbox folder including its sub directories.

Works as Camel producer and as Camel consumer.

Below are listed the options for this operation:

[width="100%",cols="20%,20%,60%",options="header",]
|=======================================================================
|Property |Mandatory |Description

|`remotePath` |`true` |Folder on Dropbox where to search in.

|`query` |`false` |A space-separated list of substrings to search for. A file matches only
if it contains all the substrings. If this option is not set, all files
will be matched.
|=======================================================================

[[Dropbox-Samples.4]]
Samples
+++++++

[source,java]
-------------------------------
from("dropbox://search?accessToken=XXX&clientIdentifier=XXX&remotePath=/XXX&query=XXX").to("mock:result");

from("direct:start").to("dropbox://search?accessToken=XXX&clientIdentifier=XXX&remotePath=/XXX").to("mock:result");
-------------------------------

[[Dropbox-ResultMessageHeaders.4]]
Result Message Headers
++++++++++++++++++++++

The following headers are set on message result:

[width="100%",cols="50%,50%",options="header",]
|=======================================================================
|Property |Value

|`FOUNDED_FILES` |list of file path founded
|=======================================================================

[[Dropbox-ResultMessageBody.4]]
Result Message Body
+++++++++++++++++++

The following objects are set on message body result:

[width="100%",cols="50%,50%",options="header",]
|=======================================================================
|Object type |Description

|`List<DbxEntry>` |list of file path founded. For more information on this object refer to
Dropbox documentation,
|=======================================================================

link:http://dropbox.github.io/dropbox-sdk-java/api-docs/v1.7.x/com/dropbox/core/DbxEntry.html[http://dropbox.github.io/dropbox-sdk-java/api-docs/v1.7.x/com/dropbox/core/DbxEntry.html]

 
