Versions Compared

Old Version 2

changes.mady.by.user Dhiraj Bokde

Saved on

compared with

New Version Current

changes.mady.by.user Andy Bell

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Fixed broken link

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 coman com.box.boxjavalibv2.dao.IAuthData OAuth token.

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

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

URI

...

Format

Code Block
  box://endpoint-prefix/endpoint?[options]

Endpoint Where the 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

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

Amount of time the component will wait for a response from Box.com

, default

. 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

custom IAuthSecureStorage or automatic component login by providing a user password.

sharedLink

String

Box shared link

for

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

if authSecureStorage is not set, or

returns

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 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 a RuntimeCamelException with a a com.box.restclientv2.exceptions.BoxSDKException derived derived exception cause.

 

Consumer Endpoints:

Any of the producer endpoints that take a reading#reading parameter can be used as a consumer endpoint. The polling consumer uses the since and until fields to get responses within the polling interval. In addition to other reading fields, an initial since value can be provided in the endpoint for the first poll.

Rather than the endpoints returning a List (or facebook4j.ResponseList) through a single route exchange, camel-facebook creates one route exchange per returned object. As an example, if "facebook://home" results in five posts, the route will be executed five times (once for each Post).

...

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:

Code Block
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:

Code Block
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:

Code Block
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

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:

Code Block
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. 

Code Block
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. 

Code Block
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. 

Code Block
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:

Code Block
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:

Code Block
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.

Code Block
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

...

  1. URI Options #

Name

Type

Description

achievementURL

java.net.URL

The unique URL of the achievement

albumCreate

facebook4j.AlbumCreate

The facebook Album to be created

albumId

String

The album ID

allowNewOptions

boolean

True if allows other users to add new options

appId

String

The ID of the Facebook Application

center

facebook4j.GeoLocation

Location latitude and longitude

checkinCreate

facebook4j.CheckinCreate

The checkin to be created. Deprecated, instead create a Post with an attached location

checkinId

String

The checkin ID

commentId

String

The comment ID

description

String

The description text

distance

int

Distance in meters

domainId

String

The domain ID

domainName

String

The domain name

domainNames

String[]

The domain names

eventId

String

The event ID

eventUpdate

facebook4j.EventUpdate

The event to be created or updated

friendId

String

The friend ID

friendUserId

String

The friend user ID

friendlistId

String

The friend list ID

friendlistName

String

The friend list Name

groupId

String

The group ID

ids

String[]

The ids of users

includeRead

boolean

Enables notifications that the user has already read in addition to unread ones

link

java.net.URL

Link URL

linkId

String

The link ID

locale

java.util.Locale

Desired FQL locale

message

String

The message text

messageId

String

The message ID

metric

String

The metric name

name

String

Test user name, must be of the form 'first last'

noStory

boolean

If set to true, optionally suppresses the feed story that is automatically generated on a user’s profile when they upload a photo using your application.

noteId

String

The note ID

notificationId

String

The notification ID

objectId

String

The insight object ID

optionDescription

String

The question's answer option description

options

java.util.List<String>

The question's answer options

permissionName

String

The permission name

permissions

String

Test user permissions in the format perm1,perm2,...

photoId

String

The photo ID

place

String

The Facebook ID of the place associated with the Photo

placeId

String

The place ID

postId

String

The post ID

postUpdate

facebook4j.PostUpdate

The post to create or update

queries

java.util.Map<String>

FQL queries

query

String

FQL query or search terms for search* endpoints

question

String

The question text

questionId

String

The question id

reading

facebook4j.Reading

Optional reading parameters. See Reading Options(#reading)

scoreValue

int

The numeric score with value

size

facebook4j.PictureSize

The picture size, one of large, normal, small or square

source

facebook4j.Media

The media content from either a java.io.File or java.io.Inputstream

subject

String

The note of the subject

tagUpdate

facebook4j.TagUpdate

Photo tag information

testUser1

facebook4j.TestUser

Test user

testUser2

facebook4j.TestUser

Test user

testUserId

String

The ID of the test user

title

String

The title text

toUserId

String

The ID of the user to tag

toUserIds

java.util.List<String>

The IDs of the users to tag

userId

String

The Facebook user ID

userId1

String

The ID of a user

userId2

String

The ID of a user

userIds

String[]

The IDs of users to invite to event

userLocale

String

The test user locale

videoId

String

The video ID

...

Reading Options

The reading option of type facebook4j.Reading adds support for reading parameters, which allow selecting specific fields, limits the number of results, etc. For more information see Graph API#reading - Facebook Developers.

It is also used by consumer endpoints to poll Facebook data to avoid sending duplicate messages across polls.

The reading option can be a reference or value of type facebook4j.Reading, or can be specified using the following reading options in either the endpoint URI or exchange header with CamelFacebook. prefix.

Option

Description

reading.fields

Field names to retrieve, in the format field1,field2,...

reading.limit

Limit for number of items to return for list results, e.g. a limit of 10 returns items 1 through 10

reading.offset

Starting offset for list results, e.g. a limit of 10, and offset of 10 returns items 11 through 20

reading.until

A Unix timestamp or strtotime data value that points to the end of the range of time-based data

reading.since

A Unix timestamp or strtotime data value that points to the start of the range of time-based data

reading.locale

Retrieve localized content in a particular locale, specified as a String with the format language[,country][,variant]

reading.with

Retrieve information about objects that have location information attached, set it to true

reading.metadata

Use Facebook Graph API Introspection to retrieve object metadata, set it to true

reading.filter

User's stream filter key. See Facebook stream_filter

Message header

Any of the URI options#urioptions can be provided in a message header for producer endpoints with CamelFacebookCamelBox. prefix.

Message

...

Body

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

For endpoints that return an array, or facebook4j.ResponseList, or java.util.List, a consumer endpoint will map every elements in the list to distinct messages.

Use cases

To create a post within your Facebook profile, send this producer a facebook4j.PostUpdate body.

Code Block
	from("direct:foo")
		.to("facebook://postFeed/inBody=postUpdate);

To poll, every 5 sec., all statuses on your home feed:

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:

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

The following route polls user's account for updates:

Code Block
languagejava
from("box://poll-events/poll?streamPosition=-1&streamType=all&limit=100")
Code Block
	from("facebook://home?delay=5")
		.to("bean:blah");

Searching using The following route uses a producer with dynamic header options from header.

In the bar header we have the Facebook search string we want to execute in public posts, so we need to assign this value to the CamelFacebook.query header.

. The fileId property has the Box file id, so its assigned to the CamelBox.fileId header as follows:

Code Block
languagejava
Code Block
	from("direct:foo")
		    .setHeader("CamelFacebookCamelBox.queryfileId", header("barfileId"))
		    .to("box://files/download")
    .to("facebookfile://posts...");