Introduction

A Facebook API client implemented in Java, derived from the poorly-maintained official Facebook client.

Note that as of May 2008, Facebook has discontinued any support of their official Java client, directing users interested developing Facebook applications in Java to use one of the various third-party clients out there. As such, the purpose of this project is now to maintain, support, and extend the abandoned codebase to provide a high-quality, up to date version of the Facebook API client for Java developers, and to keep the Java client up to date as the Facebook Platform API changes and evolves.

In this project, we strive to preserve backwards compatibility between releases, and to be drop-in compatible for anyone using the "official" Facebook Java API client, insofar as is possible. However, Facebook is not particularly shy about changing thier platform API in ways that introduce breaking changes for developers, so there is no guarantee that compatibility can be preserved 100% of the time going forward. If that bothers you as much as it bothers me, I encourage you to complain to Facebook's development team and urge them to give a higher priority to issues of backwards compatibility when they are refactoring their platform API.

So while we strive to retain backwards compatibility in each new release, the need to keep the Java client compatible with the latest changes made to the Facebook Platform may override this goal. There's little sense in retaining compatibility with a client that won't even work properly, so the need to support the latest version of the Facebook Platform API may override backwards compatibility from time to time.

For more information, please download the README file or check out the latest project javadoc.

About the Beta

As discussed on the following page:

http://wiki.developers.facebook.com/index.php/New_Design_Platform_Changes

...Facebook is in the process of rolling out some substantial changes to portions of their API. Namely, the way applications integrate with the user's profile page and feeds, and how sessions are handled.

As of version 1.8-final, the beta process is considered over. The only feature that remains unverified in the Permissions API. Everything else should be working. If you find that it is not, please submit a bug report. Thanks.

Quick Start

1. Download the latest project JAR file at http://facebook-java-api.googlecode.com/files/facebook-java-api-1.8-final.jar

2. Download the required JSON library at http://facebook-java-api.googlecode.com/files/json-1.0.jar

3. If (and only if) you are using Java 5, also download the following libraries:

4. If you (and only if) will be running your application in an environment that does not automatically include the Sun activation framework (nearly all application servers will do this by default), also download the following library:

5. Deploy all of the downloaded JAR files onto your application server, or otherwise place them on your runtime classpath. This will allow you to use the Facebook Platform API.

6. If you need help using the API, consult the Project Javadoc, or scroll down for code examples.

Companion Utility (non-desktop apps)

As of v1.6.1, there is an optional companion JAR that enables additional enhanced features for FBML/Iframe apps. In essence, it provides many of the convenience methods that PHP Facebook developers have had available for some time now, such as automatic signature verification, and a simplified login API.

The companion utility relies on the servlet-api (which is why desktop apps cannot use it), so it requires a small amount of extra setup:

1. Configure the Facebook Java API by following the instructions above.

2. Download the latest companion JAR file at http://facebook-java-api.googlecode.com/files/facebook-util-1.8-final.jar.

3. Download the required servlet-api library at http://facebook-java-api.googlecode.com/files/servlet-api-2.4.jar.

4. Deploy all of the downloaded JAR files onto your application server, or otherwise place them on your runtime classpath. This will allow you to use the companion utility.

5. If you need help using the API, consult the Companion Utility Javadoc.

Additional details regarding the use of this utility can be found in the discussion group.

Comparison Matrix

Project Changelog

Code Examples

Getting a User's Friends:

    FacebookRestClient client = new FacebookRestClient("apiKey", "secretKey", "sessionId");
    client.friends_get();
    FriendsGetResponse response = (FriendsGetResponse)client.getResponsePOJO();
    List<Long> friends = response.getUid();

Executing a Batch Query

    //set the client to run in batch mode
    client.beginBatch();
            
    //these commands will be batched
    client.users_getLoggedInUser();
    client.friends_get();
            
    //execute the batch (which also terminates batch mode until beginBatch is called again)
    List<? extends Object> batchResponse = client.executeBatch(false);
            
    //the list contains the results of the queries, in the same order they were defined
    Long userId = (Long) batchResponse.get(0);
    Document friends = (Document)batchResponse.get(1);
    NodeList nodes = friends.getElementsByTagName("uid");
            
    //print the results
    System.out.println("USER:  " + userId);
    for (int index = 0; index < nodes.getLength(); index++) {
        System.out.println("FRIEND:  " + nodes.item(index).getFirstChild().getTextContent());
    }

Update a User's Status Message:

    if (client.users_hasAppPermission(Permission.STATUS_UPDATE)) {
        client.users_setStatus("developing Facebook apps in Java because the new Java client kicks the PHP client's ass!", false);
    }

Send SMS to a User:

    FacebookRestClient client = new FacebookRestClient("apiKey", "secretKey", "sessionId");
    if (client.sms_canSend()) {
        client.sms_send("I can send you text messages now!", null, false);
    }

Publishing a Templatized Feed Entry:

    //using the TemplatizedAction utility class helps keep things sane
    TemplatizedAction action = new TemplatizedAction("{actor} recommends {book}");                      //the user has recommended a book

    action.addTitleParam("book", "<a href='http://www.amazon.com/Hamlet/dp/0140714545/'>Hamlet</a>");   //specify the specific book
    action.setBodyTemplate("{actor} is using BooksApp!");                                               //set a body template (optional)
    action.setBodyGeneral("100 other people recommend this book!");                                     //set general body content (optional)
    action.addPicture("http://code.google.com/hosting/images/code_sm.png", "http://www.google.com");    //add up to 4 pictures (optional)
    action.addPicture("http://code.google.com/hosting/images/code_sm.png", "http://www.google.com");
    action.addPicture("http://code.google.com/hosting/images/code_sm.png", "http://www.google.com");
    action.addPicture("http://code.google.com/hosting/images/code_sm.png", "http://www.google.com");
    
    client.feed_PublishTemplatizedAction(action);                                                       //publish to feed

Playing With User Preferences:

    FacebookRestClient client = new FacebookRestClient("apiKey", "secretKey", "sessionId");
    Map<Integer, String> prefs = client.data_getUserPreferences();
    
    //show any preferences that are currently set for the user, all at once
    System.out.println("Preferences already set:");
    for (Integer key : prefs.keySet()) {
        System.out.println("\tkey " + key + " = " + prefs.get(key));
    }
        
    //set the values of some preferences, one at a time    
    client.data_setUserPreference(1, "test1");
    client.data_setUserPreference(2, "test2");
    client.data_setUserPreference(3, "0");
    
    //retrieve some of the set values, one at a time    
    System.out.println("Preference 2 is:  " + client.data_getUserPreference(2));
    System.out.println("Preference 1 is:  " + client.data_getUserPreference(1));
        
    //retrieve all the values at once
    System.out.println("All current preferences:");
    prefs = client.data_getUserPreferences();
    for (Integer key : prefs.keySet()) {
        System.out.println("\tkey " + key + " = " + prefs.get(key));
    }
        
    //set several new preference values at once, preserving any existing values    
    Map<Integer, String> vals = new HashMap<Integer, String>();
    vals.put(4, "test4");
    vals.put(5, "test5");
    vals.put(6, "test6");
    client.data_setUserPreferences(vals, false);

    //retrieve all the values at once
    System.out.println("All current preferences:");
    prefs = client.data_getUserPreferences();
    for (Integer key : prefs.keySet()) {
        System.out.println("\tkey " + key + " = " + prefs.get(key));
    }
    
    //set several new preference values at once, *removing* any existing values   
    client.data_setUserPreferences(vals, true);
    
    //retrieve all the values at once (to show that anything not in 'vals' is now gone) 
    System.out.println("All current preferences:");
    prefs = client.data_getUserPreferences();
    for (Integer key : prefs.keySet()) {
        System.out.println("\tkey " + key + " = " + prefs.get(key));
    }