Repository: camel Updated Branches: refs/heads/master 17fd2363a -> 0db564a61
Added camel-facebook docs to gitbook Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/0db564a6 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/0db564a6 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/0db564a6 Branch: refs/heads/master Commit: 0db564a61ca72fef0bea680bc84a677e85543e73 Parents: 17fd236 Author: Andrea Cosentino <[email protected]> Authored: Fri Mar 18 15:20:15 2016 +0100 Committer: Andrea Cosentino <[email protected]> Committed: Fri Mar 18 15:20:15 2016 +0100 ---------------------------------------------------------------------- .../camel-facebook/src/main/docs/facebook.adoc | 257 +++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 2 files changed, 258 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/0db564a6/components/camel-facebook/src/main/docs/facebook.adoc ---------------------------------------------------------------------- diff --git a/components/camel-facebook/src/main/docs/facebook.adoc b/components/camel-facebook/src/main/docs/facebook.adoc new file mode 100644 index 0000000..22edbb5 --- /dev/null +++ b/components/camel-facebook/src/main/docs/facebook.adoc @@ -0,0 +1,257 @@ +[[Facebook-FacebookComponent]] +Facebook Component +~~~~~~~~~~~~~~~~~~ + +*Available as of Camel 2.12* + +The Facebook component provides access to all of the Facebook APIs +accessible using http://facebook4j.org/en/index.html[Facebook4J]. It +allows producing messages to retrieve, add, and delete posts, likes, +comments, photos, albums, videos, photos, checkins, locations, links, +etc. It also supports APIs that allow polling for posts, users, +checkins, groups, locations, etc. + +Facebook requires the use of OAuth for all client application +authentication. In order to use camel-facebook with your account, you'll +need to create a new application within Facebook at +https://developers.facebook.com/apps[https://developers.facebook.com/apps] +and grant the application access to your account. The Facebook +application's id and secret will allow access to Facebook APIs which do +not require a current user. A user access token is required for APIs +that require a logged in user. More information on obtaining a user +access token can be found at +https://developers.facebook.com/docs/facebook-login/access-tokens/[https://developers.facebook.com/docs/facebook-login/access-tokens/]. + +Maven users will need to add the following dependency to their pom.xml +for this component: + +[source,java] +----------------------------------------------- + <dependency> + <groupId>org.apache.camel</groupId> + <artifactId>camel-facebook</artifactId> + <version>${camel-version}</version> + </dependency> +----------------------------------------------- + +[[Facebook-URIformat]] +URI format +^^^^^^^^^^ + +[source,java] +--------------------------------- + facebook://[endpoint]?[options] +--------------------------------- + +[[Facebook-FacebookComponent.1]] +FacebookComponent +^^^^^^^^^^^^^^^^^ + +The facebook component can be configured with the Facebook account +settings below, which are mandatory. The values can be provided to the +component using the bean property *configuration* of type +*org.apache.camel.component.facebook.config.FacebookConfiguration*. The +*oAuthAccessToken* option may be ommited but that will only allow access +to application APIs. + +You can also configure these options directly in an endpoint URI. + +[width="100%",cols="20%,80%",options="header",] +|======================================================================= +|Option |Description + +|oAuthAppId |The application Id + +|oAuthAppSecret |The application Secret + +|oAuthAccessToken |The user access token +|======================================================================= + +In addition to the above settings, non-mandatory options below can be +used to configure the underlying Facebook4J runtime through either the +component's *configuration* property or in an endpoint URI. + +[width="100%",cols="10%,10%,80%",options="header",] +|======================================================================= +|Option |Description |Default Value + +|oAuthAuthorizationURL |OAuth authorization URL |https://www.facebook.com/dialog/oauth[https://www.facebook.com/dialog/oauth] + +|oAuthPermissions |Default OAuth permissions. Comma separeted permission names. See +https://developers.facebook.com/docs/reference/login/#permissions[https://developers.facebook.com/docs/reference/login/#permissions] +for the detail |null + +|oAuthAccessTokenURL |OAuth access token URL |https://graph.facebook.com/oauth/access_token[https://graph.facebook.com/oauth/access_token] + +|debugEnabled |Enables deubg output. Effective only with the embedded logger |false + +|gzipEnabled |Use Facebook GZIP encoding |true + +|httpConnectionTimeout |Http connection timeout in milliseconds |20000 + +|httpDefaultMaxPerRoute |HTTP maximum connections per route |2 + +|httpMaxTotalConnections |HTTP maximum total connections |20 + +|httpProxyHost |HTTP proxy server host name |null + +|httpProxyPassword |HTTP proxy server password |null + +|httpProxyPort |HTTP proxy server port |null + +|httpProxyUser |HTTP proxy server user name |null + +|httpReadTimeout |Http read timeout in milliseconds |120000 + +|httpRetryCount |Number of HTTP retries |0 + +|httpRetryIntervalSeconds |HTTP retry interval in seconds |5 + +|httpStreamingReadTimeout |HTTP streaming read timeout in milliseconds |40000 + +|jsonStoreEnabled |If set to true, raw JSON forms will be stored in DataObjectFactory |false + +|mbeanEnabled |If set to true, Facebook4J mbean will be registerd |false + +|prettyDebugEnabled |prettify JSON debug output if set to true |false + +|restBaseURL |API base URL |https://graph.facebook.com/[https://graph.facebook.com/] + +|useSSL |Use SSL |true + +|videoBaseURL |Video API base URL |https://graph-video.facebook.com/[https://graph-video.facebook.com/] + +|clientURL |Facebook4J API client URL |http://facebook4j.org/en/facebook4j-<version>.xml + +|clientVersion |Facebook4J client API version |1.1.12 +|======================================================================= + +[[Facebook-ProducerEndpoints:]] +Producer Endpoints: +^^^^^^^^^^^^^^^^^^^ + +Producer endpoints can use endpoint names and options from the table +below. Endpoints can also use the short name without the *get* or +*search* prefix, except *checkin* due to ambiguity between *getCheckin* +and *searchCheckin*. Endpoint options that are not mandatory are denoted +by []. + +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. For example, the facebook +endpoint in the following route retrieves activities for the user id +value in the incoming message body. + +[source,java] +-------------------------------------------------------------------- + from("direct:test").to("facebook://activities?inBody=userId")... +-------------------------------------------------------------------- + +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 +*CamelFacebook.https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=CAMEL&title=option&linkCreation=true&fromPageId=34020899[option]*. +For example, the *userId* option value in the previous route could +alternately be provided in the message header *CamelFacebook.userId*. +Note that the inBody option overrides message header, e.g. the endpoint +option *inBody=user* would override a *CamelFacebook.userId* header. + +Endpoints that return a String return an Id for the created or modified +entity, e.g. *addAlbumPhoto* returns the new album Id. Endpoints that +return a boolean, return true for success and false otherwise. In case +of Facebook API errors the endpoint will throw a RuntimeCamelException +with a facebook4j.FacebookException cause. + +[[Facebook-ConsumerEndpoints:]] +Consumer Endpoints: +^^^^^^^^^^^^^^^^^^^ + +Any of the producer endpoints that take a +https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=CAMEL&title=reading&linkCreation=true&fromPageId=34020899[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). + +[[Facebook-ReadingOptions]] +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 +https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=CAMEL&title=Graph+API&linkCreation=true&fromPageId=34020899[Graph +API#reading] - +https://developers.facebook.com/docs/reference/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. + +[[Facebook-Messageheader]] +Message header +^^^^^^^^^^^^^^ + +Any of the +https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=CAMEL&title=URI+options&linkCreation=true&fromPageId=34020899[URI +options#urioptions] can be provided in a message header for producer +endpoints with *CamelFacebook.* prefix. + +[[Facebook-Messagebody]] +Message body +^^^^^^^^^^^^ + +All result message bodies utilize objects provided by the Facebook4J +API. Producer endpoints can specify the option name for incoming message +body in 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. + +[[Facebook-Usecases]] +Use cases +^^^^^^^^^ + +To create a post within your Facebook profile, send this producer a +facebook4j.PostUpdate body. + +[source,java] +---------------------------------------------------- + from("direct:foo") + .to("facebook://postFeed/inBody=postUpdate); +---------------------------------------------------- + +To poll, every 5 sec (You can set the link:polling-consumer.html[polling +consumer] options by adding a prefix of "consumer"), all statuses on +your home feed: + +[source,java] +----------------------------------------------- + from("facebook://home?consumer.delay=5000") + .to("bean:blah"); +----------------------------------------------- + +Searching using a producer with dynamic 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. + +[source,java] +-------------------------------------------------------- + from("direct:foo") + .setHeader("CamelFacebook.query", header("bar")) + .to("facebook://posts"); +-------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/0db564a6/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 73a8792..5e072ea 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -127,6 +127,7 @@ * [Elsql](elsql.adoc) * [Eventadmin](eventadmin.adoc) * [Exec](exec.adoc) + * [Facebook](facebook.adoc) * [Ironmq](ironmq.adoc) * [JMS](jms.adoc) * [Metrics](metrics.adoc)
