connecting.xml

<?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 SocialConfig {
	
    @Bean
    public ConnectionFactoryLocator connectionFactoryLocator() {
        ConnectionFactoryRegistry registry = new ConnectionFactoryRegistry();
        registry.addConnectionFactory(new GowallaConnectionFactory(
            environment.getProperty("gowalla.clientId"),
            environment.getProperty("gowalla.clientSecret")));
        return registry;
    }

}
]]></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>.
	</para>
	
	<para>
		Because client IDs and secrets may be different across environments (e.g., test, production, etc) it is recommended that these values be externalized. 
		As shown here, Spring 3.1's <interfacename>Environment</interfacename> is used to look up the application's client ID and secret.
	</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.
		As in the Java-based configuration, the application's consumer key and secret are externalized (shown here as property placeholders).
	</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>