com.google.code.facebookapi
Class FacebookJsonRestClient

java.lang.Object
  com.google.code.facebookapi.ExtensibleClient<java.lang.Object>
      com.google.code.facebookapi.FacebookJsonRestClient

All Implemented Interfaces:

IFacebookRestClient<java.lang.Object>

public class FacebookJsonRestClient
extends ExtensibleClient<java.lang.Object>

A FacebookRestClient that uses the JSON result format. This means results from calls to the Facebook API are returned as JSON and transformed into Java Object's.

Field Summary

protected org.json.JSONArray	cacheFriendsList
protected static org.apache.commons.logging.Log	log

Fields inherited from class com.google.code.facebookapi.ExtensibleClient

_apiKey, _isDesktop, _readTimeout, _secret, _serverUrl, _timeout, _uploadFile, batchMode, cacheAppAdded, cacheSessionExpires, cacheSessionKey, cacheSessionSecret, cacheUserId, CRLF, HTTPS_SERVER_URL, JAXB_CONTEXT, MARKETPLACE_STATUS_DEFAULT, MARKETPLACE_STATUS_NOT_SUCCESS, MARKETPLACE_STATUS_SUCCESS, NUM_AUTOAPPENDED_PARAMS, permissionsApiKey, PREF, queries, rawResponse, SERVER_URL, UPLOAD_BUFFER_SIZE

Fields inherited from interface com.google.code.facebookapi.IFacebookRestClient

ERROR_TAG, FB_SERVER, HTTPS_SERVER_ADDR, SERVER_ADDR, TARGET_API_VERSION

Constructor Summary

FacebookJsonRestClient(java.lang.String apiKey, java.lang.String secret)
Constructor.

FacebookJsonRestClient(java.lang.String apiKey, java.lang.String secret, int connectionTimeout)
Constructor.

FacebookJsonRestClient(java.lang.String apiKey, java.lang.String secret, java.lang.String sessionKey)
Constructor.

FacebookJsonRestClient(java.lang.String apiKey, java.lang.String secret, java.lang.String sessionKey, int connectionTimeout)
Constructor.

FacebookJsonRestClient(java.lang.String serverAddr, java.lang.String apiKey, java.lang.String secret, java.lang.String sessionKey)
Constructor.

FacebookJsonRestClient(java.lang.String serverAddr, java.lang.String apiKey, java.lang.String secret, java.lang.String sessionKey, int connectionTimeout)
Constructor.

FacebookJsonRestClient(java.net.URL serverUrl, java.lang.String apiKey, java.lang.String secret, java.lang.String sessionKey)
Constructor.

FacebookJsonRestClient(java.net.URL serverUrl, java.lang.String apiKey, java.lang.String secret, java.lang.String sessionKey, int connectionTimeout)
Constructor.

FacebookJsonRestClient(java.net.URL serverUrl, java.lang.String apiKey, java.lang.String secret, java.lang.String sessionKey, int connectionTimeout, int readTimeout)
Constructor.

Method Summary

java.lang.String	admin_getAppPropertiesAsString(java.util.Collection<ApplicationProperty> properties) Retrieve application properties.
java.lang.String	auth_getSession(java.lang.String authToken) Sets the session information (sessionKey) using the token from auth_createToken.
java.lang.String	data_getUserPreference(java.lang.Integer prefId) Lookup a single preference value for the current user.
java.util.Map<java.lang.Integer,java.lang.String>	data_getUserPreferences() Get a map containing all preference values set for the current user.
void	data_setUserPreference(java.lang.Integer prefId, java.lang.String value) Set a user-preference value.
void	data_setUserPreferences(java.util.Map<java.lang.Integer,java.lang.String> values, boolean replace) Set multiple user-preferences values.
java.util.List<? extends java.lang.Object>	executeBatch(boolean serial) Executes a batch of queries.
protected boolean	extractBoolean(java.lang.Object val) Extracts a Boolean from a result that consists of a Boolean only.
protected int	extractInt(java.lang.Object val) Extracts an Integer from a result that consists of an Integer only.
protected java.lang.Long	extractLong(java.lang.Object val) Extracts a Long from a result that consists of an Long only.
java.lang.String	extractString(java.lang.Object val) Extracts a String from a result consisting entirely of a String.
protected java.net.URL	extractURL(java.lang.Object url) Extracts a URL from a result that consists of a URL only.
org.json.JSONArray	friends_get() Retrieves the friends of the currently logged in user.
org.json.JSONArray	getCacheFriendsList() Return the object's 'friendsList' property.
java.lang.String	getResponseFormat() The response format in which results to FacebookMethod calls are returned
java.util.List<Listing>	marketplace_getListings(java.util.List<java.lang.Long> listingIds, java.util.List<java.lang.Long> uids) Retrieve listings from the marketplace.
java.util.List<java.lang.String>	marketplace_getSubCategories() Return a list of all valid Marketplace subcategories.
java.util.List<Listing>	marketplace_search(MarketListingCategory category, MarketListingSubcategory subcategory, java.lang.String searchTerm) Search the marketplace listings by category, subcategory, and keyword.
protected java.lang.Object	parseCallResult(java.io.InputStream data, IFacebookMethod method) Parses the result of an API call from JSON into Java Objects.
void	setCacheFriendsList(java.util.List<java.lang.Long> ids) Set/override the list of friends stored in the client.
static org.json.JSONArray	toFriendsGetResponse(java.util.List<java.lang.Long> ids)

Methods inherited from class com.google.code.facebookapi.ExtensibleClient

addParam, addParam, addParamIfNotBlank, addParamIfNotBlank, admin_getAllocation, admin_getAllocation, admin_getAppProperties, admin_getAppPropertiesAsSet, admin_getAppPropertiesMap, admin_getDailyMetrics, admin_getDailyMetrics, admin_getMetrics, admin_getMetrics, admin_getNotificationAllocation, admin_getRequestAllocation, admin_setAppProperties, admin_setAppProperties, application_getPublicInfo, application_getPublicInfoByApiKey, application_getPublicInfoByCanvasName, application_getPublicInfoById, auth_createToken, auth_expireSession, auth_getUserId, auth_promoteSession, auth_revokeAuthorization, batch_run, beginBatch, beginPermissionsMode, callMethod, callMethod, data_getCookies, data_getCookies, data_getCookies, data_getCookies, data_setCookie, data_setCookie, data_setCookie, data_setCookie, data_setCookie, data_setCookie, data_setCookie, data_setCookie, delimit, encodeMethods, endPermissionsMode, events_get, events_getMembers, fbml_refreshImgSrc, fbml_refreshImgSrc, fbml_refreshRefUrl, fbml_refreshRefUrl, fbml_setRefHandle, feed_deactivateTemplateBundleByID, feed_getRegisteredTemplateBundleByID, feed_getRegisteredTemplateBundles, feed_publishTemplatizedAction, feed_publishTemplatizedAction, feed_publishTemplatizedAction, feed_publishTemplatizedAction, feed_publishTemplatizedAction, feed_publishTemplatizedAction, feed_publishTemplatizedAction, feed_PublishTemplatizedAction, feed_publishUserAction, feed_publishUserAction, feed_publishUserAction, feed_registerTemplateBundle, feed_registerTemplateBundle, feed_registerTemplateBundle, feed_registerTemplateBundle, fql_query, friends_areFriends, friends_areFriends, friends_get, friends_getAppUsers, friends_getLists, getCacheAppAdded, getCacheSessionExpires, getCacheSessionKey, getCacheSessionSecret, getCacheUserId, getDefaultServerUrl, getJaxbContext, getRawResponse, getResponsePOJO, getSessionSecret, groups_get, groups_getMembers, handleFeedImages, initJaxbSupport, isDesktop, liveMessage_send, marketplace_createListing, marketplace_createListing, marketplace_createListing, marketplace_createListing, marketplace_createListing, marketplace_createListing, marketplace_createListing, marketplace_editListing, marketplace_editListing, marketplace_getCategories, marketplace_getCategoriesObject, marketplace_getListings, marketplace_getSubCategories, marketplace_removeListing, marketplace_removeListing, marketplace_removeListing, marketplace_removeListing, marketplace_removeListing, marketplace_search, notifications_get, notifications_send, notifications_send, notifications_send, notifications_send, notifications_sendEmail, notifications_sendEmail, notifications_sendEmailPlain, notifications_sendEmailStr, notifications_sendEmailToCurrentUser, notifications_sendFbmlEmail, notifications_sendFbmlEmailToCurrentUser, notifications_sendTextEmail, notifications_sendTextEmailToCurrentUser, pages_getInfo, pages_getInfo, pages_getInfo, pages_getInfo, pages_isAdmin, pages_isAppAdded, pages_isFan, pages_isFan, permissions_checkAvailableApiAccess, permissions_checkGrantedApiAccess, permissions_grantApiAccess, permissions_grantFullApiAccess, permissions_revokeApiAccess, photos_addTag, photos_addTag, photos_addTag, photos_addTag, photos_addTags, photos_addTags, photos_createAlbum, photos_createAlbum, photos_createAlbum, photos_createAlbum, photos_get, photos_get, photos_get, photos_get, photos_get, photos_getAlbums, photos_getAlbums, photos_getAlbums, photos_getByAlbum, photos_getByAlbum, photos_getTags, photos_upload, photos_upload, photos_upload, photos_upload, photos_upload, photos_upload, photos_upload, photos_upload, postFileRequest, printDom, profile_getFBML, profile_getFBML, profile_getFBML, profile_getFBML, profile_getInfo, profile_getInfoOptions, profile_setFBML, profile_setFBML, profile_setFBML, profile_setFBML, profile_setFBML, profile_setFBML, profile_setInfo, profile_setInfoOptions, profile_setMobileFBML, profile_setMobileFBML, profile_setProfileActionFBML, profile_setProfileActionFBML, profile_setProfileFBML, profile_setProfileFBML, setCacheAppAdded, setCacheSession, setCacheSessionExpires, setCacheSessionKey, setCacheSessionSecret, setCacheUserId, setDefaultServerUrl, setIsDesktop, setJaxbContext, setServerUrl, setSessionSecret, sms_canSend, sms_canSend, sms_send, sms_send, sms_sendMessage, sms_sendMessageWithSession, sms_sendResponse, templatizedFeedHandler, toString, users_clearStatus, users_getInfo, users_getInfo, users_getLoggedInUser, users_getStandardInfo, users_getStandardInfo, users_hasAppPermission, users_hasAppPermission, users_isAppAdded, users_isAppAdded, users_isAppUser, users_isAppUser, users_setStatus, users_setStatus, users_setStatus, users_setStatus, users_setStatus, users_setStatus

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

log

protected static org.apache.commons.logging.Log log

cacheFriendsList

protected org.json.JSONArray cacheFriendsList

Constructor Detail

FacebookJsonRestClient

public FacebookJsonRestClient(java.lang.String apiKey,
                              java.lang.String secret)

Constructor.

Parameters:

apiKey - your Facebook API key

secret - your 'secret' Facebook key

FacebookJsonRestClient

public FacebookJsonRestClient(java.lang.String apiKey,
                              java.lang.String secret,
                              int connectionTimeout)

Constructor.

Parameters:

apiKey - your Facebook API key

secret - your 'secret' Facebook key

connectionTimeout - the connection timeout to apply when making API requests to Facebook, in milliseconds

FacebookJsonRestClient

public FacebookJsonRestClient(java.lang.String apiKey,
                              java.lang.String secret,
                              java.lang.String sessionKey)

Constructor.

Parameters:

apiKey - your Facebook API key

secret - your 'secret' Facebook key

sessionKey - the session-id to use

FacebookJsonRestClient

public FacebookJsonRestClient(java.lang.String apiKey,
                              java.lang.String secret,
                              java.lang.String sessionKey,
                              int connectionTimeout)

Constructor.

Parameters:

apiKey - your Facebook API key

secret - your 'secret' Facebook key

sessionKey - the session-id to use

connectionTimeout - the connection timeout to apply when making API requests to Facebook, in milliseconds

FacebookJsonRestClient

public FacebookJsonRestClient(java.lang.String serverAddr,
                              java.lang.String apiKey,
                              java.lang.String secret,
                              java.lang.String sessionKey)
                       throws java.net.MalformedURLException

Constructor.

Parameters:

serverAddr - the URL of the Facebook API server to use

apiKey - your Facebook API key

secret - your 'secret' Facebook key

sessionKey - the session-id to use

Throws:

java.net.MalformedURLException - if you specify an invalid URL

FacebookJsonRestClient

public FacebookJsonRestClient(java.lang.String serverAddr,
                              java.lang.String apiKey,
                              java.lang.String secret,
                              java.lang.String sessionKey,
                              int connectionTimeout)
                       throws java.net.MalformedURLException

Constructor.

Parameters:

serverAddr - the URL of the Facebook API server to use

apiKey - your Facebook API key

secret - your 'secret' Facebook key

sessionKey - the session-id to use

connectionTimeout - the connection timeout to apply when making API requests to Facebook, in milliseconds

Throws:

java.net.MalformedURLException - if you specify an invalid URL

FacebookJsonRestClient

public FacebookJsonRestClient(java.net.URL serverUrl,
                              java.lang.String apiKey,
                              java.lang.String secret,
                              java.lang.String sessionKey)

Constructor.

Parameters:

serverUrl - the URL of the Facebook API server to use

apiKey - your Facebook API key

secret - your 'secret' Facebook key

sessionKey - the session-id to use

FacebookJsonRestClient

public FacebookJsonRestClient(java.net.URL serverUrl,
                              java.lang.String apiKey,
                              java.lang.String secret,
                              java.lang.String sessionKey,
                              int connectionTimeout)

Constructor.

Parameters:

serverUrl - the URL of the Facebook API server to use

apiKey - your Facebook API key

secret - your 'secret' Facebook key

sessionKey - the session-id to use

connectionTimeout - the connection timeout to apply when making API requests to Facebook, in milliseconds

FacebookJsonRestClient

public FacebookJsonRestClient(java.net.URL serverUrl,
                              java.lang.String apiKey,
                              java.lang.String secret,
                              java.lang.String sessionKey,
                              int connectionTimeout,
                              int readTimeout)

Constructor.

Parameters:

serverUrl - the URL of the Facebook API server to use

apiKey - your Facebook API key

secret - your 'secret' Facebook key

sessionKey - the session-id to use

connectionTimeout - the connection timeout to apply when making API requests to Facebook, in milliseconds

readTimeout - the read timeout to apply when making API requests to Facebook, in milliseconds

Method Detail

getResponseFormat

public java.lang.String getResponseFormat()

The response format in which results to FacebookMethod calls are returned

Specified by:

getResponseFormat in class ExtensibleClient<java.lang.Object>

Returns:

the format: either XML, JSON, or null (API default)

extractString

public java.lang.String extractString(java.lang.Object val)

Extracts a String from a result consisting entirely of a String.

Specified by:

extractString in class ExtensibleClient<java.lang.Object>

Parameters:

val -

Returns:

the String

auth_getSession

public java.lang.String auth_getSession(java.lang.String authToken)
                                 throws FacebookException,
                                        java.io.IOException

Sets the session information (sessionKey) using the token from auth_createToken.

Specified by:

auth_getSession in interface IFacebookRestClient<java.lang.Object>

Specified by:

auth_getSession in class ExtensibleClient<java.lang.Object>

Parameters:

authToken - the token returned by auth_createToken or passed back to your callback_url.

Returns:

the session key

Throws:

FacebookException

java.io.IOException

See Also:

http://wiki.developers.facebook.com/index.php/Auth.getSession

parseCallResult

protected java.lang.Object parseCallResult(java.io.InputStream data,
                                           IFacebookMethod method)
                                    throws FacebookException,
                                           java.io.IOException

Parses the result of an API call from JSON into Java Objects.

Specified by:

parseCallResult in class ExtensibleClient<java.lang.Object>

Parameters:

data - an InputStream with the results of a request to the Facebook servers

method - the method

Returns:

a Java Object

Throws:

FacebookException - if data represents an error

java.io.IOException - if data is not readable

See Also:

JSONObject

extractURL

protected java.net.URL extractURL(java.lang.Object url)
                           throws java.io.IOException

Extracts a URL from a result that consists of a URL only. For JSON, that result is simply a String.

Specified by:

extractURL in class ExtensibleClient<java.lang.Object>

Parameters:

url -

Returns:

the URL

Throws:

java.io.IOException

extractInt

protected int extractInt(java.lang.Object val)

Extracts an Integer from a result that consists of an Integer only.

Specified by:

extractInt in class ExtensibleClient<java.lang.Object>

Parameters:

val -

Returns:

the Integer

extractBoolean

protected boolean extractBoolean(java.lang.Object val)

Extracts a Boolean from a result that consists of a Boolean only.

Overrides:

extractBoolean in class ExtensibleClient<java.lang.Object>

Parameters:

val -

Returns:

the Boolean

extractLong

protected java.lang.Long extractLong(java.lang.Object val)

Extracts a Long from a result that consists of an Long only.

Specified by:

extractLong in class ExtensibleClient<java.lang.Object>

Parameters:

val -

Returns:

the Integer

data_getUserPreference

public java.lang.String data_getUserPreference(java.lang.Integer prefId)
                                        throws FacebookException,
                                               java.io.IOException

Description copied from interface: IFacebookRestClient

Lookup a single preference value for the current user.

Parameters:

prefId - the id of the preference to lookup. This should be an integer value from 0-200.

Returns:

The value of that preference, or null if it is not yet set.

Throws:

FacebookException - if an error happens when executing the API call.

java.io.IOException - if a communication/network error happens.

data_getUserPreferences

public java.util.Map<java.lang.Integer,java.lang.String> data_getUserPreferences()
                                                                          throws FacebookException,
                                                                                 java.io.IOException

Description copied from interface: IFacebookRestClient

Get a map containing all preference values set for the current user.

Returns:

a map of preference values, keyed by preference id. The map will contain all preferences that have been set for the current user. If there are no preferences currently set, the map will be empty. The map returned will never be null.

Throws:

FacebookException - if an error happens when executing the API call.

java.io.IOException - if a communication/network error happens.

data_setUserPreference

public void data_setUserPreference(java.lang.Integer prefId,
                                   java.lang.String value)
                            throws FacebookException,
                                   java.io.IOException

Description copied from interface: IFacebookRestClient

Set a user-preference value. The value can be any string up to 127 characters in length, while the preference id can only be an integer between 0 and 200. Any preference set applies only to the current user of the application. To clear a user-preference, specify null as the value parameter. The values of "0" and "" will be stored as user-preferences with a literal value of "0" and "" respectively.

Parameters:

prefId - the id of the preference to set, an integer between 0 and 200.

value - the value to store, a String of up to 127 characters in length.

Throws:

FacebookException - if an error happens when executing the API call.

java.io.IOException - if a communication/network error happens.

data_setUserPreferences

public void data_setUserPreferences(java.util.Map<java.lang.Integer,java.lang.String> values,
                                    boolean replace)
                             throws FacebookException,
                                    java.io.IOException

Description copied from interface: IFacebookRestClient

Set multiple user-preferences values. The values can be strings up to 127 characters in length, while the preference id can only be an integer between 0 and 200. Any preferences set apply only to the current user of the application. To clear a user-preference, specify null as its value in the map. The values of "0" and "" will be stored as user-preferences with a literal value of "0" and "" respectively.

Parameters:

values - the values to store, specified in a map. The keys should be preference-id values from 0-200, and the values should be strings of up to 127 characters in length.

replace - set to true if you want to remove any pre-existing preferences before writing the new ones set to false if you want the new preferences to be merged with any pre-existing preferences

Throws:

FacebookException - if an error happens when executing the API call.

java.io.IOException - if a communication/network error happens.

marketplace_getListings

public java.util.List<Listing> marketplace_getListings(java.util.List<java.lang.Long> listingIds,
                                                       java.util.List<java.lang.Long> uids)
                                                throws FacebookException,
                                                       java.io.IOException

Description copied from interface: IFacebookRestClient

Retrieve listings from the marketplace. The listings can be filtered by listing-id or user-id (or both).

Parameters:

listingIds - the ids of listings to filter by, only listings matching the specified ids will be returned.

uids - the ids of users to filter by, only listings submitted by those users will be returned.

Returns:

A list of marketplace listings that meet the specified filter criteria.

Throws:

FacebookException - if an error happens when executing the API call.

java.io.IOException - if a communication/network error happens.

marketplace_getSubCategories

public java.util.List<java.lang.String> marketplace_getSubCategories()
                                                              throws FacebookException,
                                                                     java.io.IOException

Description copied from interface: IFacebookRestClient

Return a list of all valid Marketplace subcategories.

Returns:

a list of marketplace subcategories allowed by Facebook.

Throws:

FacebookException - if an error happens when executing the API call.

java.io.IOException - if a communication/network error happens.

marketplace_search

public java.util.List<Listing> marketplace_search(MarketListingCategory category,
                                                  MarketListingSubcategory subcategory,
                                                  java.lang.String searchTerm)
                                           throws FacebookException,
                                                  java.io.IOException

Description copied from interface: IFacebookRestClient

Search the marketplace listings by category, subcategory, and keyword.

Parameters:

category - the category to search in, optional (unless subcategory is specified).

subcategory - the subcategory to search in, optional.

searchTerm - the keyword to search for, optional.

Returns:

a list of marketplace entries that match the specified search parameters.

Throws:

FacebookException - if an error happens when executing the API call.

java.io.IOException - if a communication/network error happens.

admin_getAppPropertiesAsString

public java.lang.String admin_getAppPropertiesAsString(java.util.Collection<ApplicationProperty> properties)
                                                throws FacebookException,
                                                       java.io.IOException

Description copied from interface: IFacebookRestClient

Retrieve application properties. The properties are used by Facebook to describe the configuration of your application. This method cannot be called by desktop apps.

Parameters:

properties - a collection indicating the properties you are interested in retrieving.

Returns:

a JSON-encoded string containing the properties. It is your responsibility to parse the string. Details can be found at http://wiki.developers.facebook.com/index.php/Admin.getAppProperties

Throws:

FacebookException

java.io.IOException

executeBatch

public java.util.List<? extends java.lang.Object> executeBatch(boolean serial)
                                                        throws FacebookException,
                                                               java.io.IOException

Executes a batch of queries. You define the queries to execute by calling 'beginBatch' and then invoking the desired API methods that you want to execute as part of your batch as normal. Invoking this method will then execute the API calls you made in the interim as a single batch query.

Parameters:

serial - set to true, and your batch queries will always execute serially, in the same order in which your specified them. If set to false, the Facebook API server may execute your queries in parallel and/or out of order in order to improve performance.

Returns:

a list containing the results of the batch execution. The list will be ordered such that the first element corresponds to the result of the first query in the batch, and the second element corresponds to the result of the second query, and so on. The types of the objects in the list will match the type normally returned by the API call being invoked (so calling users_getLoggedInUser as part of a batch will place a Long in the list, and calling friends_get will place a Document in the list, etc.). The list may be empty, it will never be null.

Throws:

FacebookException

java.io.IOException

getCacheFriendsList

public org.json.JSONArray getCacheFriendsList()

Return the object's 'friendsList' property. This method does not call the Facebook API server.

Returns:

the friends-list stored in the API client.

setCacheFriendsList

public void setCacheFriendsList(java.util.List<java.lang.Long> ids)

Set/override the list of friends stored in the client.

Parameters:

friendsList - the new list to use.

toFriendsGetResponse

public static org.json.JSONArray toFriendsGetResponse(java.util.List<java.lang.Long> ids)

friends_get

public org.json.JSONArray friends_get()
                               throws FacebookException,
                                      java.io.IOException

Description copied from interface: IFacebookRestClient

Retrieves the friends of the currently logged in user.

Specified by:

friends_get in interface IFacebookRestClient<java.lang.Object>

Overrides:

friends_get in class ExtensibleClient<java.lang.Object>

Throws:

FacebookException

java.io.IOException

See Also:

http://wiki.developers.facebook.com/index.php/Friends.get