Spring Social Connect - Upcoming 1.0.0.M3 API

connect-m3.txt

2. Service Provider 'Connect' Framework

The spring-social-core module includes a Service Provider 'Connect' Framework for managing connections to Software-as-a-Service (SaaS) providers such as Facebook and Twitter. This framework allows your application to establish connections between local user accounts and accounts those users have with external service providers. Once a connection is established, it can be be used to obtain a strongly-typed Java binding to the ServiceProvider's API, giving your application the ability to invoke the API on behalf of a user.

To illustrate, consider Facebook as an example ServiceProvider. Suppose your application, AcmeApp, allows users to share content with their Facebook friends. To support this, a connection needs to be established between a user's AcmeApp account and her Facebook account. Once established, a FacebookApi instance can be obtained and used to post content to the user's wall. Spring Social's 'Connect' framework provides a clean API for managing service provider connections such as this.

2.1 Core API

The ServiceProviderConnection<S> interface models a connection to an external service provider such as Facebook:

public interface ServiceProviderConnection<S> {
    
    ServiceProviderConnectionKey getKey();
    
    String getDisplayName();

    String getProfileUrl();

    String getImageUrl();

    void sync();

    boolean test();

    boolean hasExpired();

    void refresh();

    ServiceProviderUserProfile fetchUserProfile();

    void updateStatus(String message);

    S getServiceApi();

    ServiceProviderConnectionData createData();

}
			
Each ServiceProviderConnection is uniquely identified by a composite key consisting of a providerId (e.g. 'facebook') and connected providerUserId (e.g. '1255689239', for Keith Donald's Facebook ID). This key tells you what provider user the connection is connected to.

A connection has a number of meta-properties that can be used to render it on a screen, including a displayName, profileUrl, and imageUrl. As an example, the following HTML template snippet could be used to generate a link to the connected user's profile on the provider's site:

<img src="${connection.imageUrl}" /> <a href="${connection.profileUrl}">${connection.displayName}</a>
			
			
The value of these properties may depend on the state of the provider user's profile. In this case, sync() can be used to synchronize these values if the user's profile is updated.

A connection can be tested to determine if its authorization credentials are valid. If invalid, the connection may have expired or been revoked by the provider. If the connection has expired, a connection may be refreshed to renew its authorization credentials.

A connection provides several operations that allow the client application to invoke the ServiceProvider's API in a uniform way. This includes the ability to fetch a model of the user's profile and update the user's status in the provider's system.

A connection's parameterized type <S> represents the Java binding to the ServiceProvider's native API. An instance of this API binding can be obtained by calling getServiceApi(). As an example, a Facebook connection instance would be parameterized as ServiceProviderConnection<FacebookApi>. getServiceApi() would return a FacebookApi instance that provides a Java binding to Facebook's graph API for a specific Facebook user.

Finally, the internal state of a connection can be captured for transfer between layers of your application by calling createData(). This could be used to persist the connection in a database, or serialize it over the network.

To put this model into action, suppose we have a reference to a ServiceProviderConnection<TwitterApi> instance. Suppose the connected user is the Twitter user with screen name 'kdonald'.

ServiceProviderConnection#getKey() would return ('twitter', '14718006') where '14718006' is @kdonald's Twitter-assigned user id that never changes.

ServiceProviderConnection#getDisplayName() would return '@kdonald'.

ServiceProviderConnection#getProfileUrl() would return 'http://twitter.com/kdonald'.

ServiceProviderConnection#getImageUrl() would return 'http://a0.twimg.com/profile_images/105951287/IMG_5863_2_normal.jpg'.

ServiceProviderConnection#sync() would synchronize the state of the connection with @kdonald's profile.

ServiceProviderConnection#test() would return true indicating the authorization credentials associated with the Twitter connection are valid. This assumes Twitter has not revoked the AcmeApp client application, and @kdonald has not reset his authorization credentials (Twitter connections do not expire).

ServiceProviderConnection#hasExpired() would return false.

ServiceProviderConnection#refresh() would not do anything since connections to Twitter do not expire.

ServiceProviderConnection#fetchUserProfile() would make a remote API call to Twitter to get @kdonald's profile data and normalize it into a ServiceProviderUser model.

ServiceProviderConnection#updateStatus(String) would post a status update to @kdonald's timeline.

ServiceProviderConnection#getServiceApi() would return a TwitterApi giving the client application access to the full capabilities of Twitter's native API.

ServiceProviderConnection#createData() would return a ServiceProviderConnectionData that could be serialized and used to restore the connection at a later time.