The Spring Social project enables your applications to establish Connections with Software-as-a-Service (SaaS) Providers such as Facebook and Twitter to invoke APIs on behalf of Users.
The phrase "social networking" often refers to efforts aimed at bringing people together. In the software world, those efforts take the form of online social networks such as Facebook, Twitter, and LinkedIn. Over half a billion of this world's internet users have flocked to these services to keep frequent contact with family, friends, and colleagues.
Under the surface, however, these services are just software applications that gather, store, and process information. Just like so many applications written before, these social networks have users who sign in and perform some activity offered by the service.
What makes these applications a little different than traditional applications is that the data that they collect represent some facet of their users' lives. What's more, these applications are more than willing to share that data with other applications, as long as the user gives permission to do so. This means that although these social networks are great at bringing people together, as software services they also excel at bringing applications together.
To illustrate, imagine that Paul is a member of an online movie club. A function of the movie club application is to recommend movies for its members to watch and to let its members maintain a list of movies that they have seen and those that they plan to see. When Paul sees a movie, he signs into the movie club site, checks the movie off of his viewing list, and indicates if he liked the movie or not. Based on his responses, the movie club application can tailor future recommendations for Paul to see.
On its own, the movie club provides great value to Paul, as it helps him choose movies to watch. But Paul is also a Facebook user. And many of Paul's Facebook friends also enjoy a good movie now and then. If Paul were able to connect his movie club account with his Facebook profile, the movie club application could offer him a richer experience. Perhaps when he sees a movie, the application could post a message on his Facebook wall indicating so. Or when offering suggestions, the movie club could factor in the movies that his Facebook friends liked.
Social integration is a three-way conversation between a service provider, a service consumer, and a user who holds an account on both the provider and consumer. All interactions between the consumer and the service provider are scoped to the context of the user's profile on the service provider.
In the narrative above, Facebook is the service provider, the movie club application is the service consumer, and Paul is the user of both. The movie club application may interact with Facebook on behalf of Paul, accessing whatever Facebook data and functionality that Paul permits, including retrieving Paul's friends and posting messages to his wall.
From the user's perspective, both applications provide some valuable functionality. But by connecting the user's account on the consumer application with his account on the provider application, the user brings together two applications that can now offer the user more value than they could individually.
With Spring Social, your application can play the part of the service consumer, interacting with a service provider on behalf of its users. The key features of Spring Social are:
A "Connect Framework" that handles the core authorization and connection flow with service providers.
A "Connect Controller" that handles the OAuth exchange between a service provider, consumer, and user in a web application environment.
A "Signin Controller" that allows users to authenticate with your application by signing in with their Provider accounts, such as their Twitter or Facebook accounts.
In addition, there are a handful of provider-specific modules that extend Spring Social to enable integration with popular SaaS providers, including Facebook and Twitter.
The core Spring Social project consists of the modules described in Table 1.1, “Spring Social Modules”.
Table 1.1. Spring Social Modules
| Name | Description |
|---|---|
| spring-social-core | Spring Social's Connect Framework and OAuth client support. |
| spring-social-web | Spring Social's ConnectController which uses the Connect Framework to manage connections in a web application environment. |
| spring-social-test | Support for testing Connect implementations and API bindings. |
Which of these modules your application needs will largely depend on what facets of Spring Social you intend to use. At very minimum, you'll need the core module in your application's classpath:
<dependency> <groupId>org.springframework.social</groupId> <artifactId>spring-social-core</artifactId> <version>${spring-social.version}</version> </dependency>
To let Spring Social handle the back-and-forth authorization handshake between your web application and a service provider, you'll need the web module:
<dependency> <groupId>org.springframework.social</groupId> <artifactId>spring-social-web</artifactId> <version>${spring-social.version}</version> </dependency>
If you're developing your own client module (Chapter 3, Adding Support for a New Service Provider) and API binding, you'll need the test module to test it:
<dependency> <groupId>org.springframework.social</groupId> <artifactId>spring-social-test</artifactId> <version>${spring-social.version}</version> </dependency>
If you are developing against a milestone or release candidate version, such as 1.0.0.M1 or 1.0.0.RC1, you will need to add the following repository in order to resolve the artifact:
<repository> <id>org.springframework.maven.milestone</id> <name>Spring Maven Milestone Repository</name> <url>http://maven.springframework.org/milestone</url> </repository>
If you are testing out the latest nightly build version (e.g. 1.0.0.BUILD-SNAPSHOT), you will need to add the following repository:
<repository> <id>org.springframework.maven.snapshot</id> <name>Spring Maven Snapshot Repository</name> <url>http://maven.springframework.org/snapshot</url> </repository>
In addition to modules that make up the core Spring Social project, there are a number of provider-specific client modules that are released separately that provide connectivity and API bindings to popular SaaS providers. These client modules are listed in Table 1.2, “Spring Social Client Modules”.
Table 1.2. Spring Social Client Modules
| Name | Maven group ID | Maven artifact ID |
|---|---|---|
| Spring Social Facebook | org.springframework.social | spring-social-facebook |
| Spring Social Twitter | org.springframework.social | spring-social-twitter |
| Spring Social LinkedIn | org.springframework.social | spring-social-linkedin |
| Spring Social TripIt | org.springframework.social | spring-social-tripit |
| Spring Social GitHub | org.springframework.social | spring-social-github |
All of these modules are optional, depending on the connectivity needs of your application. For instance, if your application will connect with Facebook, you'll want to add the Facebook module to your project:
<dependency> <groupId>org.springframework.social</groupId> <artifactId>spring-social-facebook</artifactId> <version>${spring-social-facebook.version}</version> </dependency>
Note that each of the client modules will progress and release on a different schedule than Spring Social. Consequently, the version numbers for any given client module may not align with Spring Social or any other client module.
Refer to each client module's reference documentation for details on connectivity and the API binding.
Spring Social depends on a few things to run. Most dependencies are optional and an effort has been made to keep the required dependencies to a minimum. The project dependencies are described in this section.
The Spring Social web support requires Java Servlet 2.5 or greater (Tomcat 6+).
Spring Social depends on RestTemplate provided by the core Spring Framework in the spring-web module. It requires Spring Framework version 3.0.5 or above. Spring Framework 3.1 is recommended to take advantage of several RestTemplate improvements.
If you are using Spring Social with Spring Framework 3.0.5 or >, make sure you explicitly add the spring-web dependency to your build:
<dependency> <groupId>org.springframework</groupId> <artifactId>spring-web</artifactId> <version>3.0.6.RELEASE</version> </dependency>
Maven's dependency management favors "nearest" dependencies, so your project's definition of the spring-web dependency will override Spring Social's transitive dependency on the recommended 3.1 version.
Gradle, on the other hand, favors the newest dependency.
If you're using Gradle to build your project, you'll need to also set the dependency's force property to true to force Gradle to resolve your chosen version of Spring:
dependencies {
compile ("org.springframework:spring-web:3.0.6.RELEASE") { force=true }
}
If you're not already using Spring Security to secure your application, you'll need to add the standalone crypto module. This is required for OAuth1 request signing and encrypting credentials when persisting Connection data. If you're already using Spring Security, there is nothing for you to do because the crypto library comes included.
<dependency> <groupId>org.springframework.security</groupId> <artifactId>spring-security-crypto</artifactId> <version>3.1.0.RC3</version> </dependency>
Spring Social has an optional dependency on Apache HttpComponents. If the HttpComponents HttpClient library is present, it will use it as the HTTP client (which is generally recommended). Otherwise, it will fall back on standard J2SE facilities.
<dependency> <groupId>org.apache.httpcomponents</groupId> <artifactId>httpclient</artifactId> <version>4.1.2</version> </dependency>
Although shown here to depend on version 4.1.1 of the HttpClient library, Spring Social can also with with 4.0.X versions of HttpClient.
Spring Social's provider API bindings rely on the Jackson JSON Processor to map JSON responses to Java objects. Each binding, such as Facebook or Twitter, transitively depends on Jackson 1.8.5, so there's nothing special to do to add Jackson to your project's Maven or Gradle build.
We have created a few sample applications to illustrate the capabilities of Spring Social. To obtain the https://github.com/SpringSource/spring-social-samples code, use the following git command:
git clone git://github.com/SpringSource/spring-social-samples.git
The Spring Social Samples project includes the following samples:
spring-social-quickstart - Designed to get you up and running quickly.
spring-social-quickstart-30x - Designed to get you up and running quickly as well as using Spring Social with Spring 3.0.x.
spring-social-showcase - Illustrates most of Spring Social's features.
spring-social-movies - Shows how to extend Spring Social to implement a new ServiceProvider and API binding.
spring-social-twitter4j - Shows how to extend Spring Social and re-use an existing API binding.
spring-social-popup - Shows how to use Spring Social to drive a browser popup-based connection flow.
spring-social-canvas - Demonstrates how to use Spring Social within a Facebook Canvas application.