You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ac...@apache.org on 2016/03/18 15:42:28 UTC
camel git commit: Added camel-facebook docs to gitbook
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 <an...@gmail.com>
Authored: Fri Mar 18 15:20:15 2016 +0100
Committer: Andrea Cosentino <an...@gmail.com>
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)