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:

URI format

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. 

OptionTypeDescription
authSecureStoragecom.box.boxjavalibv2.authorization.IAuthSecureStorageOAuth 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.
boxConfigcom.box.boxjavalibv2.IBoxConfigCustom Box SDK configuration, not required normally
clientIdStringBox application client ID
clientSecretStringBox application client secret
connectionManagerBuildercom.box.boxjavalibv2.BoxConnectionManagerBuilderCustom Box connection manager builder, used to override default settings like max connections for underlying HttpClient.
httpParamsjava.util.MapCustom HTTP params for settings like proxy host
loginTimeoutintamount of time the component will wait for a response from Box.com, default is 30 seconds
refreshListenercom.box.boxjavalibv2.authorization.OAuthRefreshListenerOAuth listener for token updates, if the Camel application needs to use the access token outside the route
revokeOnShutdownbooleanFlag 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
sharedLinkStringBox shared link for shared-* endpoints, can be a link for a shared comment, file or folder
sharedPasswordStringPassword associated with the shared link, MUST be provided with sharedLink
userNameStringBox user name, MUST be provided
userPasswordStringBox 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:

EndpointShorthand AliasOptionsResult Body Type
createCollaborationcreatecollabRequest, folderIdcom.box.boxjavalibv2.dao.BoxCollaboration
deleteCollaborationdeletecollabId, defaultRequest 
getAllCollaborationsallCollaborationsgetAllCollabsRequestjava.util.List
getCollaborationcollaborationcollabId, defaultRequestcom.box.boxjavalibv2.dao.BoxCollaboration
updateCollaborationupdatecollabId, collabRequestcom.box.boxjavalibv2.dao.BoxCollaboration
URI Options for collaborations
NameType
collabIdString
collabRequestcom.box.boxjavalibv2.requests.requestobjects.BoxCollabRequestObject
defaultRequestcom.box.restclientv2.requestsbase.BoxDefaultRequestObject
folderIdString
getAllCollabsRequestcom.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:

EndpointShorthand AliasOptionsResult Body Type
getEventOptionseventOptionsdefaultRequestcom.box.boxjavalibv2.dao.BoxCollection
getEventseventseventRequestcom.box.boxjavalibv2.dao.BoxEventCollection
URI Options for events
NameType
defaultRequestcom.box.restclientv2.requestsbase.BoxDefaultRequestObject
eventRequestcom.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:

EndpointShorthand AliasOptionsResult Body Type
createGroup [groupRequest], [name]com.box.boxjavalibv2.dao.BoxGroup
createMembership [groupId, role, userId], [groupMembershipRequest]com.box.boxjavalibv2.dao.BoxGroupMembership
deleteGroupdeletedefaultRequest, groupId 
deleteMembershipdeletedefaultRequest, membershipId 
getAllCollaborationsallCollaborationsdefaultRequest, groupIdcom.box.boxjavalibv2.dao.BoxCollection
getAllGroupsallGroupsdefaultRequestcom.box.boxjavalibv2.dao.BoxCollection
getMembershipmembershipdefaultRequest, membershipIdcom.box.boxjavalibv2.dao.BoxGroupMembership
getMembershipsmembershipsdefaultRequest, groupIdcom.box.boxjavalibv2.dao.BoxCollection
updateGroupupdategroupId, groupRequestcom.box.boxjavalibv2.dao.BoxGroup
updateMembershipupdate[groupMembershipRequest], [role], membershipIdcom.box.boxjavalibv2.dao.BoxGroupMembership
URI Options for groups
NameType
defaultRequestcom.box.restclientv2.requestsbase.BoxDefaultRequestObject
groupIdString
groupMembershipRequestcom.box.boxjavalibv2.requests.requestobjects.BoxGroupMembershipRequestObject
groupRequestcom.box.boxjavalibv2.requests.requestobjects.BoxGroupRequestObject
membershipIdString
nameString
roleString
userIdString

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:

EndpointShorthand AliasOptionsResult Body Type
search defaultRequest, searchQuerycom.box.boxjavalibv2.dao.BoxCollection
URI Options for search
NameType
defaultRequestcom.box.restclientv2.requestsbase.BoxDefaultRequestObject
searchQueryString

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. 

EndpointShorthand AliasOptionsResult Body Type
addComment [commentRequest], [commentedItemId, commentedItemType, message]com.box.boxjavalibv2.dao.BoxComment
deleteCommentdeletecommentId, defaultRequest 
getCommentcommentcommentId, defaultRequestcom.box.boxjavalibv2.dao.BoxComment
updateCommentupdatecommentId, commentRequestcom.box.boxjavalibv2.dao.BoxComment
URI Options for comments and shared-comments
NameType
commentIdString
commentRequestcom.box.boxjavalibv2.requests.requestobjects.BoxCommentRequestObject
commentedItemIdString
commentedItemTypecom.box.boxjavalibv2.dao.IBoxType
defaultRequestcom.box.restclientv2.requestsbase.BoxDefaultRequestObject
messageString

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. 

EndpointShorthand AliasOptionsResult Body Type
copyFile fileId, itemCopyRequestcom.box.boxjavalibv2.dao.BoxFile
createSharedLinkcreatefileId, sharedLinkRequestcom.box.boxjavalibv2.dao.BoxFile
deleteFile defaultRequest, fileId 
downloadFiledownload[destination, listener], [listener, outputStreams], defaultRequest, fileIdjava.io.InputStream
downloadThumbnaildownloadextension, fileId, imageRequestjava.io.InputStream
getFilefiledefaultRequest, fileIdcom.box.boxjavalibv2.dao.BoxFile
getFileCommentsfileCommentsdefaultRequest, fileIdcom.box.boxjavalibv2.dao.BoxCollection
getFileVersionsfileVersionsdefaultRequest, fileIdjava.util.List
getPreviewpreviewextension, fileId, imageRequestcom.box.boxjavalibv2.dao.BoxPreview
getThumbnailthumbnailextension, fileId, imageRequestcom.box.boxjavalibv2.dao.BoxThumbnail
updateFileInfoupdatefileId, fileRequestcom.box.boxjavalibv2.dao.BoxFile
uploadFileuploadfileUploadRequestcom.box.boxjavalibv2.dao.BoxFile
uploadNewVersionuploadfileId, fileUploadRequestcom.box.boxjavalibv2.dao.BoxFile
URI Options for files and shared-files
NameType
defaultRequestcom.box.restclientv2.requestsbase.BoxDefaultRequestObject
destinationjava.io.File
extensionString
fileIdString
fileRequestcom.box.boxjavalibv2.requests.requestobjects.BoxFileRequestObject
fileUploadRequestcom.box.restclientv2.requestsbase.BoxFileUploadRequestObject
imageRequestcom.box.boxjavalibv2.requests.requestobjects.BoxImageRequestObject
itemCopyRequestcom.box.boxjavalibv2.requests.requestobjects.BoxItemCopyRequestObject
listenercom.box.boxjavalibv2.filetransfer.IFileTransferListener
outputStreamsjava.io.OutputStream[]
sharedLinkRequestcom.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. 

EndpointShorthand AliasOptionsResult Body Type
copyFolder folderId, itemCopyRequestcom.box.boxjavalibv2.dao.BoxFolder
createFoldercreatefolderRequestcom.box.boxjavalibv2.dao.BoxFolder
createSharedLinkcreatefolderId, sharedLinkRequestcom.box.boxjavalibv2.dao.BoxFolder
deleteFolderdeletefolderDeleteRequest, folderId 
getFolderfolderdefaultRequest, folderIdcom.box.boxjavalibv2.dao.BoxFolder
getFolderCollaborationsfolderCollaborationsdefaultRequest, folderIdjava.util.List
getFolderItemsfolderItemsfolderId, pagingRequestcom.box.boxjavalibv2.dao.BoxCollection
updateFolderInfoupdatefolderId, folderRequestcom.box.boxjavalibv2.dao.BoxFolder
URI Options for folders or shared-folders

 

NameType
defaultRequestcom.box.restclientv2.requestsbase.BoxDefaultRequestObject
folderDeleteRequestcom.box.boxjavalibv2.requests.requestobjects.BoxFolderDeleteRequestObject
folderIdString
folderRequestcom.box.boxjavalibv2.requests.requestobjects.BoxFolderRequestObject
itemCopyRequestcom.box.boxjavalibv2.requests.requestobjects.BoxItemCopyRequestObject
pagingRequestcom.box.boxjavalibv2.requests.requestobjects.BoxPagingRequestObject
sharedLinkRequestcom.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:

EndpointShorthand AliasOptionsResult Body Type
getSharedItemsharedItemdefaultRequestcom.box.boxjavalibv2.dao.BoxItem
URI Options for shared-items
NameType
defaultRequestcom.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:

EndpointShorthand AliasOptionsResult Body Type
addEmailAlias emailAliasRequest, userIdcom.box.boxjavalibv2.dao.BoxEmailAlias
createEnterpriseUsercreateuserRequestcom.box.boxjavalibv2.dao.BoxUser
deleteEmailAlias defaultRequest, emailId, userId 
deleteEnterpriseUser userDeleteRequest, userId 
getAllEnterpriseUserallEnterpriseUserdefaultRequest, filterTermjava.util.List
getCurrentUsercurrentUserdefaultRequestcom.box.boxjavalibv2.dao.BoxUser
getEmailAliasesemailAliasesdefaultRequest, userIdjava.util.List
moveFolderToAnotherUser folderId, simpleUserRequest, userIdcom.box.boxjavalibv2.dao.BoxFolder
updateUserInformaitonupdateuserId, userRequestcom.box.boxjavalibv2.dao.BoxUser
updateUserPrimaryLoginupdateuserId, userUpdateLoginRequestcom.box.boxjavalibv2.dao.BoxUser
URI Options for users
NameType
defaultRequestcom.box.restclientv2.requestsbase.BoxDefaultRequestObject
emailAliasRequestcom.box.boxjavalibv2.requests.requestobjects.BoxEmailAliasRequestObject
emailIdString
filterTermString
folderIdString
simpleUserRequestcom.box.boxjavalibv2.requests.requestobjects.BoxSimpleUserRequestObject
userDeleteRequestcom.box.boxjavalibv2.requests.requestobjects.BoxUserDeleteRequestObject
userIdString
userRequestcom.box.boxjavalibv2.requests.requestobjects.BoxUserRequestObject
userUpdateLoginRequestcom.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.

EndpointShorthand AliasOptionsResult 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
NameType
limitInteger
streamPositionLong
streamTypeString
splitResultboolean

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 header property CamelBox.folderId. If the header 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:

The following route polls user's account for updates:

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

© 2004-2014 The Apache Software Foundation.
Apache Camel, Camel, Apache, the Apache feather logo, and the Apache Camel project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
Graphic Design By Hiram