[[Box-BoxComponent]]
Box Component
~~~~~~~~~~~~~

*Available as of Camel 2.14*

The Box component provides access to all of the Box.com APIs accessible
using https://github.com/box/box-java-sdk-v2/[box-java-sdk-v2]. It
allows producing messages to upload and download files, create, edit,
and manage folders, etc. It also supports APIs that allow polling for
updates to user accounts and even changes to enterprise accounts, etc.

Box.com requires the use of OAuth2.0 for all client application
authentication. In order to use camel-box with your account, you'll need
to create a new application within Box.com at
https://app.box.com/developers/services/edit/[https://app.box.com/developers/services/edit/].
The Box application's client id and secret will allow access to Box APIs
which require a current user. A user access token is generated and
managed by the API for an end user. Alternatively the Camel application
can register an implementation
of com.box.boxjavalibv2.authorization.IAuthSecureStorage to provide
an com.box.boxjavalibv2.dao.IAuthData OAuth token.

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

[source,java]
-------------------------------------------
    <dependency>
        <groupId>org.apache.camel</groupId>
        <artifactId>camel-box</artifactId>
        <version>${camel-version}</version>
    </dependency>
-------------------------------------------

[[Box-URIformat]]
URI format
^^^^^^^^^^

[source,java]
--------------------------------------------
    box://endpoint-prefix/endpoint?[options]
--------------------------------------------

Endpoint prefix can be one of:

* collaborations
* comments
* events
* files
* folders
* groups
* poll-events
* search
* shared-comments
* shared-files
* shared-folders
* shared-items
* users

[[Box-BoxComponent.1]]
BoxComponent
^^^^^^^^^^^^

The Box Component can be configured with the options below. These
options can be provided using the component's bean
property *`configuration`* of
type *`org.apache.camel.component.box.BoxConfiguration`*. These options
can also be specified in the endpoint URI. 

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

|authSecureStorage |com.box.boxjavalibv2.authorization.IAuthSecureStorage |OAuth Secure Storage callback, can be used to provide and or save OAuth
tokens. The callback may return null on first call to allow the
component to login and authorize application and obtain an OAuth token,
which can then be saved in the secure storage. For the component to be
able to create a token automatically a user password must be provided.

|boxConfig |com.box.boxjavalibv2.IBoxConfig |Custom Box SDK configuration, not required normally

|clientId |String |Box application client ID

|clientSecret |String |Box application client secret

|connectionManagerBuilder |com.box.boxjavalibv2.BoxConnectionManagerBuilder |Custom Box connection manager builder, used to override default settings
like max connections for underlying HttpClient.

|httpParams |java.util.Map |Custom HTTP params for settings like proxy host

|loginTimeout |int |amount of time the component will wait for a response from Box.com,
default is 30 seconds

|refreshListener |com.box.boxjavalibv2.authorization.OAuthRefreshListener |OAuth listener for token updates, if the Camel application needs to use
the access token outside the route

|revokeOnShutdown |boolean |Flag to revoke OAuth refresh token on route shutdown, default false.
Will require a fresh refresh token on restart using either a custom
IAuthSecureStorage or automatic component login by providing a user
password

|sharedLink |String |Box shared link for shared-* endpoints, can be a link for a shared
comment, file or folder

|sharedPassword |String |Password associated with the shared link, MUST be provided with
sharedLink

|userName |String |Box user name, MUST be provided

|userPassword |String |Box user password, MUST be provided if authSecureStorage is not set, or
returns null on first call
|=======================================================================

[[Box-ProducerEndpoints:]]
Producer Endpoints:
^^^^^^^^^^^^^^^^^^^

Producer endpoints can use endpoint prefixes followed by endpoint names
and associated options described next. A shorthand alias can be used for
some endpoints. The endpoint URI MUST contain a prefix.

Endpoint options that are not mandatory are denoted by *[]*. When there
are no mandatory options for an endpoint, one of the set of *[]* options
MUST be provided. Producer endpoints can also use a special
option *`inBody`* that in turn should contain the name of the endpoint
option whose value will be contained in the Camel Exchange In message.

Any of the endpoint options can be provided in either the endpoint URI,
or dynamically in a message header. The message header name must be of
the format *`CamelBox.<option>`*. Note that the *`inBody`* option
overrides message header, i.e. the endpoint
option *`inBody=option`* would override a *`CamelBox.option`* header.

If a value is not provided for the option *defaultRequest* either in the
endpoint URI or in a message header, it will be assumed to be `null`.
Note that the `null` value will only be used if other options do not
satisfy matching endpoints.

In case of Box API errors the endpoint will throw a
RuntimeCamelException with a
*com.box.restclientv2.exceptions.BoxSDKException* derived exception
cause.

[[Box-EndpointPrefixcollaborations]]
Endpoint Prefix _collaborations_
++++++++++++++++++++++++++++++++

For more information on Box collaborations see
https://developers.box.com/docs/#collaborations[https://developers.box.com/docs/#collaborations]. The
following endpoints can be invoked with the prefix *`collaborations`* as
follows:

[source,java]
-------------------------------------------
    box://collaborations/endpoint?[options]
-------------------------------------------

[width="100%",cols="10%,10%,10%,70%",options="header",]
|=======================================================================
|Endpoint |Shorthand Alias |Options |Result Body Type

|createCollaboration |create |collabRequest, folderId |com.box.boxjavalibv2.dao.BoxCollaboration

|deleteCollaboration |delete |collabId, defaultRequest |

|getAllCollaborations |allCollaborations |getAllCollabsRequest |java.util.List

|getCollaboration |collaboration |collabId, defaultRequest |com.box.boxjavalibv2.dao.BoxCollaboration

|updateCollaboration |update |collabId, collabRequest |com.box.boxjavalibv2.dao.BoxCollaboration
|=======================================================================

[[Box-URIOptionsforcollaborations]]
URI Options for _collaborations_


[width="100%",cols="10%,90%",options="header",]
|=======================================================================
|Name |Type

|collabId |String

|collabRequest |com.box.boxjavalibv2.requests.requestobjects.BoxCollabRequestObject

|defaultRequest |com.box.restclientv2.requestsbase.BoxDefaultRequestObject

|folderId |String

|getAllCollabsRequest |com.box.boxjavalibv2.requests.requestobjects.BoxGetAllCollabsRequestObject
|=======================================================================

[[Box-EndpointPrefixevents]]
Endpoint Prefix _events_
++++++++++++++++++++++++

For more information on Box events see
https://developers.box.com/docs/#events[https://developers.box.com/docs/#events].
Although this endpoint can be used by producers, Box events are better
used as a consumer endpoint using the *poll-events* endpoint prefix. The
following endpoints can be invoked with the prefix *`events`* as
follows:

[source,java]
---------------------------------
  box://events/endpoint?[options]
---------------------------------

[width="100%",cols="10%,10%,10%,70%",options="header",]
|=======================================================================
|Endpoint |Shorthand Alias |Options |Result Body Type

|getEventOptions |eventOptions |defaultRequest |com.box.boxjavalibv2.dao.BoxCollection

|getEvents |events |eventRequest |com.box.boxjavalibv2.dao.BoxEventCollection
|=======================================================================

[[Box-URIOptionsforevents]]
URI Options for _events_

[width="100%",cols="10%,90%",options="header",]
|=======================================================================
|Name |Type

|defaultRequest |com.box.restclientv2.requestsbase.BoxDefaultRequestObject

|eventRequest |com.box.boxjavalibv2.requests.requestobjects.BoxEventRequestObject
|=======================================================================

[[Box-EndpointPrefixgroups]]
Endpoint Prefix _groups_
++++++++++++++++++++++++

For more information on Box groups see
https://developers.box.com/docs/#groups[https://developers.box.com/docs/#groups].
The following endpoints can be invoked with the prefix *`groups`* as
follows:

[source,java]
-----------------------------------
    box://groups/endpoint?[options]
-----------------------------------

[width="100%",cols="10%,10%,10%,70%",options="header",]
|=======================================================================
|Endpoint |Shorthand Alias |Options |Result Body Type

|createGroup |[groupRequest], [name] |com.box.boxjavalibv2.dao.BoxGroup 

|createMembership |[groupId, role, userId], [groupMembershipRequest] |com.box.boxjavalibv2.dao.BoxGroupMembership

|deleteGroup |delete |defaultRequest, groupId |

|deleteMembership |delete |defaultRequest, membershipId |

|getAllCollaborations |allCollaborations |defaultRequest, groupId |com.box.boxjavalibv2.dao.BoxCollection

|getAllGroups |allGroups |defaultRequest |com.box.boxjavalibv2.dao.BoxCollection

|getMembership |membership |defaultRequest, membershipId |com.box.boxjavalibv2.dao.BoxGroupMembership

|getMemberships |memberships |defaultRequest, groupId |com.box.boxjavalibv2.dao.BoxCollection

|updateGroup |update |groupId, groupRequest |com.box.boxjavalibv2.dao.BoxGroup

|updateMembership |update |[groupMembershipRequest], [role], membershipId |com.box.boxjavalibv2.dao.BoxGroupMembership
|=======================================================================

[[Box-URIOptionsforgroups]]
URI Options for _groups_

[width="100%",cols="10%,90%",options="header",]
|=======================================================================
|Name |Type

|defaultRequest |com.box.restclientv2.requestsbase.BoxDefaultRequestObject

|groupId |String

|groupMembershipRequest |com.box.boxjavalibv2.requests.requestobjects.BoxGroupMembershipRequestObject

|groupRequest |com.box.boxjavalibv2.requests.requestobjects.BoxGroupRequestObject

|membershipId |String

|name |String

|role |String

|userId |String

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

[[Box-EndpointPrefixsearch]]
Endpoint Prefix _search_
++++++++++++++++++++++++

For more information on Box search API see
https://developers.box.com/docs/#search[https://developers.box.com/docs/#search]. The
following endpoints can be invoked with the prefix *`search`* as
follows:

[source,java]
-----------------------------------
    box://search/endpoint?[options]
-----------------------------------

[width="100%",cols="10%,10%,10%,70%",options="header",]
|=======================================================================
|Endpoint |Shorthand Alias |Options |Result Body Type

|search |defaultRequest, searchQuery |com.box.boxjavalibv2.dao.BoxCollection
|=======================================================================

[[Box-URIOptionsforsearch]]
URI Options for _search_

[width="100%",cols="10%,90%",options="header",]
|=======================================================================
|Name |Type

|defaultRequest |com.box.restclientv2.requestsbase.BoxDefaultRequestObject

|searchQuery |String
|=======================================================================

[[Box-EndpointPrefixcommentsandshared-comments]]
Endpoint Prefix _comments_ and _shared-comments_
++++++++++++++++++++++++++++++++++++++++++++++++

For more information on Box comments see
https://developers.box.com/docs/#comments[https://developers.box.com/docs/#comments].
The following endpoints can be invoked with the prefix *comments*
or *`shared-comments`* as follows. The *shared-comments* prefix requires
*sharedLink* and *sharedPassword* properties. 

[source,java]
--------------------------------------------
    box://comments/endpoint?[options]
    box://shared-comments/endpoint?[options]
--------------------------------------------

[width="100%",cols="10%,10%,10%,70%",options="header",]
|=======================================================================
|Endpoint |Shorthand Alias |Options |Result Body Type

|addComment |[commentRequest], [commentedItemId, commentedItemType, message] | | com.box.boxjavalibv2.dao.BoxComment 

|deleteComment |delete |  |commentId, defaultRequest

|getComment |comment |commentId, defaultRequest |com.box.boxjavalibv2.dao.BoxComment

|updateComment |update |commentId, commentRequest |com.box.boxjavalibv2.dao.BoxComment
|=======================================================================

[[Box-URIOptionsforcommentsandshared-comments]]
URI Options for _comments_ and _shared-comments_

[width="100%",cols="10%,90%",options="header",]
|=======================================================================
|Name |Type

|commentId |String

|commentRequest |com.box.boxjavalibv2.requests.requestobjects.BoxCommentRequestObject

|commentedItemId |String

|commentedItemType |com.box.boxjavalibv2.dao.IBoxType

|defaultRequest |com.box.restclientv2.requestsbase.BoxDefaultRequestObject

|message |String
|=======================================================================

[[Box-EndpointPrefixfilesandshared-files]]
Endpoint Prefix _files_ and _shared-files_
++++++++++++++++++++++++++++++++++++++++++

For more information on Box files see
https://developers.box.com/docs/#files[https://developers.box.com/docs/#files].
The following endpoints can be invoked with the
prefix *`files`* or *`shared-files`* as follows. The
*`shared-files `*prefix requires *sharedLink* and *sharedPassword*
properties. 

[source,java]
----------------------------------------
   box://files/endpoint?[options]
   box://shared-files/endpoint?[options]
----------------------------------------

[width="100%",cols="10%,10%,10%,70%",options="header",]
|=======================================================================
|Endpoint |Shorthand Alias |Options |Result Body Type

|copyFile |  |fileId, itemCopyRequest |com.box.boxjavalibv2.dao.BoxFile

|createSharedLink |create |fileId, sharedLinkRequest |com.box.boxjavalibv2.dao.BoxFile

|deleteFile |  | defaultRequest, fileId |

|downloadFile |download |[destination, listener], [listener, outputStreams], defaultRequest,
fileId |java.io.InputStream

|downloadThumbnail |download |extension, fileId, imageRequest |java.io.InputStream

|getFile |file |defaultRequest, fileId |com.box.boxjavalibv2.dao.BoxFile 

|getFileComments |fileComments defaultRequest, fileId |com.box.boxjavalibv2.dao.BoxCollection

|getFileVersions |fileVersions |defaultRequest, fileId |java.util.List

|getPreview |preview |extension, fileId, imageRequest |com.box.boxjavalibv2.dao.BoxPreview

|getThumbnail |thumbnail |extension, fileId, imageRequest |com.box.boxjavalibv2.dao.BoxThumbnail

|updateFileInfo |update |fileId, fileRequest |com.box.boxjavalibv2.dao.BoxFile

|uploadFile |upload |fileUploadRequest |com.box.boxjavalibv2.dao.BoxFile

|uploadNewVersion |upload |fileId, fileUploadRequest |com.box.boxjavalibv2.dao.BoxFile
|=======================================================================

[[Box-URIOptionsforfilesandshared-files]]
URI Options for _files_ and _shared-files_

[width="100%",cols="10%,90%",options="header",]
|=======================================================================
|Name |Type

|defaultRequest |com.box.restclientv2.requestsbase.BoxDefaultRequestObject

|destination |java.io.File

|extension |String

|fileId |String

|fileRequest |com.box.boxjavalibv2.requests.requestobjects.BoxFileRequestObject

|fileUploadRequest |com.box.restclientv2.requestsbase.BoxFileUploadRequestObject

|imageRequest|com.box.boxjavalibv2.requests.requestobjects.BoxImageRequestObject 

|itemCopyRequest |com.box.boxjavalibv2.requests.requestobjects.BoxItemCopyRequestObject

|listener |com.box.boxjavalibv2.filetransfer.IFileTransferListener

|outputStreams |java.io.OutputStream[]

|sharedLinkRequest |com.box.boxjavalibv2.requests.requestobjects.BoxSharedLinkRequestObject
|=======================================================================

[[Box-EndpointPrefixfoldersandshared-folders]]
Endpoint Prefix _folders_ and _shared-folders_
++++++++++++++++++++++++++++++++++++++++++++++

For more information on Box folders see
https://developers.box.com/docs/#folders[https://developers.box.com/docs/#folders].
The following endpoints can be invoked with the prefix
*`folders`* or *`shared-folders`* as follows. The prefix
*shared-folders* requires *sharedLink* and *sharedPassword* properties. 

[source,java]
-------------------------------------------
    box://folders/endpoint?[options]
    box://shared-folders/endpoint?[options]
-------------------------------------------

[width="100%",cols="10%,10%,10%,70%",options="header",]
|=======================================================================
|Endpoint |Shorthand Alias |Options |Result Body Type

|copyFolder |  |folderId, itemCopyRequest |com.box.boxjavalibv2.dao.BoxFolder

|createFolder |create |folderRequest |com.box.boxjavalibv2.dao.BoxFolder

|createSharedLink |create |folderId, sharedLinkRequest|com.box.boxjavalibv2.dao.BoxFolder 

|deleteFolder |delete |folderDeleteRequest, folderId

|getFolder |folder |defaultRequest, folderId |com.box.boxjavalibv2.dao.BoxFolder

|getFolderCollaborations |folderCollaborations |defaultRequest, folderId |java.util.List

|getFolderItems |folderItems |folderId, pagingRequest |com.box.boxjavalibv2.dao.BoxCollection

|updateFolderInfo |update |folderId, folderRequest |com.box.boxjavalibv2.dao.BoxFolder
|=======================================================================

[[Box-URIOptionsforfoldersorshared-folders]]
URI Options for _folders_ or _shared-folders_

[width="100%",cols="10%,90%",options="header",]
|=======================================================================
|Name |Type

|defaultRequest |com.box.restclientv2.requestsbase.BoxDefaultRequestObject

|folderDeleteRequest |com.box.boxjavalibv2.requests.requestobjects.BoxFolderDeleteRequestObject

|folderId |String

|folderRequest |com.box.boxjavalibv2.requests.requestobjects.BoxFolderRequestObject

|itemCopyRequest |com.box.boxjavalibv2.requests.requestobjects.BoxItemCopyRequestObject

|pagingRequest |com.box.boxjavalibv2.requests.requestobjects.BoxPagingRequestObject

|sharedLinkRequest |com.box.boxjavalibv2.requests.requestobjects.BoxSharedLinkRequestObject
|=======================================================================

[[Box-EndpointPrefixshared-items]]
Endpoint Prefix _shared-items_
++++++++++++++++++++++++++++++

For more information on Box shared items see
https://developers.box.com/docs/#shared-items[https://developers.box.com/docs/#shared-items].
The following endpoints can be invoked with the
prefix *`shared-items`* as follows:

[source,java]
-----------------------------------------
    box://shared-items/endpoint?[options]
-----------------------------------------

[width="100%",cols="10%,10%,10%,70%",options="header",]
|=======================================================================
|Endpoint |Shorthand Alias |Options |Result Body Type

|getSharedItem |sharedItem |defaultRequest |com.box.boxjavalibv2.dao.BoxItem
|=======================================================================

[[Box-URIOptionsforshared-items]]
URI Options for _shared-items_

[width="100%",cols="10%,90%",options="header",]
|=======================================================================
|Name |Type

|defaultRequest |com.box.restclientv2.requestsbase.BoxDefaultRequestObject
|=======================================================================

[[Box-EndpointPrefixusers]]
Endpoint Prefix _users_
+++++++++++++++++++++++

For information on Box users see
https://developers.box.com/docs/#users[https://developers.box.com/docs/#users].
The following endpoints can be invoked with the prefix *`users`* as
follows:

[source,java]
----------------------------------
    box://users/endpoint?[options]
----------------------------------

[width="100%",cols="10%,10%,10%,70%",options="header",]
|=======================================================================
|Endpoint |Shorthand Alias |Options |Result Body Type

|addEmailAlias |  |emailAliasRequest, userId |com.box.boxjavalibv2.dao.BoxEmailAlias

|createEnterpriseUser |create |userRequest |com.box.boxjavalibv2.dao.BoxUser

|deleteEmailAlias |  |defaultRequest, emailId, userId |

deleteEnterpriseUser |  |userDeleteRequest, userId |

|getAllEnterpriseUser |allEnterpriseUser |defaultRequest, filterTerm |java.util.List

|getCurrentUser |currentUser |defaultRequest |com.box.boxjavalibv2.dao.BoxUser

|getEmailAliases |emailAliases |defaultRequest, userId |java.util.List

|moveFolderToAnotherUser |  | folderId, simpleUserRequest, userId |com.box.boxjavalibv2.dao.BoxFolder

|updateUserInformaiton |update |userId, userRequest |com.box.boxjavalibv2.dao.BoxUser

|updateUserPrimaryLogin |update |userId, userUpdateLoginRequest |com.box.boxjavalibv2.dao.BoxUser
|=======================================================================

[[Box-URIOptionsforusers]]
URI Options for _users_

[width="100%",cols="10%,90%",options="header",]
|=======================================================================
|Name |Type

|defaultRequest |com.box.restclientv2.requestsbase.BoxDefaultRequestObject

|emailAliasRequest |com.box.boxjavalibv2.requests.requestobjects.BoxEmailAliasRequestObject

|emailId |String

|filterTerm |String

|folderId |String

|simpleUserRequest |com.box.boxjavalibv2.requests.requestobjects.BoxSimpleUserRequestObject

|userDeleteRequest |com.box.boxjavalibv2.requests.requestobjects.BoxUserDeleteRequestObject

|userId |String

|userRequest |com.box.boxjavalibv2.requests.requestobjects.BoxUserRequestObject

|userUpdateLoginRequest |com.box.boxjavalibv2.requests.requestobjects.BoxUserUpdateLoginRequestObject
|=======================================================================

[[Box-ConsumerEndpoints:]]
Consumer Endpoints:
^^^^^^^^^^^^^^^^^^^

For more information on Box events see
https://developers.box.com/docs/#events[https://developers.box.com/docs/#events] and
for long polling
see https://developers.box.com/docs/#events-long-polling[https://developers.box.com/docs/#events-long-polling].
Consumer endpoints can only use the endpoint prefix *poll-events* as
shown in the example next. By default the consumer will split
the com.box.boxjavalibv2.dao.BoxEventCollection from every long poll and
create an exchange for every com.box.boxjavalibv2.dao.BoxEvent. To make
the consumer return the entire collection in a single exchange, use the
URI option *consumer.splitResult=false*.

[source,java]
----------------------------------------
    box://poll-events/endpoint?[options]
----------------------------------------

[width="100%",cols="10%,10%,10%,70%",options="header",]
|=======================================================================
|Endpoint |Shorthand Alias |Options |Result Body Type

|poll |  |limit, streamPosition, streamType |com.box.boxjavalibv2.dao.BoxEvent by default, or
com.box.boxjavalibv2.dao.BoxEventCollection when
consumer.splitResult=false
|=======================================================================

[[Box-URIOptionsforpoll-events]]
URI Options for _poll-events_

[width="100%",cols="10%,90%",options="header",]
|=======================================================================
|Name |Type

|limit |Integer

|streamPosition |Long

|streamType |String

|splitResult |boolean
|=======================================================================

[[Box-Messageheader]]
Message header
^^^^^^^^^^^^^^

Any of the options can be provided in a message header for producer
endpoints with *CamelBox.* prefix.

[[Box-Messagebody]]
Message body
^^^^^^^^^^^^

All result message bodies utilize objects provided by the Box Java SDK.
Producer endpoints can specify the option name for incoming message body
in the *inBody* endpoint parameter.

[[Box-TypeConverter]]
Type Converter
^^^^^^^^^^^^^^

The Box component also provides a Camel type converter to convert
http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/file/GenericFile.html[GenericFile]
objects from http://camel.apache.org/file2.html[File] component to
a *com.box.restclientv2.requestsbase.BoxFileUploadRequestObject* to
upload files to Box.com. The target *folderId* for the upload can be
specified in the exchange property *CamelBox.folderId*. If the exchange
property is not specified the value defaults to *"**0"* for the root
folder ID. 

[[Box-Usecases]]
Use cases
^^^^^^^^^

The following route uploads new files to the user's root folder:

[source,java]
-----------------------------------------------------------
    from("file:...")
        .to("box://files/upload/inBody=fileUploadRequest");
-----------------------------------------------------------

The following route polls user's account for updates:

[source,java]
-----------------------------------------------------------------------------
    from("box://poll-events/poll?streamPosition=-1&streamType=all&limit=100")
        .to("bean:blah");
-----------------------------------------------------------------------------

The following route uses a producer with dynamic header options. The
*fileId* property has the Box file id , so its assigned to the
*CamelBox.fileId* header as follows:

[source,java]
-------------------------------------------------------
    from("direct:foo")
        .setHeader("CamelBox.fileId", header("fileId"))
        .to("box://files/download")
        .to("file://...");
-------------------------------------------------------
