Skip to content
This repository has been archived by the owner on Mar 21, 2019. It is now read-only.

Commit

Permalink
Reference docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@habuma
habuma committed Jun 2, 2011
1 parent 9ed7466 commit 2003696
Show file tree
Hide file tree
Showing 5 changed files with 222 additions and 108 deletions.
96 changes: 96 additions & 0 deletions docs/src/reference/docbook/api.xml
View file
@@ -0,0 +1,96 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="apis" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Gowalla API Binding</title>

<para>
Spring Social Gowalla provides an API binding to Gowalla's REST API through the <interfacename>Gowalla</interfacename> interface and its implementation, <classname>GowallaTemplate</classname>.
</para>

<para>
To obtain an instance of <classname>GowallaTemplate</classname>, you can instantiate it by passing an authorized access token to its constructor:
</para>

<programlisting language="java"><![CDATA[
String accessToken = "f8FX29g..."; // access token received from Gowalla after OAuth authorization
Gowalla gowalla = new GowallaTemplate(accessToken);]]>
</programlisting>

<para>
If you are using Spring Social's <ulink url="http://static.springsource.org/spring-social/docs/1.0.x/reference/html/serviceprovider.html">service provider framework</ulink>, you can get an instance of <interfacename>Gowalla</interfacename> via a <interfacename>Connection</interfacename>.
For example, the following snippet calls <methodname>getApi()</methodname> on a connection to retrieve a <interfacename>Gowalla</interfacename>:
</para>

<programlisting language="java"><![CDATA[
Connection<Gowalla> connection = connectionRepository.findPrimaryConnectionToApi(Gowalla.class);
Gowalla gowalla = connection.getApi();]]>
</programlisting>

<para>
Here, <interfacename>ConnectionRepository</interfacename> is being asked for the primary connections that the current user has with Gowalla.
From that connection, it retrieves a <interfacename>Gowalla</interfacename> instance that is configured with the connection details received when the connection was first established.
</para>

<para>
With a <interfacename>Gowalla</interfacename> in hand, there are a handful of operations it provides to interact with Gowalla on behalf of the user.
These will be covered in the following sections.
</para>

<section id="gowalla-getProfile">
<title>Retrieving a user's profile data</title>

<para>
You can retrieve a user's Gowalla profile using the <methodname>getUserProfile()</methodname> method:
</para>

<programlisting language="java"><![CDATA[
GowallaProfile profile = gowalla.getUserProfile();]]>
</programlisting>

<para>
This will return the Gowalla profile data for the authenticated user.
If you want to retrieve profile data for another user, you can pass the user's profile ID into <methodname>getUserProfile()</methodname>:
</para>

<programlisting language="java"><![CDATA[
GowallaProfile profile = gowalla.getUserProfile("habuma");]]>
</programlisting>

<para>
The <classname>GowallaProfile</classname> object contains basic information about the Gowalla user such as their first and last names, their hometown, and the number of pins and stamps that they have earned.
</para>

<para>
If all you want is the authenticated user's profile ID, you can get that by calling the <methodname>getProfileId()</methodname>:
</para>

<programlisting language="java"><![CDATA[
String profileId = gowalla.getProfileId();]]>
</programlisting>

<para>
Or if you want the URL to the user's profile page at Gowalla, use the <methodname>getProfileUrl()</methodname> method:
</para>

<programlisting language="java"><![CDATA[
String profileUrl = gowalla.getProfileUrl();]]>
</programlisting>

</section>

<section id="gowalla-checkins">
<title>Getting a user's checkins</title>

<para>
<interfacename>Gowalla</interfacename> also allows you to learn about the user's favorite checkin spots.
The <methodname>getTopCheckins()</methodname> method will provide a list of the top 10 places that the user has visited:
</para>

<programlisting language="java"><![CDATA[
List<Checkin> topCheckins = gowalla.getTopCheckins();]]>
</programlisting>

<para>
Each member of the returns list is a <classname>Checkin</classname> object that includes the name of the location as well as the number of times that the user has checked in at that location.
</para>
</section>
</chapter>
104 changes: 0 additions & 104 deletions docs/src/reference/docbook/apis.xml
View file

This file was deleted.

69 changes: 69 additions & 0 deletions docs/src/reference/docbook/connecting.xml
View file
@@ -0,0 +1,69 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="connecting"
xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Configuring Gowalla Connectivity</title>

<para>
Spring Social's <classname>ConnectController</classname> works with one or more provider-specific <classname>ConnectionFactory</classname>s to exchange authorization details with the provider and to create connections.
Spring Social Gowalla provides <classname>GowallaConnectionFactory</classname>, a <classname>ConnectionFactory</classname> for creating connections with Gowalla.
</para>

<para>
So that <classname>ConnectController</classname> can find <classname>GowallaConnectionFactory</classname>, it must be registered with a <classname>ConnectionFactoryRegistry</classname>.
The following class constructs a <classname>ConnectionFactoryRegistry</classname> containing a <interfacename>ConnectionFactory</interfacename> for Gowalla using Spring's Java configuration style:
</para>

<programlisting language="java"><![CDATA[
@Configuration
public class ConnectionFactoryConfig {
@Bean
public ConnectionFactoryLocator connectionFactoryLocator() {
ConnectionFactoryRegistry registry = new ConnectionFactoryRegistry();
registry.addConnectionFactory(new GowallaConnectionFactory(gowallaClientId, gowallaClientSecret));
return registry;
}
@Value("${gowalla.clientId}")
private String gowallaClientId;
@Value("${gowalla.clientSecret}")
private String gowallaClientSecret;
}
]]></programlisting>

<para>
Here, a Gowalla connection factory is registered with <classname>ConnectionFactoryRegistry</classname> via the <methodname>addConnectionFactory()</methodname> method.
If we wanted to add support for connecting to other providers, we would simply register their connection factories here in the same way as <classname>GowallaConnectionFactory</classname>.
Because consumer keys and secrets may be different across environments (e.g., test, production, etc) it is recommended that these values be externalized.
Therefore, they are wired in with <code>@Value</code> as property placeholder values to be resolved by Spring's property placeholder support.
</para>

<para>
Optionally, you may also configure <classname>ConnectionFactoryRegistry</classname> and <classname>GowallaConnectionFactory</classname> in XML:
</para>

<programlisting language="xml"><![CDATA[
<bean id="connectionFactoryLocator" class="org.springframework.social.connect.support.ConnectionFactoryRegistry">
<property name="connectionFactories">
<list>
<bean class="org.springframework.social.gowalla.connect.GowallaConnectionFactory">
<constructor-arg value="${gowalla.clientId}" />
<constructor-arg value="${gowalla.clientSecret}" />
</bean>
</list>
</property>
</bean>]]>
</programlisting>

<para>
This is functionally equivalent to the Java-based configuration of <classname>ConnectionFactoryRegistry</classname> shown before.
The only casual difference is that the connection factories are injected as a list into the <code>connectionFactories</code> property rather than with the <methodname>addConnectionFactory()</methodname> method.
</para>

<para>
Refer to <ulink url="http://static.springsource.org/spring-social/docs/1.0.x/reference/html/connecting.html">Spring Social's reference documentation</ulink> for complete details on configuring <classname>ConnectController</classname> and its dependencies.
</para>

</chapter>
3 changes: 2 additions & 1 deletion docs/src/reference/docbook/index.xml
View file
Expand Up @@ -37,5 +37,6 @@
<toc></toc>

<xi:include href="./overview.xml"/>
<xi:include href="./apis.xml" />
<xi:include href="./connecting.xml"/>
<xi:include href="./api.xml" />
</book>
58 changes: 55 additions & 3 deletions docs/src/reference/docbook/overview.xml
View file
Expand Up @@ -3,7 +3,59 @@
xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Spring Social Gowalla Overview</title>

<section id="overview-introduction">
<title>Introduction</title>
</section>
<section id="overview-introduction">
<title>Introduction</title>

<para>
The Spring Social Gowalla project is an extension to <ulink url="http://www.springframework.org/spring-social">Spring Social</ulink> that enables integration with Gowalla.
</para>

<para>
<ulink url="http://www.gowalla.com">Gowalla</ulink> is a location-based social network where users may check in to various locations they visit and earn pins and stamps for having checked in a locations that achieve some goal (for example, a "Lucha Libre" pin may be earned by having checked into 10 different Mexican food restaurants).
</para>

<para>
Spring Social Gowalla enables integration with Gowalla with <classname>GowallaConnectionFactory</classname>, a connection factory that can be plugged into Spring Social's service provider connection framework, and with an API binding to Gowalla's REST API.
</para>
</section>

<section id="overview-howtoget">
<title>How to get</title>

<para>
The following Maven dependency will add Spring Social Gowalla to your project:
</para>

<programlisting language="xml"><![CDATA[
<dependency>
<groupId>org.springframework.social</groupId>
<artifactId>spring-social-gowalla</artifactId>
<version>${org.springframework.social-gowalla-version}</version>
</dependency>]]>
</programlisting>

<para>
As an extension to Spring Social, Spring Social Gowalla depends on Spring Social.
Spring Social's core module will be transitively resolved from the Spring Social Gowalla dependency.
If you'll be using Spring Social's web module, you'll need to add that dependency yourself:
</para>

<programlisting language="xml"><![CDATA[
<dependency>
<groupId>org.springframework.social</groupId>
<artifactId>spring-social-web</artifactId>
<version>${org.springframework.social-version}</version>
</dependency>]]>
</programlisting>

<para>
Note that Spring Social Gowalla may release on a different schedule than Spring Social.
Consequently, Spring Social's version may differ from that of Spring Social Gowalla.
</para>

<para>
Consult <ulink url="http://static.springsource.org/spring-social/docs/1.0.x/reference/html/overview.html#overview-howtoget">Spring Social's reference documentation</ulink> for more information on Spring Social dependencies.
</para>
</section>

</chapter>

0 comments on commit 2003696

Please sign in to comment.