Box Component

Table of Contents

Box Options
URI format
BoxComponent
Producer Endpoints:
Consumer Endpoints:
Message header
Message body
Type Converter
Use cases

Available as of Camel 2.14

The Box component provides access to all of the Box.com APIs accessible using 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/. 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:

    <dependency>
        <groupId>org.apache.camel</groupId>
        <artifactId>camel-box</artifactId>
        <version>${camel-version}</version>
    </dependency>

Box Options

The Box component supports 1 options which are listed below.

{% raw %}

Name	Java Type	Description
configuration	`BoxConfiguration`	To use the shared configuration

{% endraw %}

The Box component supports 21 endpoint options which are listed below:

{% raw %}

Name	Group	Default	Java Type	Description
apiName	common		`BoxApiName`	Required What kind of operation to perform
methodName	common		`String`	Required What sub operation to use for the selected operation
clientId	common		`String`	Box application client ID
inBody	common		`String`	Sets the name of a parameter to be passed in the exchange In Body
loginTimeout	common	`30`	`int`	Amount of time the component will wait for a response from Box.com default is 30 seconds
revokeOnShutdown	common	`false`	`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	common		`String`	Box shared link for shared endpoints can be a link for a shared comment file or folder
sharedPassword	common		`String`	Password associated with the shared link MUST be provided with sharedLink
bridgeErrorHandler	consumer	`false`	`boolean`	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/ERROR level and ignored.
exceptionHandler	consumer (advanced)		`ExceptionHandler`	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions that will be logged at WARN/ERROR level and ignored.
exchangePattern	consumer (advanced)		`ExchangePattern`	Sets the exchange pattern when the consumer creates an exchange.
boxConfig	advanced		`IBoxConfig`	Custom Box SDK configuration not required normally
connectionManagerBuilder	advanced		`BoxConnectionManagerBuilder`	Custom Box connection manager builder used to override default settings like max connections for underlying HttpClient.
httpParams	advanced		`Map`	Custom HTTP params for settings like proxy host
refreshListener	advanced		`OAuthRefreshListener`	OAuth listener for token updates if the Camel application needs to use the access token outside the route
synchronous	advanced	`false`	`boolean`	Sets whether synchronous processing should be strictly used or Camel is allowed to use asynchronous processing (if supported).
authSecureStorage	security		`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.
clientSecret	security		`String`	Box application client secret
sslContextParameters	security		`SSLContextParameters`	To configure security using SSLContextParameters.
userName	security		`String`	Box user name MUST be provided
userPassword	security		`String`	Box user password MUST be provided if authSecureStorage is not set or returns null on first call

{% endraw %}

URI format

    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

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.

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

Producer Endpoints:

Table of Contents

Endpoint Prefix collaborations
Endpoint Prefix events
Endpoint Prefix groups
Endpoint Prefix search
Endpoint Prefix comments and shared-comments
Endpoint Prefix files and shared-files
Endpoint Prefix folders and shared-folders
Endpoint Prefix shared-items
Endpoint Prefix users

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.

Endpoint Prefix collaborations

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

    box://collaborations/endpoint?[options]

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

URI Options for collaborations

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

Endpoint Prefix events

For more information on Box events see 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:

  box://events/endpoint?[options]

Endpoint	Shorthand Alias	Options	Result Body Type
getEventOptions	eventOptions	defaultRequest	com.box.boxjavalibv2.dao.BoxCollection
getEvents	events	eventRequest	com.box.boxjavalibv2.dao.BoxEventCollection

URI Options for events

Name	Type
defaultRequest	com.box.restclientv2.requestsbase.BoxDefaultRequestObject
eventRequest	com.box.boxjavalibv2.requests.requestobjects.BoxEventRequestObject

Endpoint Prefix groups

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

    box://groups/endpoint?[options]

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

URI Options for groups

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

Endpoint Prefix search

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

    box://search/endpoint?[options]

Endpoint	Shorthand Alias	Options	Result Body Type
search		defaultRequest, searchQuery	com.box.boxjavalibv2.dao.BoxCollection

URI Options for search

Name	Type
defaultRequest	com.box.restclientv2.requestsbase.BoxDefaultRequestObject
searchQuery	String

Endpoint Prefix comments and shared-comments

For more information on Box comments see 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.

    box://comments/endpoint?[options]
    box://shared-comments/endpoint?[options]

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

URI Options for comments and shared-comments

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

Endpoint Prefix files and shared-files

For more information on Box files see 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.

   box://files/endpoint?[options]
   box://shared-files/endpoint?[options]

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

URI Options for files and shared-files

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

Endpoint Prefix folders and shared-folders

For more information on Box folders see 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.

    box://folders/endpoint?[options]
    box://shared-folders/endpoint?[options]

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

URI Options for folders or shared-folders

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

Endpoint Prefix shared-items

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

    box://shared-items/endpoint?[options]

Endpoint	Shorthand Alias	Options	Result Body Type
getSharedItem	sharedItem	defaultRequest	com.box.boxjavalibv2.dao.BoxItem

URI Options for shared-items

Name	Type
defaultRequest	com.box.restclientv2.requestsbase.BoxDefaultRequestObject

Endpoint Prefix users

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

    box://users/endpoint?[options]

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

URI Options for users

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

Consumer Endpoints:

For more information on Box events see https://developers.box.com/docs/#events and for long polling see 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.

    box://poll-events/endpoint?[options]

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

URI Options for poll-events

Name	Type
limit	Integer
streamPosition	Long
streamType	String
splitResult	boolean

Message header

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

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.

Type Converter

The Box component also provides a Camel type converter to convert GenericFile objects from 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.

Use cases

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

    from("file:...")
        .to("box://files/upload/inBody=fileUploadRequest");

The following route polls user’s account for updates:

    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:

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