Spring Social Facebook Reference

The Spring Social Facebook project is an extension to Spring Social that enables integration with Facebook.

1. Introduction

With over 700 million users (and growing), Facebook is the largest online social network. While bringing together friends and family, Facebook also offers a rich platform on which to develop applications.

Spring Social Facebook enables integration with Facebook with FacebookConnectionFactory, a connection factory that can be plugged into Spring Social’s service provider connection framework, and with an API binding to Facebook’s REST API.

1.1. How to get

The following Gradle dependency will add Spring Social Facebook to your project:

build.gradle

compile "org.springframework.social:spring-social-facebook:2.0.3.RELEASE"

Or in Maven:

pom.xml

<dependency>
  <groupId>org.springframework.social</groupId>
  <artifactId>spring-social-facebook</artifactId>
  <version>2.0.3.RELEASE</version>
</dependency>

As an extension to Spring Social, Spring Social Facebook depends on Spring Social. Spring Social’s core module will be transitively resolved from the Spring Social Facebook dependency. If you’ll be using Spring Social’s web module, you’ll need to add that dependency yourself. In Gradle:

build.gradle

compile "org.springframework.social:spring-social-web:1.1.4.RELEASE"

Or in Maven:

pom.xml

<dependency>
  <groupId>org.springframework.social</groupId>
  <artifactId>spring-social-web</artifactId>
  <version>1.1.4.RELEASE</version>
</dependency>

Note that Spring Social Facebook may release on a different schedule than Spring Social. Consequently, Spring Social’s version may differ from that of Spring Social Facebook.

Consult Spring Social’s reference documentation for more information on Spring Social dependencies.

2. Configuring Facebook Connectivity

Spring Social’s ConnectController works with one or more provider-specific ConnectionFactory instances to exchange authorization details with the provider and to create connections. Spring Social Facebook provides FacebookConnectionFactory, a ConnectionFactory for creating connections with Facebook.

So that ConnectController can find FacebookConnectionFactory, it must be registered with a ConnectionFactoryRegistry. The following configuration class uses Spring Social’s Java configuration support to register a ConnectionFactory for Facebook:

@Configuration
public class SocialConfig implements SocialConfigurer {

    @Override
    public void addConnectionFactories(ConnectionFactoryConfigurer cfConfig, Environment env) {
        cfConfig.addConnectionFactory(new FacebookConnectionFactory(
            env.getProperty("facebook.clientId"),
            env.getProperty("facebook.clientSecret")));
    }

    ...
}

If we wanted to add support for connecting to other providers, we would simply register their connection factories here in the same way as FacebookConnectionFactory.

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’s Environment abstraction is provided as a parameter to addConnectionFactories() so that it can look up the application’s client ID and secret.

Optionally, you may also configure FacebookConnectionFactory in XML. Using Spring Social Facebook’s XML configuration namespace:

<facebook:config app-id="${facebook.clientId}"
                 app-secret="${facebook.clientSecret}"
                 app-namespace="socialshowcase" />

This is roughly equivalent to the Java-based configuration of ConnectionFactoryRegistry shown before. As in the Java-based configuration, the application’s client ID and secret are externalized (shown here as property placeholders).

Refer to Spring Social’s reference documentation for complete details on configuring ConnectController and its dependencies.

3. Facebook API Binding

Spring Social Facebook’s Facebook interface and its implementation, FacebookTemplate provide the operations needed to interact with Facebook on behalf of a user. Creating an instance of FacebookTemplate is as simple as constructing it by passing in an authorized access token to the constructor:

String accessToken = "f8FX29g..."; // access token received from Facebook after OAuth authorization
Facebook facebook = new FacebookTemplate(accessToken);

FacebookTemplate has a similar constructor that also takes an application namespace in addition to the access token:

String accessToken = "f8FX29g..."; // access token received from Facebook after OAuth authorization
Facebook facebook = new FacebookTemplate(accessToken, "myapp");

The application namespace is required for working with any of Facebook’s OpenGraph operations. If you won’t be using any OpenGraph operations, then you can use the simpler constructor that only requires an access token.

If you are using Spring Social’s service provider framework, you can get an instance of Facebook from a Connection. For example, the following snippet calls getApi() on a Connection to retrieve a Facebook instance:

Connection<Facebook> connection = connectionRepository.findPrimaryConnection(Facebook.class);
Facebook facebook = connection != null ? connection.getApi() : null;

Here, ConnectionRepository is being asked for the primary connection that the current user has with Facebook. If a connection to Facebook is found, a call to getApi() retrieves a Facebook instance that is configured with the connection details received when the connection was first established. If there is no connection, then no Facebook instance can be obtained.

With a Facebook in hand, there are several ways you can use it to interact with Facebook on behalf of the user. Spring Social’s Facebook API binding is divided into 13 sub-APIs exposes through the methods of the Facebook interface:

public interface Facebook extends GraphApi, ApiBinding {

  AchievementOperations achievementOperations();

  CommentOperations commentOperations();

  EventOperations eventOperations();

  FeedOperations feedOperations();

  FriendOperations friendOperations();

  GroupOperations groupOperations();

  LikeOperations likeOperations();

  MediaOperations mediaOperations();

  OpenGraphOperations openGraphOperations();

  PageOperations pageOperations();

  SocialContextOperations socialContextOperations();

  TestUserOperations testUserOperations();

  UserOperations userOperations();

  RestOperations restOperations();

  String getApplicationNamespace();

}

The sub-API interfaces returned from Facebook’s methods are described in Facebook’s Sub-APIs.

Table 1. Facebook’s Sub-APIs
Sub-API Interface	Description
`AchievementOperations`	Operations for working with Facebook achievements.
`CommentOperations`	Add, delete, and read comments on Facebook objects.
`EventOperations`	Create and maintain events and RSVP to event invitations.
`FeedOperations`	Read and post to a Facebook wall.
`FriendOperations`	Retrieve a user’s friends and maintain friend lists.
`GroupOperations`	Retrieve group details and members.
`LikeOperations`	Retrieve a user’s interests and likes. Like and unlike objects.
`MediaOperations`	Maintain albums, photos, and videos.
`OpenGraphOperations`	Operations against Facebook’s OpenGraph API.
`PageOperations`	Operations against a Facebook page.
`SocialContextOperations`	Operations for querying against a user’s social context.
`TestUserOperations`	Operations for creating and working with test users.
`UserOperations`	Retrieve user profile data and profile images.

Notice that in addition to the 13 sub-APIs, Facebook's restOperations() method will return a RestOperations (e.g., a RestTemplate) that is instrumented to place an OAuth Authorization header for the provided access token on any request it sends.

The following sections will give an overview of common tasks that can be performed via Facebook and its sub-APIs. For complete details on all of the operations available, refer to the JavaDoc.

3.1. Retrieving a user’s profile data

You can retrieve the authenticated user’s Facebook profile data using the Facebook#userOperations.getUserProfile() method:

User profile = facebook.userOperations().getUserProfile();

The User object will contain basic profile information about the authenticating user, including their first and last name and their Facebook ID. Depending on what authorization scope has been granted to the application, it may also include additional details about the user such as their email address, birthday, hometown, and religious and political affiliations. For example, getBirthday() will return the current user’s birthday if the application has been granted "user_birthday" permission; null otherwise. Consult the JavaDoc for User for details on which permissions are required for each property.

You can also ask for a Facebook profile for a specific Facebook user (not necessarily the authenticated user) by passing a user ID (or Facebook alias) to getUserProfile():

User profile = facebook.userOperations().getUserProfile("4");

3.2. Getting a user’s Facebook friends

An essential feature of Facebook and other social networks is creating a network of friends or contacts. You can access the user’s list of Facebook friends by calling the getFriendIds() method from FriendOperations:

List<String> friendIds = facebook.friendOperations().getFriendIds();

This returns a list of Facebook IDs belonging to the current user’s list of friends who are also using the same application. This is just a list of String IDs, so to retrieve an individual user’s profile data, you can turn around and call getUserProfile(), passing in one of those IDs to retrieve the profile data for an individual user:

User firstFriend = facebook.userOperations().getUserProfile(friendIds.get(0));

Or you can get a list of user’s friends as User by calling getFriendProfiles():

List<User> friends = facebook.friendOperations().getFriendProfiles();

Facebook also enables users to organize their friends into friend lists. To retrieve a list of the authenticating user’s friend lists, call getFriendLists() with no arguments:

List<Reference> friends = facebook.friendOperations().getFriendLists();

You can also retrieve a list of friend lists for a specific user by passing the user ID (or an alias) to getFriendLists():

List<Reference> friends = facebook.friendOperations().getFriendLists("habuma");

getFriendLists() returns a list of Reference objects that carry the ID and name of each friend list.

To retieve a list of friends who are members of a specific friend list call getFriendListMembers(), passing in the ID of the friend list:

List<Reference> friends = facebook.friendOperations().getFriendListMembers("193839228");

3.3. Posting to and reading feeds

To post a message to the user’s Facebook wall, call FeedOperations' updateStatus() method, passing in the message to be posted:

facebook.feedOperations().updateStatus("I'm trying out Spring Social!");

If you’d like to attach a link to the status message, you can do so by passing a PostData to the post() method:

FacebookLink link = new FacebookLink("http://www.springsource.org/spring-social",
        "Spring Social",
        "The Spring Social Project",
        "Spring Social is an extension to Spring to enable applications to connect with service providers.");
facebook.feedOperations().post("I'm trying out Spring Social!", link);
facebook.feedOperations().post(new PostData("me").message("I'm trying out Spring Social!")
    .link("http://www.springsource.org/spring-social", null, "Spring Social", "The Spring Social Project", "Spring Social is an extension to Spring to enable applications to connect with service providers."));

When calling the link() method on a PostData object, the first parameter is the link’s URL, the second parameter is a picture to associate with the link (overriding any picture that Facebook would find from the page at the URL given), the third parameter is the name of the link, the fourth parameter is a caption, and the fifth is a description of the link.

If you want to read posts from a user’s feed, FeedOperations has several methods to choose from. The getFeed() method retrieves recent posts to a user’s wall. When called with no parameters, it retrieves posts from the authenticating user’s wall:

List<Post> feed = facebook.feedOperations().getFeed();

The getFeed() method returns a list of Post objects.