Red Hat Training

A Red Hat training course is available for Red Hat Fuse

Chapter 14. Box

Box Component

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>

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

Box Component

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:

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
[groupMembershipRequest], [role], membershipId
com.box.boxjavalibv2.dao.BoxGroupMembership

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
upload
fileId, fileUploadRequest
com.box.boxjavalibv2.dao.BoxFile

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
update
folderId, folderRequest
com.box.boxjavalibv2.dao.BoxFolder

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
update
userId, userUpdateLoginRequest
com.box.boxjavalibv2.dao.BoxUser

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://...");