INT-1557 added initial documentation (OAuth, Connection INbound Adapters) for Twitter adapter
This commit is contained in:
Oleg Zhurakousky
@@ -82,19 +82,20 @@
|
|||||||
<partintro id="spring-integration-adapters">
|
<partintro id="spring-integration-adapters">
|
||||||
<para>Adapters TODO</para>
|
<para>Adapters TODO</para>
|
||||||
</partintro>
|
</partintro>
|
||||||
|
<xi:include href="./event.xml"/>
|
||||||
<xi:include href="./file.xml"/>
|
<xi:include href="./file.xml"/>
|
||||||
|
<xi:include href="./http.xml"/>
|
||||||
|
<xi:include href="./httpinvoker.xml"/>
|
||||||
|
<xi:include href="./mail.xml"/>
|
||||||
|
<xi:include href="./ip.xml"/>
|
||||||
<xi:include href="./jdbc.xml"/>
|
<xi:include href="./jdbc.xml"/>
|
||||||
<xi:include href="./jms.xml"/>
|
<xi:include href="./jms.xml"/>
|
||||||
<xi:include href="./ws.xml"/>
|
|
||||||
<xi:include href="./rmi.xml"/>
|
<xi:include href="./rmi.xml"/>
|
||||||
<xi:include href="./httpinvoker.xml"/>
|
|
||||||
<xi:include href="./http.xml"/>
|
|
||||||
<xi:include href="./ip.xml"/>
|
|
||||||
<xi:include href="./mail.xml"/>
|
|
||||||
<xi:include href="./xmpp.xml"/>
|
|
||||||
<xi:include href="./stream.xml"/>
|
<xi:include href="./stream.xml"/>
|
||||||
<xi:include href="./event.xml"/>
|
<xi:include href="./twitter.xml"/>
|
||||||
|
<xi:include href="./ws.xml"/>
|
||||||
<xi:include href="./xml.xml"/>
|
<xi:include href="./xml.xml"/>
|
||||||
|
<xi:include href="./xmpp.xml"/>
|
||||||
</part>
|
</part>
|
||||||
<part id="spring-integration-appendices">
|
<part id="spring-integration-appendices">
|
||||||
<title>Appendices</title>
|
<title>Appendices</title>
|
||||||
|
|||||||
178
docs/src/reference/docbook/twitter.xml
Normal file
178
docs/src/reference/docbook/twitter.xml
Normal file
@@ -0,0 +1,178 @@
|
|||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="twitter"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||||
|
<title>Twitter Adapter</title>
|
||||||
|
<para>
|
||||||
|
Spring Integration provides support for interacting with Twitter via Twitter adapters. With Twitter adapters you can both
|
||||||
|
receive and send Twitter messages.
|
||||||
|
</para>
|
||||||
|
<section id="twitter-intro">
|
||||||
|
<title>Introduction</title>
|
||||||
|
<para>
|
||||||
|
Twitter is a social networking and microblogging service that enables its users to send and read messages known as tweets.
|
||||||
|
Tweets are text-based posts of up to 140 characters displayed on the author's profile page and delivered to the author's
|
||||||
|
subscribers who are known as followers.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<important>
|
||||||
|
Current Twitter support is based on <link linkend="http://twitter4j.org/en/index.html">Twitter4J API</link>,
|
||||||
|
however future version will be changed to use <link linkend="https://jira.springframework.org/browse/SOCIAL">Spring Social</link>
|
||||||
|
project as it is nearing its first release at the time of writing.
|
||||||
|
</important>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Spring Integration provides a convenient namespace configuration to define Twitter artifacts.
|
||||||
|
<programlisting language="xml"><![CDATA[xmlns:twitter="http://www.springframework.org/schema/integration/twitter"
|
||||||
|
xsi:schemaLocation="http://www.springframework.org/schema/integration/twitter
|
||||||
|
http://www.springframework.org/schema/integration/twitter/spring-integration-twitter-2.0.xsd"]]></programlisting>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="twitter-oauth">
|
||||||
|
<title>Twitter Connection and OAuth Configuration</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Before using inbound or outbound Twitter adapters you must establish secured Twitter connection. This connection object
|
||||||
|
could be shared by all twitter adapters connected to a particular account.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Twitter uses OAuth - an authentication protocol that allows users to approve application to act on their behalf without
|
||||||
|
sharing their password. More information can be found at <link linkend="http://oauth.net/">http://oauth.net/</link> or
|
||||||
|
in this article <link linkend="http://hueniverse.com/oauth/">http://hueniverse.com/oauth/</link> from Hueniverse.
|
||||||
|
Please also see <link linkend="http://dev.twitter.com/pages/oauth_faq">OAuth FAQ</link> for more information about OAuth and Twitter.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
In order to use OAuth authentication/authorization with Twitter you must create new Application on Twitter Developers site.
|
||||||
|
Follow the directions below to create a new application and obtain consumer keys and access token:
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>Go to <link linkend="http://dev.twitter.com/">http://dev.twitter.com/</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Click on <code>Register an app</code> link and fill out all required fields on the form provided;
|
||||||
|
set <code>Application Type</code> to <code>Client</code> and depending on the nature of your application select
|
||||||
|
<code>Default Access Type</code> as <emphasis>Read & Write</emphasis> or <emphasis>Read-only</emphasis>
|
||||||
|
and Submit the form. If everything is successful you'll be presented with the <code>Consumer Key</code>
|
||||||
|
and <code>Consumer Secret</code>. Copy both values in the safe place.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>On the same page you should see <code>My Access Token</code> button on the side bar (right).
|
||||||
|
Click on it and you'll be presented with two more values: <code>Access Token</code> and <code>Access Token Secret</code>.
|
||||||
|
Copy these values in a safe place as well.</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<emphasis>Twitter Connection</emphasis>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Spring Integration provides a convenient namespace configuration to define Twitter Connection. As you can see form the
|
||||||
|
configuration below you configure Twitter connection via <code>twitter-connection</code> element while providing
|
||||||
|
OAuth <code>attributes</code> filling them with values you have obtained in the previous step.
|
||||||
|
|
||||||
|
<programlisting language="xml"><![CDATA[<twitter:twitter-connection id="tc"
|
||||||
|
access-token="21691649-4XYZY5iJEOfz2A9qCFd9SjBRGb3HLmIm4HNE6AMv4"
|
||||||
|
access-token-secret="AbRxUAvyNCtqQtvxFK8w5ZMtMj20KFhB6oEfTA0"
|
||||||
|
consumer-key="4XzBPabcJQxyBzzzH3TrRQ"
|
||||||
|
consumer-secret="ab2piKdMfPu8bVa3ab6DAIvIWEVZyMDL0RSEN2I8"/>]]></programlisting>
|
||||||
|
<note>The values above are not real</note>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
However a more practical way to manage OAuth connection attributes would be via Spring's placeholder support by simply
|
||||||
|
creating a property file (e.g., oauth.properties):
|
||||||
|
|
||||||
|
<programlisting language="java"><![CDATA[twitter.oauth.consumerKey=4XzBPabcJQxyBzzzH3TrRQ
|
||||||
|
twitter.oauth.consumerSecret=ab2piKdMfPu8bVa3ab6DAIvIWEVZyMDL0RSEN2I8
|
||||||
|
twitter.oauth.accessToken=21691649-4XYZY5iJEOfz2A9qCFd9SjBRGb3HLmIm4HNE6AMv4
|
||||||
|
twitter.oauth.accessTokenSecret=AbRxUAvyNCtqQtvxFK8w5ZMtMj20KFhB6oEfTA0]]></programlisting>
|
||||||
|
|
||||||
|
and configuring a <code>property-placeholder</code> pointing to he above property file:
|
||||||
|
|
||||||
|
<programlisting language="java"><![CDATA[<context:property-placeholder
|
||||||
|
location="classpath:oauth.properties"/>
|
||||||
|
|
||||||
|
<twitter:twitter-connection id="tc"
|
||||||
|
access-token="${twitter.oauth.accessToken}"
|
||||||
|
access-token-secret="${twitter.oauth.accessTokenSecret}"
|
||||||
|
consumer-key="${twitter.oauth.consumerKey}"
|
||||||
|
consumer-secret="${twitter.oauth.consumerSecret}"/>]]></programlisting>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="twitter-inbound">
|
||||||
|
<title>Twitter Inbound Adapters</title>
|
||||||
|
<para>
|
||||||
|
Twitter inbound adapters allow you to receive Twitter Messages. There are several types of twitter messages:
|
||||||
|
<link linkend="http://support.twitter.com/groups/31-twitter-basics/topics/109-tweets-messages/articles/119138-types-of-tweets-and-where-they-appear">Types of Tweets</link>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Current release of Spring Integration provides support for Public Messages, Direct Messages as well as Mention Messages
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Every Inbound Twitter Channel Adapter is a <emphasis>Polling consumer</emphasis> which means you have to provide a poller
|
||||||
|
configuration. However, one important thing you must understand with regard to Twitter since its inner-workings are slightly
|
||||||
|
different then any other poling consumer. Twitter defines a concept of Rate Limiting. You can read more about
|
||||||
|
it here: <link linkend="http://dev.twitter.com/pages/rate-limiting">Rate Limiting</link> . In the nutshell Rate Limiting
|
||||||
|
is the way Twitter manages how often an application can poll for updates. Luckily for you you don't have to worry about it
|
||||||
|
since the special Rate limit aware polling thread is created when any Twitter adapter is started. This thread will
|
||||||
|
poll Messages (Tweets) from the Twitter account at the rate allowed by Twitter at the time (it may change after every poll). The Tweets
|
||||||
|
will be stored in the instance of the <classname>org.springframework.integration.store.MetadataStore</classname> which is a
|
||||||
|
strategy interface designed for storing various types of metadata (e.g., last retrieved tweet) to help components such as Twitter
|
||||||
|
to deal with duplicates. By default, Spring Integration will look for a bean of type <classname>org.springframework.integration.store.MetadataStore</classname>
|
||||||
|
in the ApplicationContext. If one found then it will be used, otherwise it will create a new instance of <classname>SimpleMetadataStore</classname>
|
||||||
|
which is a simple in-memory implementation that will only persist meta-data within the life-cycle of the application context
|
||||||
|
which means upon restart you may end up with duplicate entries. If you need to persist meta-data between Application Context
|
||||||
|
restarts, you may use <classname>PropertiesPersistingMetadataStore</classname> (property file based persister) or provide your
|
||||||
|
own implementation of the <classname>MetedataStore</classname> interface (e.g., JdbcMetadatStore) and configure it
|
||||||
|
as bean in the Application Context.
|
||||||
|
<programlisting language="java"><![CDATA[<bean class="org.springframework.integration.store.PropertiesPersistingMetadataStore"/>
|
||||||
|
]]></programlisting>
|
||||||
|
The Poller that is configured as part of the any Inbound Twitter Adapter (see below) will simply poll from this MetadataStore
|
||||||
|
</para>
|
||||||
|
<section id="inbound-twitter-update">
|
||||||
|
<title>Inbound Update Channel Adapter</title>
|
||||||
|
<para>
|
||||||
|
This adapter allows you to receive updates from everyone you follow.
|
||||||
|
<programlisting language="java"><![CDATA[<twitter:inbound-mention-channel-adapter twitter-connection="tc" channel="inbound_mentions">
|
||||||
|
<poller fixed-rate="5000" max-messages-per-poll="3"/>
|
||||||
|
</twitter:inbound-mention-channel-adapter>]]></programlisting>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="inbound-twitter-direct">
|
||||||
|
<title>Inbound Direct Message Channel Adapter</title>
|
||||||
|
<para>
|
||||||
|
This adapter allows you to receive Twitter Messages that were sent directly to you
|
||||||
|
<programlisting language="java"><![CDATA[<twitter:inbound-dm-channel-adapter twitter-connection="tc" channel="inbound_dm">
|
||||||
|
<poller fixed-rate="5000" max-messages-per-poll="3"/>
|
||||||
|
</twitter:inbound-dm-channel-adapter>]]></programlisting>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="inbound-twitter-mention">
|
||||||
|
<title>Inbound Mention Message Channel Adapter</title>
|
||||||
|
<para>
|
||||||
|
This adapter allows you to receive Twitter Messages that Mention you via @user
|
||||||
|
<programlisting language="java"><![CDATA[<twitter:inbound-mention-channel-adapter twitter-connection="tc" channel="inbound_mentions">
|
||||||
|
<poller fixed-rate="5000" max-messages-per-poll="3"/>
|
||||||
|
</twitter:inbound-mention-channel-adapter>]]></programlisting>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
<para>
|
||||||
|
As you can see the configuration of all of these adapters is very similar to other inbound adapters with one exception.
|
||||||
|
Each one needs to be injected with the <code>twitter-connection</code>. Once configured the Twitter Messages would be
|
||||||
|
encapsulated into a Spring Integration Message and sent to a channel specified via <code>channel</code> attribute.
|
||||||
|
Currently the Payload of the Message is <classname>twitter4j.DirectMessage</classname> for <emphasis>Inbound Direct Message Channel Adapter</emphasis>
|
||||||
|
or <classname>twitter4j.Status</classname> for <emphasis>Inbound Update Channel Adapter</emphasis> and
|
||||||
|
<emphasis>Inbound Mention Message Channel Adapter</emphasis>.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
For example; to get the text from the <classname>twitter4j.DirectMessage</classname> or <classname>twitter4j.Status</classname>
|
||||||
|
simply invoke <code>getText()</code> method. For more information please refer to <link linkend="http://twitter4j.org/en/index.html">Twitter4J API</link>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
</chapter>
|
||||||
Reference in New Issue
Block a user