Introduction

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

The purpose of this project is to provide a high-quality, more up to date version of the Facebook API client for Java developers, and to allow it to be maintained regularly over time to maintain support as the Facebook Platform API changes and evolves.

One of the most important goals for this project is that it be drop-in compatible for anyone using the "official" Facebook Java API client, insofar as is possible. Note that as the Facebook Platform changes, it may not be possible to retain direct compatibility with the official client library. For example, the Facebook Platform will soon be migrated to use 64-bit object id's, and this version of the client supports that. The official version of the client, however, still uses 32-bit id's, and thus is incompatible both with the Facebook Platform and this project in that regard. What this means in practice is that to migrate to this library you will have to update your code to use a Long wherever you were passing an object id as an Integer.

The need to keep the Java client compatible with the latest changes made to the Facebook Platform is the only consideration that may override the goal of preserving drop-in compatibility with the official Facebook client (as in the above case, where changes to the platform will make the official client incompatible with it...there's no sense in being drop-in compatible with a client that won't even work properly).

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

Quick Start

1. Download the latest project JAR file at http://facebook-java-api.googlecode.com/files/facebook-java-api-1.7.4.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:

• http://facebook-java-api.googlecode.com/files/jaxb-api-2.1.jar
• http://facebook-java-api.googlecode.com/files/jaxb-impl-2.1.jar
• http://facebook-java-api.googlecode.com/files/jsr173-api-1.0.jar

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:

• http://facebook-java-api.googlecode.com/files/activation.jar

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.7.4.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

From v1.7.3 to 1.7.4

• Disable admin.getAppProperties, admin.setAppProperties, and fbml.setRefHandle from desktop apps (as per API spec).
• Fix bug where FacebookXmlRestClient/FacebookJsonRestClient could not call admin.getAllocation.
• Improve parsing of multiline field values from XML.
• Add getters/setters for some internal client vars.

From v1.7.2 to 1.7.3

• Fix bug where calling 'Admin.getAllocation' would always throw an exception.
• Minor optimizations to user-id caching.

From v1.7.1 to 1.7.2

• Add 'Application.getPublicInfo' API call.
• Update JAXB bindings (adds support for several newer API calls).
• Add 'Admin.getAllocation' API call.
• Fold in official API changes made on 2/8/09.

From v1.7 to 1.7.1

• Implement the 'batch' API.
• Fix some bugs in the JSON and JAXB clients.
• Fix some NPE bugs.

From v1.6.2 to 1.7

• Merge in changes from official Facebook API made on 1/20/2008.
• Add 'pageActorId' attribute to TemplatizedAction utility class.
• Fix several NPE issues in feed_publishTemplatizedAction.
• Fix ClassCastException in FacebookJsonRestClient.

From v1.6.1 to 1.6.2

• Fix bug where calling admin_getAppProperties would throw an Exception.
• Add ability to retrieve app properties as a Map<ApplicationProperty, String> (admin_getAppPropertiesMap).
• Fix bug where sms_sendMessage would call the wrong API method.
• Fix multiple bugs in feed_publishTemplatizedAction (encode maps properly, don't ignore actorId parameter).
• Add ability to lookup an ApplicationProperty by name.

From v1.6 to 1.6.1

• Add 'Facebook' utility class (in seperate JAR file).
• Add support for admin.getAppProperties and admin.setAppProperties.
• Add support for data.getCookies and data.setCookie.
• Add support for configurable connection timeout settings for Facebook API requests.
• Add autoVerifySignature convenience method.
• Update JAXB bindings (add has 'has_added_app' property to user, support new API methods, etc.).
• Set 'expires' field correctly when getting a session.
• Fix logic error in photos_addTag (avoid NPE when trying to add a text tag instead of a UID-based tag).
• Remove some unimplemented methods that are now provided by the official API.

From v1.5.2 to 1.6

• Fix parsing bug in JAXB client.
• Support upcoming API changes to profile.setFBML.
• Allow notifications.sendEmail to be called without a session when using a non-desktop app.
• Merge in changes from official Facebook API made on 12/11/2007.

From v1.5.1 to 1.5.2

• Add support for the notifications.sendEmail API call.
• Deprecate 'email' parameter of notifications.send, provide an alternate version with no 'email' parameter.
• Update users.setStatus to include the 'status_includes_verb' parameter.
• Made session-key optional when using 'Pages' API calls.
• Minor updates to the Facebook 'sig' parameter list.

From v1.5 to 1.5.1

• Fix minor bug with international characters screwing up the 'sig' utilities.
• Rebuild the JAR with Java 5 to ensure its compatibility for Java 5 users.

From v1.4 to v1.5

• Fix various bugs in FacebookJsonRestClient (should actually be usable now).
• Merge in changes from official Facebook API made on 11/7/2007.

From v1.3 to v1.4

• Merge in changes from official Facebook API made on 10/30/2007.
• Refactor changes so that they don't break reverse compatibility for anyone using the official API.
• Refactor changes so that they don't break reverse compatibility for anyone using a previous version this API.
• Add a 'FacebookJaxbRestClient' that returns JAXB objects when making API calls.
• Extend the 'IFacebookRestClient' interface to include sms and data API calls.
• Refactor any UID's that were expressed as Integers in the new Facebook code to use Longs.
• Remove dependency on the simple-json library, the previous json library is still used.
• Add some new utility methods to 'FacebookXmlRestClient' and 'FacebookJsonRestClient'.
• Cleanup, add documentation, deprecate things where appropriate.

From v1.2 to v1.3

• Add support for all 'marketplace' API calls.
• Add support for users.hasAppPermission and users.setStatus API calls.
• Add support for fbml.setRefHandle API call.
• Add support for 'sms' API calls.
• Add support for data.setUserPreference(s) and data.getUserPreference(s) API calls.
• Add JAXB bindings for all 'marketplace' and 'data' API calls.
• Add MarketListing utility class to assist in creating marketplace listings.
• Define enum's that can be used for specifying marketplace categories, subcategories, and status codes.
• client now supports all "official" API methods as specified at http://wiki.developers.facebook.com/index.php/API

From v1.1 to v1.2:

• Add JAXB bindings for all FacebookRestClient methods that return a Document.
• Add utility method to get the JAXB response object corresponding to the last API call made through the client.

From v1.0 ("official" Facebook release in July) to v1.1:

• The 'Pair' class has been factored out of FacebookRestClient, and is now public.
• All object id's use 64-bit longs as their datatype to be compatible with pending Facebook platform changes.
• 'notifications_sendRequest' is marked as deprecated (it is no longer supported by Facebook).
• 'feed_publishActionOfUser' is marked as deprecated (it is being replaced with 'feed_publishTemplatizedAction').
• Add support for 'feed_publishTemplatizedAction' API call.
• Add 'TemplatizedAction' utility class to assist in creating feed entries through 'feed_publishTemplatizedAction'.
• Add ability to retrieve the raw XML/text snippet returned by the Facebook API server (note that this can only be called once per API call).
• Update/add javadoc comments.
• Provide more useful error messages and debugging output.
• Removed 'ExampleClient' sample application (removes spurious dependency on BrowserLauncher).
• Fixed various bugs in 'PhotoTag' class.

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));
    }