com.restfb

Interface FacebookClient

All Known Implementing Classes:

DefaultFacebookClient

public interface FacebookClient

Specifies how a Facebook Graph API client must operate.

Projects that need to access the old REST API should use LegacyFacebookClient instead. You might choose to do this because you have a legacy codebase or you need functionality that is not yet available in the Graph API.

If you'd like to...

• Fetch an object: use fetchObject(String, Class, Parameter...) or fetchObjects(List, Class, Parameter...)
• Fetch a connection: use fetchConnection(String, Class, Parameter...)
• Execute an FQL query: use executeFqlQuery(String, Class, Parameter...) or executeFqlMultiquery(Map, Class, Parameter...)
• Execute operations in batch: use executeBatch(BatchRequest...) or executeBatch(List, List)
• Publish data: use publish(String, Class, Parameter...) or publish(String, Class, BinaryAttachment, Parameter...)
• Delete an object: use deleteObject(String, Parameter...)

You may also perform some common access token operations. If you'd like to...

• Extend the life of an access token: use obtainExtendedAccessToken(String, String, String)
• Obtain an access token for use on behalf of an application instead of a user, use obtainAppAccessToken(String, String).
• Convert old-style session keys to OAuth access tokens: use convertSessionKeysToAccessTokens(String, String, String...)
• Verify and extract data from a signed request: use parseSignedRequest(String, String, Class)

Author:

Mark Allen, Scott Hernandez, Mattia Tommasone, Chris Petersen, Josef Gierbl, Broc Seib

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	FacebookClient.AccessToken Represents an access token/expiration date pair.
static class	FacebookClient.DebugTokenError
static class	FacebookClient.DebugTokenInfo Represents the result of a debugToken(String) inquiry.

Method Summary

Modifier and Type	Method and Description
List<FacebookClient.AccessToken>	convertSessionKeysToAccessTokens(String appId, String secretKey, String... sessionKeys) Converts an arbitrary number of sessionKeys to OAuth access tokens.
FacebookClient.DebugTokenInfo	debugToken(String inputToken) When working with access tokens, you may need to check what information is associated with them, such as its user or expiry.
boolean	deleteObject(String object, Parameter... parameters) Performs a Graph API delete operation on the given object.
List<BatchResponse>	executeBatch(BatchRequest... batchRequests) Executes operations as a batch using the Batch API.
List<BatchResponse>	executeBatch(List<BatchRequest> batchRequests) Executes operations as a batch using the Batch API.
List<BatchResponse>	executeBatch(List<BatchRequest> batchRequests, List<BinaryAttachment> binaryAttachments) Executes operations as a batch with binary attachments using the Batch API.
<T> T	executeFqlMultiquery(Map<String,String> queries, Class<T> objectType, Parameter... parameters) Deprecated. With the deprecation of Graph API 2.0 (August 7, 2016) FQL is not longer supported, change this asap
<T> List<T>	executeFqlQuery(String query, Class<T> objectType, Parameter... parameters) Deprecated. With the deprecation of Graph API 2.0 (August 7, 2016) FQL is not longer supported, change this asap
<T> T	executeMultiquery(Map<String,String> queries, Class<T> objectType, Parameter... parameters) Deprecated. As of 1.6.12, prefer executeFqlMultiquery(Map, Class, Parameter...) because it connects to the Graph API FQL endpoint instead of the legacy FQL endpoint.
<T> List<T>	executeQuery(String query, Class<T> objectType, Parameter... parameters) Deprecated. As of 1.6.12, prefer executeFqlQuery(String, Class, Parameter...) because it connects to the Graph API FQL endpoint instead of the legacy FQL endpoint.
<T> Connection<T>	fetchConnection(String connection, Class<T> connectionType, Parameter... parameters) Fetches a Graph API Connection type, mapping the result to an instance of connectionType.
<T> Connection<T>	fetchConnectionPage(String connectionPageUrl, Class<T> connectionType) Fetches a previous/next page of a Graph API Connection type, mapping the result to an instance of connectionType.
DeviceCode	fetchDeviceCode(String appId, ScopeBuilder scope) Method to initialize the device access token generation.
<T> T	fetchObject(String object, Class<T> objectType, Parameter... parameters) Fetches a single Graph API object, mapping the result to an instance of objectType.
<T> T	fetchObjects(List<String> ids, Class<T> objectType, Parameter... parameters) Fetches multiple Graph API objects in a single call, mapping the results to an instance of objectType.
JsonMapper	getJsonMapper() Gets the JsonMapper used to convert Facebook JSON to Java objects.
String	getLoginDialogUrl(String appId, String redirectUri, ScopeBuilder scope, Parameter... additionalParameters) generates the login dialog url
String	getLogoutUrl(String next) generates an logout url
WebRequestor	getWebRequestor() Gets the WebRequestor used to talk to the Facebook API endpoints.
FacebookClient.AccessToken	obtainAppAccessToken(String appId, String appSecret) Obtains an access token which can be used to perform Graph API operations on behalf of an application instead of a user.
String	obtainAppSecretProof(String accessToken, String appSecret) Generates an appsecret_proof value.
FacebookClient.AccessToken	obtainDeviceAccessToken(String appId, String code) Method to poll Facebook and fetch the Device Access Token.
FacebookClient.AccessToken	obtainExtendedAccessToken(String appId, String appSecret) Convenience method which invokes obtainExtendedAccessToken(String, String, String) with the current access token.
FacebookClient.AccessToken	obtainExtendedAccessToken(String appId, String appSecret, String accessToken) Obtains an extended access token for the given existing, non-expired, short-lived access_token.
FacebookClient.AccessToken	obtainUserAccessToken(String appId, String appSecret, String redirectUri, String verificationCode) Obtains an access token which can be used to perform Graph API operations on behalf of a user.
<T> T	parseSignedRequest(String signedRequest, String appSecret, Class<T> objectType) Parses a signed request and verifies it against your App Secret.
<T> T	publish(String connection, Class<T> objectType, BinaryAttachment binaryAttachment, Parameter... parameters) Performs a Graph API publish operation on the given connection and includes a file - a photo, for example - in the publish request, and mapping the result to an instance of objectType.
<T> T	publish(String connection, Class<T> objectType, List<BinaryAttachment> binaryAttachments, Parameter... parameters) Performs a Graph API publish operation on the given connection and includes some files - photos, for example - in the publish request, and mapping the result to an instance of objectType.
<T> T	publish(String connection, Class<T> objectType, Parameter... parameters) Performs a Graph API publish operation on the given connection, mapping the result to an instance of objectType.

Method Detail

fetchObject

<T> T fetchObject(String object,
                  Class<T> objectType,
                  Parameter... parameters)

Fetches a single Graph API object, mapping the result to an instance of objectType.

Type Parameters:

T - Java type to map to.

Parameters:

object - ID of the object to fetch, e.g. "me".

objectType - Object type token.

parameters - URL parameters to include in the API call (optional).

Returns:

An instance of type objectType which contains the requested object's data.

Throws:

FacebookException - If an error occurs while performing the API call.

fetchObjects

<T> T fetchObjects(List<String> ids,
                   Class<T> objectType,
                   Parameter... parameters)

Fetches multiple Graph API objects in a single call, mapping the results to an instance of objectType.

You'll need to write your own container type (objectType) to hold the results. See http://restfb.com for an example of how to do this.

Type Parameters:

T - Java type to map to.

Parameters:

ids - IDs of the objects to fetch, e.g. "me", "arjun".

objectType - Object type token.

parameters - URL parameters to include in the API call (optional).

Returns:

An instance of type objectType which contains the requested objects' data.

Throws:

FacebookException - If an error occurs while performing the API call.

fetchConnection

<T> Connection<T> fetchConnection(String connection,
                                  Class<T> connectionType,
                                  Parameter... parameters)

Fetches a Graph API Connection type, mapping the result to an instance of connectionType.

Type Parameters:

T - Java type to map to.

Parameters:

connection - The name of the connection, e.g. "me/feed".

connectionType - Connection type token.

parameters - URL parameters to include in the API call (optional).

Returns:

An instance of type connectionType which contains the requested Connection's data.

Throws:

FacebookException - If an error occurs while performing the API call.

fetchConnectionPage

<T> Connection<T> fetchConnectionPage(String connectionPageUrl,
                                      Class<T> connectionType)

Fetches a previous/next page of a Graph API Connection type, mapping the result to an instance of connectionType.

Type Parameters:

T - Java type to map to.

Parameters:

connectionPageUrl - The URL of the connection page to fetch, usually retrieved via Connection.getPreviousPageUrl() or Connection.getNextPageUrl().

connectionType - Connection type token.

Returns:

An instance of type connectionType which contains the requested Connection's data.

Throws:

FacebookException - If an error occurs while performing the API call.

executeQuery

@Deprecated
<T> List<T> executeQuery(String query,
                                     Class<T> objectType,
                                     Parameter... parameters)

Deprecated. As of 1.6.12, prefer executeFqlQuery(String, Class, Parameter...) because it connects to the Graph API FQL endpoint instead of the legacy FQL endpoint.

Executes an FQL query, mapping the resultset to a List of instances of objectType.

Type Parameters:

T - Java type to map to.

Parameters:

query - The FQL query to execute, e.g. "SELECT name FROM user WHERE uid=220439 or uid=7901103".

objectType - Resultset object type token.

parameters - URL parameters to include in the API call (optional).

Returns:

A list of instances of objectType which map to the query results.

Throws:

FacebookException - If an error occurs while performing the API call.

executeMultiquery

@Deprecated
<T> T executeMultiquery(Map<String,String> queries,
                                    Class<T> objectType,
                                    Parameter... parameters)

Deprecated. As of 1.6.12, prefer executeFqlMultiquery(Map, Class, Parameter...) because it connects to the Graph API FQL endpoint instead of the legacy FQL endpoint.

Executes an FQL multiquery, which allows you to batch multiple queries into a single request.

You'll need to write your own container type (objectType) to hold the results. See http://restfb.com for an example of how to do this.

Type Parameters:

T - Java type to map to.

Parameters:

queries - A mapping of query names to queries. This is marshaled to JSON and sent over the wire to the Facebook API endpoint as the queries parameter.

objectType - Object type token.

parameters - URL parameters to include in the API call (optional).

Returns:

An instance of type objectType which contains the requested objects' data.

Throws:

FacebookException - If an error occurs while performing the API call.

executeFqlQuery

@Deprecated
<T> List<T> executeFqlQuery(String query,
                                        Class<T> objectType,
                                        Parameter... parameters)

Deprecated. With the deprecation of Graph API 2.0 (August 7, 2016) FQL is not longer supported, change this asap

Executes an FQL query, mapping the resultset to a List of instances of objectType.

Type Parameters:

T - Java type to map to.

Parameters:

query - The FQL query to execute, e.g. "SELECT name FROM user WHERE uid=220439 or uid=7901103".

objectType - Resultset object type token.

parameters - URL parameters to include in the API call (optional).

Returns:

A list of instances of objectType which map to the query results.

Throws:

FacebookException - If an error occurs while performing the API call.

Since:

1.6.12

executeFqlMultiquery

@Deprecated
<T> T executeFqlMultiquery(Map<String,String> queries,
                                       Class<T> objectType,
                                       Parameter... parameters)

Deprecated. With the deprecation of Graph API 2.0 (August 7, 2016) FQL is not longer supported, change this asap

Executes an FQL multiquery, which allows you to batch multiple queries into a single request.

You'll need to write your own container type (objectType) to hold the results. See http://restfb.com for an example of how to do this.

Type Parameters:

T - Java type to map to.

Parameters:

queries - A mapping of query names to queries. This is marshaled to JSON and sent over the wire to the Facebook API endpoint as the q parameter.

objectType - Object type token.

parameters - URL parameters to include in the API call (optional).

Returns:

An instance of type objectType which contains the requested objects' data.

Throws:

FacebookException - If an error occurs while performing the API call.

executeBatch

List<BatchResponse> executeBatch(BatchRequest... batchRequests)

Executes operations as a batch using the Batch API.

Parameters:

batchRequests - The operations to execute.

Returns:

The execution results in the order in which the requests were specified.

executeBatch

List<BatchResponse> executeBatch(List<BatchRequest> batchRequests)

Executes operations as a batch using the Batch API.

Parameters:

batchRequests - The operations to execute.

Returns:

The execution results in the order in which the requests were specified.

executeBatch

List<BatchResponse> executeBatch(List<BatchRequest> batchRequests,
                                 List<BinaryAttachment> binaryAttachments)

Executes operations as a batch with binary attachments using the Batch API.

Parameters:

batchRequests - The operations to execute.

binaryAttachments - Binary attachments referenced by the batch requests.

Returns:

The execution results in the order in which the requests were specified.

Since:

1.6.5

publish

<T> T publish(String connection,
              Class<T> objectType,
              Parameter... parameters)

Performs a Graph API publish operation on the given connection, mapping the result to an instance of objectType.

Type Parameters:

T - Java type to map to.

Parameters:

connection - The Connection to publish to.

objectType - Object type token.

parameters - URL parameters to include in the API call.

Returns:

An instance of type objectType which contains the Facebook response to your publish request.

Throws:

FacebookException - If an error occurs while performing the API call.

publish

<T> T publish(String connection,
              Class<T> objectType,
              List<BinaryAttachment> binaryAttachments,
              Parameter... parameters)

Performs a Graph API publish operation on the given connection and includes some files - photos, for example - in the publish request, and mapping the result to an instance of objectType.

Type Parameters:

T - Java type to map to.

Parameters:

connection - The Connection to publish to.

objectType - Object type token.

binaryAttachments - The files to include in the publish request.

parameters - URL parameters to include in the API call.

Returns:

An instance of type objectType which contains the Facebook response to your publish request.

Throws:

FacebookException - If an error occurs while performing the API call.

publish

<T> T publish(String connection,
              Class<T> objectType,
              BinaryAttachment binaryAttachment,
              Parameter... parameters)

Performs a Graph API publish operation on the given connection and includes a file - a photo, for example - in the publish request, and mapping the result to an instance of objectType.

Type Parameters:

T - Java type to map to.

Parameters:

connection - The Connection to publish to.

objectType - Object type token.

binaryAttachment - The file to include in the publish request.

parameters - URL parameters to include in the API call.

Returns:

An instance of type objectType which contains the Facebook response to your publish request.

Throws:

FacebookException - If an error occurs while performing the API call.

deleteObject

boolean deleteObject(String object,
                     Parameter... parameters)

Performs a Graph API delete operation on the given object.

Parameters:

object - The ID of the object to delete.

parameters - URL parameters to include in the API call.

Returns:

true if Facebook indicated that the object was successfully deleted, false otherwise.

Throws:

FacebookException - If an error occurred while attempting to delete the object.

convertSessionKeysToAccessTokens

List<FacebookClient.AccessToken> convertSessionKeysToAccessTokens(String appId,
                                                                  String secretKey,
                                                                  String... sessionKeys)

Converts an arbitrary number of sessionKeys to OAuth access tokens.

See the Facebook Platform Upgrade Guide for details on how this process works and why you should convert your application's session keys if you haven't already.

Parameters:

appId - A Facebook application ID.

secretKey - A Facebook application secret key.

sessionKeys - The Old REST API session keys to be converted to OAuth access tokens.

Returns:

A list of access tokens ordered to correspond to the sessionKeys argument list.

Throws:

FacebookException - If an error occurs while attempting to convert the session keys to API keys.

Since:

1.6

obtainUserAccessToken

FacebookClient.AccessToken obtainUserAccessToken(String appId,
                                                 String appSecret,
                                                 String redirectUri,
                                                 String verificationCode)

Obtains an access token which can be used to perform Graph API operations on behalf of a user.

See Access Tokens.

Parameters:

appId - The ID of the app for which you'd like to obtain an access token.

appSecret - The secret for the app for which you'd like to obtain an access token.

redirectUri - The redirect URI which was used to obtain the verificationCode.

verificationCode - The verification code in the Graph API callback to the redirect URI.

Returns:

The access token for the user identified by appId, appSecret, redirectUri and verificationCode.

Throws:

FacebookException - If an error occurs while attempting to obtain an access token.

Since:

1.8.0

obtainAppAccessToken

FacebookClient.AccessToken obtainAppAccessToken(String appId,
                                                String appSecret)

Obtains an access token which can be used to perform Graph API operations on behalf of an application instead of a user.

See Facebook's authenticating as an app documentation.

Parameters:

appId - The ID of the app for which you'd like to obtain an access token.

appSecret - The secret for the app for which you'd like to obtain an access token.

Returns:

The access token for the application identified by appId and appSecret.

Throws:

FacebookException - If an error occurs while attempting to obtain an access token.

Since:

1.6.10

obtainExtendedAccessToken

FacebookClient.AccessToken obtainExtendedAccessToken(String appId,
                                                     String appSecret,
                                                     String accessToken)

Obtains an extended access token for the given existing, non-expired, short-lived access_token.

See Facebook's extend access token documentation.

Parameters:

appId - The ID of the app for which you'd like to obtain an extended access token.

appSecret - The secret for the app for which you'd like to obtain an extended access token.

accessToken - The non-expired, short-lived access token to extend.

Returns:

An extended access token for the given accessToken.

Throws:

FacebookException - If an error occurs while attempting to obtain an extended access token.

Since:

1.6.10

obtainAppSecretProof

String obtainAppSecretProof(String accessToken,
                            String appSecret)

Generates an appsecret_proof value.

See Facebook's 'securing requests' documentation for more info.

Parameters:

accessToken - The access token required to generate the appsecret_proof value.

appSecret - The secret for the app for which you'd like to generate the appsecret_proof value.

Returns:

A hex-encoded SHA256 hash as a String.

Throws:

IllegalStateException - If creating the appsecret_proof fails.

Since:

1.6.13

obtainExtendedAccessToken

FacebookClient.AccessToken obtainExtendedAccessToken(String appId,
                                                     String appSecret)

Convenience method which invokes obtainExtendedAccessToken(String, String, String) with the current access token.

Parameters:

appId - The ID of the app for which you'd like to obtain an extended access token.

appSecret - The secret for the app for which you'd like to obtain an extended access token.

Returns:

An extended access token for the given accessToken.

Throws:

FacebookException - If an error occurs while attempting to obtain an extended access token.

IllegalStateException - If this instance was not constructed with an access token.

Since:

1.6.10

parseSignedRequest

<T> T parseSignedRequest(String signedRequest,
                         String appSecret,
                         Class<T> objectType)

Parses a signed request and verifies it against your App Secret.

See Facebook's signed request documentation.

Type Parameters:

T - class of objectType

Parameters:

signedRequest - The signed request to parse.

appSecret - The secret for the app that can read this signed request.

objectType - Object type token.

Returns:

An instance of type objectType which contains the decoded object embedded within signedRequest.

Throws:

FacebookSignedRequestParsingException - If an error occurs while trying to process signedRequest.

FacebookSignedRequestVerificationException - If signedRequest fails verification against appSecret.

Since:

1.6.13

fetchDeviceCode

DeviceCode fetchDeviceCode(String appId,
                           ScopeBuilder scope)

Method to initialize the device access token generation. You receive a DeviceCode instance and have to show the user the DeviceCode.getVerificationUri() and the DeviceCode.getUserCode(). The user have to enter the user code at the verification url. Save the DeviceCode.getCode() to use it later, when polling Facebook with the obtainDeviceAccessToken(java.lang.String, java.lang.String) method.

Parameters:

appId - The ID of your app, found in your app's dashboard.

scope - List of Permissions to request from the person using your app.

Returns:

Instance of DeviceCode including the information to obtain the Device access token

Since:

1.12.0

obtainDeviceAccessToken

FacebookClient.AccessToken obtainDeviceAccessToken(String appId,
                                                   String code)
                                            throws FacebookDeviceTokenCodeExpiredException,
                                                   FacebookDeviceTokenPendingException,
                                                   FacebookDeviceTokenDeclinedException,
                                                   FacebookDeviceTokenSlowdownException

Method to poll Facebook and fetch the Device Access Token. You have to use this method to check if the user confirms the authorization. FacebookOAuthException can be thrown if the authorization is declined or still pending.

Parameters:

appId - The ID of your app, found in your app's dashboard.

code - The device

Returns:

An extended access token for the given FacebookClient.AccessToken.

Throws:

FacebookDeviceTokenCodeExpiredException - the DeviceCode.getCode() is expired, please fetch a new DeviceCode. Call fetchDeviceCode(java.lang.String, com.restfb.scope.ScopeBuilder)

FacebookDeviceTokenPendingException - the user has not finished the authorisation process, yet. Please poll again later.

FacebookDeviceTokenDeclinedException - the user declined the authorisation. You have to handle this problem.

FacebookDeviceTokenSlowdownException - you tried too often to fetch the device access token. You have to use a larger interval

Since:

1.12.0

debugToken

FacebookClient.DebugTokenInfo debugToken(String inputToken)

When working with access tokens, you may need to check what information is associated with them, such as its user or expiry. To get this information you can use the debug tool in the developer site, or you can use this function.

You must instantiate your FacebookClient using your App Access Token, or a valid User Access Token from a developer of the app.

Note that if your app is set to Native/Desktop in the Advanced settings of your App Dashboard, the underlying GraphAPI endpoint will not work with your app token unless you change the "App Secret in Client" setting to NO. If you do not see this setting, make sure your "App Type" is set to Native/Desktop and then press the save button at the bottom of the page. This will not affect apps set to Web.

The response of the API call is a JSON array containing data and a map of fields. For example:

 
 {
     "data": {
         "app_id": 138483919580948, 
         "application": "Social Cafe", 
         "expires_at": 1352419328, 
         "is_valid": true, 
         "issued_at": 1347235328, 
         "metadata": {
             "sso": "iphone-safari"
         }, 
         "scopes": [
             "email", 
             "publish_actions"
         ], 
         "user_id": 1207059
     }
 }
 
 

Note that the issued_at field is not returned for short-lived access tokens.

See Debugging an Access Token

Parameters:

inputToken - The Access Token to debug.

Returns:

A JsonObject containing the debug information for the accessToken.

Since:

1.6.13

getJsonMapper

JsonMapper getJsonMapper()

Gets the JsonMapper used to convert Facebook JSON to Java objects.

Returns:

The JsonMapper used to convert Facebook JSON to Java objects.

Since:

1.6.7

getWebRequestor

WebRequestor getWebRequestor()

Gets the WebRequestor used to talk to the Facebook API endpoints.

Returns:

The WebRequestor used to talk to the Facebook API endpoints.

Since:

1.6.7

getLogoutUrl

String getLogoutUrl(String next)

generates an logout url

Parameters:

next - may be null, url the webpage should redirect after logout

Returns:

the logout url

Since:

1.9.0

getLoginDialogUrl

String getLoginDialogUrl(String appId,
                         String redirectUri,
                         ScopeBuilder scope,
                         Parameter... additionalParameters)

generates the login dialog url

Parameters:

appId - The ID of your app, found in your app's dashboard.

redirectUri - The URL that you want to redirect the person logging in back to. This URL will capture the response from the Login Dialog. If you are using this in a webview within a desktop app, this must be set to https://www.facebook.com/connect/login_success.html.

scope - List of Permissions to request from the person using your app.

additionalParameters - List of additional parameters

Returns:

Since:

1.9.0