248 lines
14 KiB
XML
248 lines
14 KiB
XML
<?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 OAuth Configuration</title>
|
|
|
|
|
|
<para>
|
|
Twitter API allows for both authenticated and anonymous operations. For authenticated operations 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>
|
|
|
|
</section>
|
|
<section>
|
|
<title>Twitter Template</title>
|
|
|
|
<para>
|
|
Spring Integration uses the same familiar template pattern to interact with Twitter. Since current Twitter support
|
|
is based on Twitter4J API and we provide Twiter4JTemplate.
|
|
For anonymous operation (e.g., search) you don't have to define <classname>Twitter4JTemplate</classname> explicitly, since the default
|
|
instance of it will be created and injected into the endpoint. However, for authenticated operation
|
|
(e.g., update status, send direct message etc.) you must configure <classname>Twitter4JTemplate</classname> as a bean and
|
|
inject it explicitly into the endpoint. Below is a sample configuration of Twitter4JTemplate:
|
|
|
|
|
|
<programlisting language="xml"><![CDATA[<bean id="twitterTemplate" class="org.springframework.integration.twitter.core.Twitter4jTemplate">
|
|
<constructor-arg value="21691649-4XYZY5iJEOfz2A9qCFd9SjBRGb3HLmIm4HNE6AMv4""/>
|
|
<constructor-arg value="AbRxUAvyNCtqQtvxFK8w5ZMtMj20KFhB6oEfTA0"/>
|
|
<constructor-arg value="4XzBPabcJQxyBzzzH3TrRQ"/>
|
|
<constructor-arg value="ab2piKdMfPu8bVa3ab6DAIvIWEVZyMDL0RSEN2I8"/>
|
|
</bean>]]></programlisting>
|
|
<note>The values above are not real</note>
|
|
|
|
As you can see form the configuration above all we need to do is to provide
|
|
OAuth <code>attributes</code> as constructor arguments filling them with values you have obtained in the previous step.
|
|
The order of constructor arguments is: 1) <code>consumerKey</code>; 2) <code>consumerSecret</code>;
|
|
3) <code>accessToken</code>; 4) <code>accessTokenSecret</code>;
|
|
</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"/>
|
|
|
|
<bean id="twitterTemplate" class="org.springframework.integration.twitter.core.Twitter4jTemplate">
|
|
<constructor-arg value="${twitter.oauth.consumerKey}"/>
|
|
<constructor-arg value="${twitter.oauth.consumerSecret}"/>
|
|
<constructor-arg value="${twitter.oauth.accessToken}"/>
|
|
<constructor-arg value="${twitter.oauth.accessTokenSecret}"/>
|
|
</bean>]]></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
|
|
<link linkend="http://support.twitter.com/groups/31-twitter-basics/topics/109-tweets-messages/articles/119138-types-of-tweets-and-where-they-appear">twitter messages - tweets</link>
|
|
</para>
|
|
<para>
|
|
Current release of Spring Integration provides support for receiving tweets as <emphasis>Public Messages</emphasis>,
|
|
<emphasis>Direct Messages</emphasis>, <emphasis>Mention Messages</emphasis> as well as perform Searches
|
|
</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 latest Tweet timestamp
|
|
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 Message Channel Adapter</title>
|
|
<para>
|
|
This adapter allows you to receive updates from everyone you follow.
|
|
<programlisting language="java"><![CDATA[<twitter:inbound-channel-adapter twitter-template="twitterTemplate" channel="inChannel">
|
|
<poller fixed-rate="5000" max-messages-per-poll="3"/>
|
|
</twitter:inbound-channel-adapter>]]></programlisting>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="inbound-twitter-direct">
|
|
<title>Direct Inbound Message Channel Adapter</title>
|
|
<para>
|
|
This adapter allows you to receive Twitter Messages that were sent directly to you
|
|
<programlisting language="java"><![CDATA[<twitter:dm-inbound-channel-adapter twitter-template="twiterTemplate" channel="inboundDmChannel">
|
|
<poller fixed-rate="5000" max-messages-per-poll="3"/>
|
|
</twitter:dm-inbound-channel-adapter>]]></programlisting>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="inbound-twitter-mention">
|
|
<title>Mentions Inbound Message Channel Adapter</title>
|
|
<para>
|
|
This adapter allows you to receive Twitter Messages that Mention you via @user
|
|
<programlisting language="java"><![CDATA[<twitter:mentions-inbound-channel-adapter twitter-template="twiterTemplate"
|
|
channel="inboundMentionsChannel">
|
|
<poller fixed-rate="5000" max-messages-per-poll="3"/>
|
|
</twitter:mentions-inbound-channel-adapter>]]></programlisting>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="inbound-twitter-search">
|
|
<title>Search Inbound Message Channel Adapter</title>
|
|
<para>
|
|
This adapter allows you to perform searches. As you can see it is not neccessery to define twitter-template
|
|
since search could be performed anonymously, however an you must define a search query.
|
|
<programlisting language="java"><![CDATA[<twitter:search-inbound-channel-adapter query="#springintegration"
|
|
channel="inboundMentionsChannel">
|
|
<poller fixed-rate="5000" max-messages-per-poll="3"/>
|
|
</twitter:search-inbound-channel-adapter>]]></programlisting>
|
|
|
|
</para>
|
|
<para>
|
|
Here is a link that will help you learn more about Twitter queries: http://search.twitter.com/operators
|
|
</para>
|
|
</section>
|
|
<para>
|
|
As you can see the configuration of all of these adapters is very similar to other inbound adapters with one exception.
|
|
Some may need to be injected with the <code>twitter-template</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 type of any Message is <classname>org.springframework.integration.twitter.core.Tweet</classname>
|
|
which is very similar to the object with the same name in Spring Social. As we migrate to Spring Social
|
|
we'll be depending on their API and some of the artifacts that ar currently in use will be obsolete, however we've already
|
|
made sure that the impact of such migration is minimal by alignning our API with the curent state (at the time of writing)
|
|
of Spring Social
|
|
</para>
|
|
<para>
|
|
To get the text from the <classname>org.springframework.integration.twitter.core.Tweet</classname>
|
|
simply invoke <code>getText()</code> method.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="twitter-outbound">
|
|
<title>Twitter Outbound Adapter</title>
|
|
<para>
|
|
Twitter outbound channels adapters allow you to send Twitter Messages - tweets
|
|
</para>
|
|
<para>
|
|
Current release of Spring Integration supports sending <emphasis>Status Update Messages</emphasis> and <emphasis>Direct Messages</emphasis>.
|
|
Twitter outbound channels adapters as any other outbound adapter will take the Message payload and send it as
|
|
Twitter message. Currently the only supported payload type is <classname>String</classname>, so consider adding a <emphasis>transformer</emphasis>
|
|
if the payload of the incoming message is not a String.
|
|
</para>
|
|
|
|
<section id="outbound-twitter-update">
|
|
<title>Twitter Outbound Update Channel Adapter</title>
|
|
<para>
|
|
This adapter allows you to send regular status updates by simply sending a Message to a channel
|
|
identified via <code>channel</code> attribute.
|
|
<programlisting language="java"><![CDATA[<twitter:outbound-channel-adapter twitter-template="twitterTemplate" channel="twitterChannel"/>]]></programlisting>
|
|
The only extra configuration that is required for this adapter is <code>twitter-template</code>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="outbound-twitter-direct">
|
|
<title>Twitter Outbound Direct Message Channel Adapter</title>
|
|
<para>
|
|
This adapter allows you to send Direct Twitter Messages (i.e., @user) by simply sending a Message to a channel
|
|
identified via <code>channel</code> attribute.
|
|
<programlisting language="java"><![CDATA[<twitter:dm-outbound-channel-adapter twitter-template="twitterTemplate" channel="twitterChannel"/>]]></programlisting>
|
|
The only extra configuration that is required for this adapter is <code>twitter-template</code>
|
|
</para>
|
|
</section>
|
|
<para>
|
|
<important>Twitter does not allow you to post duplicate Messages. This is a common problem during testing when
|
|
the same code works the first time but doesn't work the second time,so make sure to change the content of the Message.
|
|
One thing that works good for testing is appent timestamp to the end of the message.
|
|
</important>
|
|
</para>
|
|
</section>
|
|
</chapter>
|