From cf7e538e9365977a26fd0e3ca55813d93c754286 Mon Sep 17 00:00:00 2001
From: Craig Walls <cwalls@vmware.com>
Date: Mon, 22 Aug 2011 14:34:39 -0500
Subject: [PATCH] Reference doc updates

---
 docs/src/reference/docbook/connecting.xml     | 11 +++++---
 docs/src/reference/docbook/overview.xml       |  2 ++
 .../src/reference/docbook/serviceprovider.xml | 26 ++++++++++++++++++-
 3 files changed, 34 insertions(+), 5 deletions(-)

diff --git a/docs/src/reference/docbook/connecting.xml b/docs/src/reference/docbook/connecting.xml
index e0feb953d..014e4f3ec 100644
--- a/docs/src/reference/docbook/connecting.xml
+++ b/docs/src/reference/docbook/connecting.xml
@@ -540,25 +540,28 @@ public class SocialConfig {
 		<programlisting language="java"><![CDATA[
 public interface ConnectInterceptor<A> {
 	
-    void preConnect(ConnectionFactory<A> connectionFactory, WebRequest request);
+    MultiValueMap<String, String> preConnect(ConnectionFactory<A> connectionFactory, WebRequest request);
 
     void postConnect(Connection<A> connection, WebRequest request);
 	
 }]]>
 		</programlisting>
 		<para>
-			The <methodname>preConnect()</methodname> method will be called by <classname>ConnectController</classname> just before redirecting the browser to the provider's authorization page. 
+			The <methodname>preConnect()</methodname> method will be called by <classname>ConnectController</classname> just before redirecting the browser to the provider's authorization page.
+			It has a return type of <code>MultiValueMap&lt;String, String&gt;</code> which can contain parameters to be passed on the request when <classname>ConnectController</classname> redirects to the provider's authorization URL.
+			If it has no parameters to contribute to the authorization URL, it may return <code>null</code>.  
 			<methodname>postConnect()</methodname> will be called immediately after a connection has been persisted linking the user's local account with the provider profile.
 		</para>
 		<para>
-			For example, suppose that after connecting a user account with their Twitter profile , you want to immediately post a tweet about that connection to the user's Twitter timeline. 
+			For example, suppose that after connecting a user account with their Twitter profile you want to immediately post a tweet about that connection to the user's Twitter timeline. 
 			To accomplish that, you might write the following connection interceptor:
 		</para>
 		<programlisting language="java"><![CDATA[
 public class TweetAfterConnectInterceptor implements ConnectInterceptor<Twitter> {
 
-    public void preConnect(ConnectionFactory<TwitterApi> provider, WebRequest request) {
+    public MultiValueMap<String, String> preConnect(ConnectionFactory<TwitterApi> provider, WebRequest request) {
         // nothing to do
+        return null;
     }
 
     public void postConnect(Connection<TwitterApi> connection, WebRequest request) {
diff --git a/docs/src/reference/docbook/overview.xml b/docs/src/reference/docbook/overview.xml
index 802dd0144..6f31bade7 100644
--- a/docs/src/reference/docbook/overview.xml
+++ b/docs/src/reference/docbook/overview.xml
@@ -326,9 +326,11 @@ git clone git://github.com/SpringSource/spring-social-samples.git
 		
 		<itemizedlist>
 			<listitem><para>spring-social-quickstart - Designed to get you up and running quickly.</para></listitem>
+			<listitem><para>spring-social-quickstart-30x - Designed to get you up and running quickly as well as using Spring Social with Spring 3.0.x.</para></listitem>
 			<listitem><para>spring-social-showcase - Illustrates most of Spring Social's features.</para></listitem>
 			<listitem><para>spring-social-movies - Shows how to extend Spring Social to implement a new ServiceProvider and API binding.</para></listitem>
 			<listitem><para>spring-social-twitter4j - Shows how to extend Spring Social and re-use an existing API binding.</para></listitem>
+			<listitem><para>spring-social-popup - Shows how to use Spring Social to drive a browser popup-based connection flow.</para></listitem>
 		</itemizedlist>
 	</section>
 </chapter>
\ No newline at end of file
diff --git a/docs/src/reference/docbook/serviceprovider.xml b/docs/src/reference/docbook/serviceprovider.xml
index db013b63b..5f881697a 100644
--- a/docs/src/reference/docbook/serviceprovider.xml
+++ b/docs/src/reference/docbook/serviceprovider.xml
@@ -464,9 +464,33 @@ public interface UsersConnectionRepository {
 			<title>JDBC-based persistence</title>
 			<para>
 				Spring Social provides a JdbcUsersConnectionRepository implementation capable of persisting connections to a RDBMS.
-				The database schema designed to back this repository is defined in JdbcUsersConnectionRepository.sql.
+				The database schema designed to back this repository is defined as follows:
+			</para>
+			
+  			<programlisting language="sql"><![CDATA[
+create table UserConnection (userId varchar(255) not null,
+    providerId varchar(255) not null,
+    providerUserId varchar(255),
+    rank int not null,
+    displayName varchar(255),
+    profileUrl varchar(512),
+    imageUrl varchar(512),
+    accessToken varchar(255) not null,					
+    secret varchar(255),
+    refreshToken varchar(255),
+    expireTime bigint,
+    primary key (userId, providerId, providerUserId));
+create unique index UserConnectionRank on UserConnection(userId, providerId, rank);]]>
+  			</programlisting>
+
+			<para>
+				For convenience is bootstrapping the schema from a running application, this schema definition is available in the <code>spring-social-core</code> module as a resource at the path /org/springframework/social/connect/jdbc/JdbcUsersConnectionRepository.sql.				
+			</para>
+
+			<para>
 				The implementation also provides support for encrypting authorization credentials so they are not stored in plain-text.
 			</para>
+			
 			<para>
 				The example code below demonstrates construction and usage of a JdbcUsersConnectionRepository:
 			</para>