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 | ||
---|---|---|
| ||
<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 |
---|---|---|
|
| OAuth Secure Storage callback, can be used to provide and or save OAuth tokens. The callback may returnreturn |
|
| Custom Box SDK configuration, not required normally. |
|
| Box application client ID. |
|
| Box application client secret. |
|
| Custom Box connection manager builder, used to override default settings like max connections for underlying |
|
| Custom HTTP params for settings like proxy host. |
|
| amount Amount of time the component will wait for a response from Box.com , default. Default is 30 seconds. |
|
| OAuth listener for token updates, if the Camel application needs to use the access token outside the route. |
|
| Flag to revoke OAuth refresh token on route shutdown, default false. Will require a fresh refresh token on restart using either a customcustom |
|
| Box shared link forfor |
|
| Password associated with the shared link, MUST be provided with |
|
| Box user name, MUST be provided. |
|
| Box user password, MUST be provided ifif returns |
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
cause 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 |
---|---|---|---|
|
|
|
|
|
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
URI Options for collaborations
Name | Type |
---|---|
|
|
|
|
|
|
|
|
|
|
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 |
---|---|---|---|
|
|
|
|
|
|
|
|
URI Options for events
Name | Type |
---|---|
|
|
|
|
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 |
---|---|---|---|
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
URI Options for groups
Name | Type |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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:
Code Block |
---|
box://search/endpoint?[options] |
Endpoint | Shorthand Alias | Options | Result Body Type |
---|---|---|---|
|
|
|
URI Options for search
Name | Type |
---|---|
|
|
|
|
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 |
---|---|---|---|
|
|
| |
|
|
| |
|
|
|
|
|
|
|
|
URI Options for comments
and shared-comments
Name | Type |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
---|---|---|---|
|
|
| |
|
|
|
|
|
| ||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
URI Options for files
and shared-files
Name | Type |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
---|---|---|---|
|
|
| |
|
|
|
|
|
|
|
|
|
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
URI Options for folders
or shared-folders
Name | Type |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
---|---|---|---|
|
|
|
|
URI Options for shared-items
Name | Type |
---|---|
|
|
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 |
---|---|---|---|
|
|
| |
|
|
|
|
|
| ||
|
| ||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
|
|
|
|
|
|
|
|
URI Options for users
Name | Type |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
---|---|---|---|
|
|
or |
URI Options for poll-events
Name | Type |
---|---|
|
|
|
|
|
|
|
|
Message Header
Any of the options can
...
- 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 | ||
---|---|---|
| ||
from("file:...")
.to("box://files/upload/inBody=fileUploadRequest");
|
The following route polls user's account for updates:
Code Block | ||
---|---|---|
| ||
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 | ||
---|---|---|
| ||
| ||
Code Block | ||
from("direct:foo") .setHeader("CamelFacebookCamelBox.queryfileId", header("barfileId")) .to("box://files/download") .to("facebookfile://posts..."); |