Socializing Spring Applications

Engineering
Craig Walls
November 03, 2010

Increasingly, web surfers are using the internet to connect with friends, family, and colleagues using social networking sites. Conversations that once took place over email are now taking place in short messages written on someone’s Facebook wall or in a brief tweet on Twitter. Connections once made with a handshake are now created using LinkedIn. And when a face-to-face meetings are desired, travel details can be shared using TripIt.

Just as people are using these social networking sites to interact with each other, businesses are also finding ways to inject themselves into the social graph so that they can connect in a more personal way with their customers and also make their web sites an extension of their customers’ social experiences.

This week, we are pleased to have released the first milestone of Spring Social, a new extension to Spring that aims to provide a platform upon which social-ready Spring applications may be built. I thought I’d take this opportunity to introduce you to Spring Social and give you a taste of what it offers.
Securely Sharing Social Data

On the surface, developing applications that interact with the various social networks may appear straightforward. Since most of the social networks offer a REST API, Spring’s RestTemplate would seem to be all you need. But you’ll quickly discover that those social REST APIs are protected by OAuth and that signing a request sent through RestTemplate with OAuth credentials is a non-trivial task.

OAuth is an open protocol that enables a user to share their data hosted on one or more service providers with another application. With access to that data, the application can aggregate, present, and process the information in ways that provide additional value beyond what the service providers themselves ever intended or imagined.

Virtually all of the major service providers support OAuth, including Twitter, Facebook, LinkedIn, TripIt, and Foursquare, as well as the Google and Yahoo APIs. Therefore, OAuth is essential to developing social-ready applications.

At the beginning of an OAuth-secured interaction is a back-and-forth conversation that is commonly known as the “OAuth Dance”. In a typical OAuth Dance, there are three parties involved:

The service provider (such as Twitter or LinkedIn)
The user who wants to access or update data hosted by that service provider.
The consumer application that the user wants to share their data with.

The key steps in this dance are as follows:

The consumer application directs the user to the service provider's site to sign in and authorize the consumer.
Assuming that the user agrees to grant the consumer access to their data, the flow is sent back to the consumer application.
The consumer application receives an access token from the service provider.

The access token received in step 3 is the “valet key” that must accompany any request to the service provider’s REST API. In OAuth 1, this means that the access token, along with the request URL, parameters, and a few other bits of information are collected together in a base string, encrypted, and sent on the request in an Authorization header. Constructing this header and attaching it to the request is a complicated task. This is the reason that using RestTemplate to access OAuth-secured resources is difficult. If you get it wrong, the service provider will respond with an HTTP 401 for any resource you try to access and debugging the encrypted Authorization header is tricky.
Working with Social Templates

A key component of Spring Social is its collection of social templates. These templates (which leverage RestTemplate under the covers) expose operations of the service providers that they model, handling the intricacies of adding OAuth Authorization headers for you.

Spring Social 1.0.0.M1 includes 4 social templates to choose from:

TwitterTemplate
FacebookTemplate
LinkedInTemplate
TripItTemplate

To use any of these templates, simply create an instance of it, providing the OAuth connection details through constructor arguments. For example, to create an instance of TwitterTemplate:

TwitterTemplate twitter = new TwitterTemplate(apiKey, apiSecret, accessToken, accessTokenSecret);

The four parameters to TwitterTemplate’s constructor are all Strings values. The API key and API secret are given to you when you register your application with Twitter (see http://dev.twitter.com/apps/new). The access token and access token secret are granted to your application on a per-user basis at the end of the OAuth Dance with Twitter. At this point, I’m going to assume that you’ve already obtained all four of these values; we’ll circle back to how to manage API keys and tokens a little later.

Creating instances of the other social templates isn’t much different. LinkedInTemplate and TripItTemplate each have constructors with the same argument list as the TwitterTemplate constructor shown above. Since Facebook’s API security is based on OAuth 2, FacebookTemplate has a slightly simpler constructor that only requires the value of the access token:

FacebookTemplate facebook = new FacebookTemplate(accessToken);

Once you have an instance of one of these social templates, what can you do with it? If you’re using TwitterTemplate, perhaps you want to know the authenticated user’s Twitter screen name:

String screenName = twitter.getProfileId();

Or for something a bit more involved, maybe you could send a tweet on behalf of the user:

twitter.updateStatus(“Hey, I’m tweeting with #Spring Social!”);

Similarly, with a FacebookTemplate in hand, you can post to the user’s wall:

facebook.updateStatus(“Spring Social can also post to Facebook!”);

And if you want to examine a user’s upcoming travel itineraries, TripItTemplate’s getTrips() can oblige:

List trips = tripIt.getTrips();
for(Trip trip : trips) {
System.out.println("I’m traveling to " + trip.getPrimaryLocation() +
" on " + trip.getStartDate());
}

This is just a sampling of the kinds of things you can do with Spring Social’s templates. Check out the API documentation to see the other operations that are available.
Managing OAuth Connections

When I created the TwitterTemplate instance above, I glossed over where the API key/secret and the access token came from. Initially, the access token would be received after a user authorizes the application to access their data hosted on the service provider. But you probably don’t want to force your users to perform authorization every time they use your application, so you’ll need a way to store the access tokens long-term for reuse in future sessions.

In its first milestone release Spring Social doesn’t provide an OAuth token management strategy, leaving it up to the application to obtain and manage OAuth details for itself. This is something that we intend to address for 1.0 Milestone 2. In the meantime, however, we can look to Greenhouse for an example of how this might take shape.

In Greenhouse, all of the information about a service provider is stored in a relational database in a ServiceProvider table with the following schema:

As you can see, the ServiceProvider table includes, among other things, the provider’s API key and secret. To access an individual service provider record, Greenhouse uses JdbcServiceProviderFactory, an implementation of a ServiceProvider interface:

package com.springsource.greenhouse.connect;

public interface ServiceProviderFactory {

ServiceProvider getServiceProvider(String name);

<S> ServiceProvider<S> getServiceProvider(String name, Class<S> serviceType);

}

To retrieve a Twitter service provider from the database, Greenhouse simply calls the getServiceProvider() method, passing in “twitter” (the provider’s name) as a parameter. In the case of Twitter, this ultimately returns an instance of TwitterServiceProvider which is an implementation of the ServiceProvider interface.

The ServiceProvider has several methods, but two of them are interesting with regard to token management. The first, connect(), is used by Greenhouse to create a connection between one of its users and their social identity on the service provider:

void connect(Long accountId, AuthorizedRequestToken requestToken);

At the point where the connect() method is called, Greenhouse has gone through enough of the OAuth dance to have an authorized request token in hand. Passing those along with the user’s account ID will create a connection in the AccountConnection table. The AccountConnection table has the following schema:

With the connection having been made, you can use ServiceProvider’s getServiceOperations() method to get an instance of TwitterOperations (the interface that TwitterTemplate is based on):

TwitterOperations twitter = twitterProvider.getServiceOperations(accountId);

Under the covers of getServiceOperations(), the ServiceProvider implementation retrieves the access token and uses it along with its own API key and secret to construct a TwitterTemplate, freeing the application from having to deal with the access token directly.

In Greenhouse, the TwitterOperations instance is a request-scoped bean, created via a factory method in ServiceProvidersApiConfiguration, using Spring JavaConfig like this:

@Bean
@Scope(value=“request”, proxyMode=ScopedProxyMode.INTERFACES)
public TwitterOperations twitter(ServiceProvider twitterProvider, @Value("#{request.getAttribute(‘account’)}") Account account) {

return twitterProvider.getServiceOperations(accountId(account));

}

As a Spring bean, the TwitterOperations can be injected into any other Spring bean that needs to exchange data with Twitter. For instance, in Greenhouse, the EventsController is the Spring MVC controller that handles web interaction for all event-oriented requests. It uses a TwitterOperations to post tweets about an event on the user’s behalf. It is injected with the TwitterOperations bean through its constructor:

@Inject
public EventsController(EventRepository eventRepository, TwitterOperations twitterApi) {
this.eventRepository = eventRepository;
this.twitterApi = twitterApi;
}

As I mentioned, we intend to transition the ServiceProvider facility from Greenhouse to Spring Social in milestone 2. Obviously, the current implementation supports relational storage of OAuth details, but we’re eager to hear from you with ideas on other implementations that maintain OAuth information in other kinds of stores.
Running Greenhouse

Although you can view the running Greenhouse application at http://greenhouse.springsource.org, you’ll probably want to checkout the Greenhouse source code and try it out for yourself as you explore Spring Social. To do that, follow the following steps:

Checkout the Greenhouse source code:
git clone git://git.springsource.org/greenhouse/greenhouse.git
Import the Greenhouse project into SpringSource Tool Suite
Drag the Greenhouse project into the SpringSource tcServer (under the Servers tab) to deploy the application.
Edit the run configuration for tcServer to add "-DspringProfiles=embedded" to the end of the list of VM arguments.
Start the server and access http://localhost:8080/greenhouse in your web browser.

Step 4 is required because Greenhouse uses the new environment beans feature of Spring 3.1, which makes it possible to identify beans that will only be created for certain profiles. Setting that property indicates that the application should be run with the “embedded” profile.
Conclusion

Spring Social 1.0 M1 is the first step in an exciting quest to bring social networking capabilities to Spring. I encourage you to download Spring Social, check out the code, and provide feedback either through issue tracking, the Spring Social Forum, or via the Greenhouse mailing list.
comments powered by Disqus

translate：
翻译：

越来越多的网络冲浪者使用互联网与朋友、家人和同事通过社交网站建立联系。曾经通过电子邮件进行的对话现在都是通过写在某人Facebook墙上的短消息或Twitter上的简短推文进行的。曾经通过握手建立的连接现在是使用LinkedIn创建的。当需要面对面的会议时，可以使用TripIt共享旅行细节。
就像人们使用这些社交网站相互交流一样，企业也在想方设法将自己融入到社交网络中，以便以更个人化的方式与客户建立联系，并使其网站成为客户社交体验的延伸。
本周，我们很高兴发布了SpringSocial的第一个里程碑，这是Spring的一个新扩展，旨在提供一个平台，在此平台上可以构建社交就绪的Spring应用程序。我想借此机会向您介绍一下Spring Social，让您体验一下它的功能。
安全共享社交数据
从表面上看，开发与各种社交网络交互的应用程序可能看起来很简单。由于大多数社交网络都提供REST API，Spring的restemplate似乎是您所需要的全部。但是您很快就会发现，这些社交restapi受OAuth保护，使用OAuth凭据对通过restemplate发送的请求进行签名是一项非常重要的任务。
OAuth是一个开放协议，允许用户与另一个应用程序共享其托管在一个或多个服务提供商上的数据。有了对这些数据的访问，应用程序可以聚合、呈现和处理这些信息，从而提供超出服务提供者自己所期望或想象的附加价值。
几乎所有的主要服务提供商都支持OAuth，包括Twitter、Facebook、LinkedIn、TripIt和Foursquare，以及Google和yahooapi。因此，OAuth对于开发面向社会的应用程序至关重要。