public class DefaultFacebookClient extends Object implements FacebookClient
Modifier and Type | Class and Description |
---|---|
protected static interface |
DefaultFacebookClient.Requestor |
FacebookClient.AccessToken
Modifier and Type | Field and Description |
---|---|
protected static String |
ACCESS_TOKEN_PARAM_NAME
Reserved access token parameter name.
|
protected String |
accessToken
Graph API access token.
|
protected static String |
ERROR_ATTRIBUTE_NAME
API error response 'error' attribute name.
|
protected static String |
ERROR_MESSAGE_ATTRIBUTE_NAME
API error response 'message' attribute name.
|
protected static String |
ERROR_TYPE_ATTRIBUTE_NAME
API error response 'type' attribute name.
|
protected static String |
FACEBOOK_GRAPH_ENDPOINT_URL
API endpoint URL.
|
protected static String |
FACEBOOK_LEGACY_ENDPOINT_URL
Legacy API endpoint URL, used to support FQL queries.
|
protected FacebookGraphExceptionMapper |
facebookGraphExceptionMapper
Knows how to map Graph API exceptions to formal Java exception types.
|
protected static String |
FORMAT_PARAM_NAME
Reserved "result format" parameter name.
|
protected static String |
IDS_PARAM_NAME
Reserved "multiple IDs" parameter name.
|
protected Set<String> |
illegalParamNames
Set of parameter names that user must not specify themselves, since we use
these parameters internally.
|
protected JsonMapper |
jsonMapper
Handles mapping Facebook response JSON to Java objects.
|
protected static String |
LEGACY_ERROR_CODE_ATTRIBUTE_NAME
Legacy API error response 'error_code' attribute name.
|
protected static String |
LEGACY_ERROR_MSG_ATTRIBUTE_NAME
Legacy API error response 'error_msg' attribute name.
|
protected Logger |
logger
Logger.
|
protected static String |
METHOD_PARAM_NAME
Reserved method override parameter name.
|
protected static String |
QUERIES_PARAM_NAME
Reserved FQL multiquery parameter name.
|
protected static String |
QUERY_PARAM_NAME
Reserved FQL query parameter name.
|
protected WebRequestor |
webRequestor
Handles
GET s and POST s to the Facebook API endpoint. |
Constructor and Description |
---|
DefaultFacebookClient()
Creates a Facebook Graph API client with no access token.
|
DefaultFacebookClient(String accessToken)
Creates a Facebook Graph API client with the given
accessToken . |
DefaultFacebookClient(String accessToken,
WebRequestor webRequestor,
JsonMapper jsonMapper)
Creates a Facebook Graph API client with the given
accessToken ,
webRequestor , and jsonMapper . |
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. |
protected FacebookGraphExceptionMapper |
createFacebookGraphExceptionMapper()
Specifies how we map Graph API exception types/messages to real Java
exceptions.
|
boolean |
deleteObject(String object)
Performs a Graph
API delete operation on the given
object . |
<T> T |
executeMultiquery(Map<String,String> queries,
Class<T> objectType,
Parameter... parameters)
Executes an FQL
multiquery, which allows you to batch multiple queries into a single
request.
|
<T> List<T> |
executeQuery(String query,
Class<T> objectType,
Parameter... parameters)
|
<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 . |
<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 . |
protected String |
getFacebookGraphEndpointUrl()
Returns the base endpoint URL for the Graph API.
|
protected String |
getFacebookLegacyEndpointUrl()
Returns the base endpoint URL for the Old REST API.
|
protected String |
makeRequest(String endpoint,
boolean useLegacyEndpoint,
boolean executeAsPost,
boolean executeAsDelete,
InputStream binaryAttachment,
Parameter... parameters)
Coordinates the process of executing the API request GET/POST and
processing the response we receive from the endpoint.
|
protected String |
makeRequest(String endpoint,
Parameter... parameters)
Coordinates the process of executing the API request GET/POST and
processing the response we receive from the endpoint.
|
protected String |
makeRequestAndProcessResponse(DefaultFacebookClient.Requestor requestor) |
protected <T> Connection<T> |
mapToConnection(String connectionJson,
Class<T> connectionType) |
protected Parameter[] |
parametersWithAdditionalParameter(Parameter parameter,
Parameter... parameters)
Appends the given
parameter to the given parameters array. |
<T> T |
publish(String connection,
Class<T> objectType,
InputStream 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,
Parameter... parameters)
Performs a Graph API
publish operation on the given
connection , mapping the result
to an instance of objectType . |
protected String |
queriesToJson(Map<String,String> queries)
Given a map of query names to queries, verify that it contains valid data
and convert it to a JSON object string.
|
protected void |
throwFacebookResponseStatusExceptionIfNecessary(String json)
Throws an exception if Facebook returned an error response.
|
protected void |
throwLegacyFacebookResponseStatusExceptionIfNecessary(String json)
If the
error_code JSON field is present, we've got a response
status error for this API call. |
protected String |
toParameterString(Parameter... parameters)
Generate the parameter string to be included in the Facebook API request.
|
protected String |
urlEncodedValueForParameterName(String name,
String value)
Gets the URL-encoded version of the given
value for the parameter
named name . |
protected void |
verifyParameterLegality(Parameter... parameters)
Verifies that the provided parameter names don't collide with the ones we
internally pass along to Facebook.
|
protected void |
verifyParameterPresence(String parameterName,
Object parameter)
Ensures that
parameter isn't null . |
protected void |
verifyParameterPresence(String parameterName,
String parameter)
Ensures that
parameter isn't null or an empty string. |
protected String accessToken
protected FacebookGraphExceptionMapper facebookGraphExceptionMapper
protected static final String FACEBOOK_GRAPH_ENDPOINT_URL
protected static final String FACEBOOK_LEGACY_ENDPOINT_URL
protected static final String METHOD_PARAM_NAME
protected static final String IDS_PARAM_NAME
protected static final String QUERY_PARAM_NAME
protected static final String QUERIES_PARAM_NAME
protected static final String FORMAT_PARAM_NAME
protected static final String ERROR_ATTRIBUTE_NAME
protected static final String ERROR_TYPE_ATTRIBUTE_NAME
protected static final String ERROR_MESSAGE_ATTRIBUTE_NAME
protected WebRequestor webRequestor
GET
s and POST
s to the Facebook API endpoint.protected JsonMapper jsonMapper
protected final Set<String> illegalParamNames
protected static final String LEGACY_ERROR_CODE_ATTRIBUTE_NAME
protected static final String LEGACY_ERROR_MSG_ATTRIBUTE_NAME
protected static final String ACCESS_TOKEN_PARAM_NAME
protected final Logger logger
public DefaultFacebookClient()
public DefaultFacebookClient(String accessToken)
accessToken
.accessToken
- A Facebook OAuth access token.public DefaultFacebookClient(String accessToken, WebRequestor webRequestor, JsonMapper jsonMapper)
accessToken
,
webRequestor
, and jsonMapper
.accessToken
- A Facebook OAuth access token.webRequestor
- The WebRequestor
implementation to use for sending
requests to the API endpoint.jsonMapper
- The JsonMapper
implementation to use for mapping API
response JSON to Java objects.NullPointerException
- If jsonMapper
or webRequestor
is null
.public boolean deleteObject(String object)
FacebookClient
object
.deleteObject
in interface FacebookClient
object
- The ID of the object to delete.true
if Facebook indicated that the object was successfully
deleted, false
otherwise.FacebookClient.deleteObject(String)
public <T> Connection<T> fetchConnection(String connection, Class<T> connectionType, Parameter... parameters)
FacebookClient
Connection
type, mapping the result to an
instance of connectionType
.fetchConnection
in interface FacebookClient
T
- Java type to map to.connection
- The name of the connection, e.g. "me/feed"
.connectionType
- Connection type token.parameters
- URL parameters to include in the API call (optional).connectionType
which contains the
requested Connection's data.FacebookClient.fetchConnection(String,
Class, com.restfb.Parameter[])
public <T> Connection<T> fetchConnectionPage(String connectionPageUrl, Class<T> connectionType)
FacebookClient
Connection
type,
mapping the result to an instance of connectionType
.fetchConnectionPage
in interface FacebookClient
T
- Java type to map to.connectionPageUrl
- The URL of the connection page to fetch, usually retrieved via
Connection.getPreviousPageUrl()
or
Connection.getNextPageUrl()
.connectionType
- Connection type token.connectionType
which contains the
requested Connection's data.FacebookClient.fetchConnectionPage(String,
Class)
protected <T> Connection<T> mapToConnection(String connectionJson, Class<T> connectionType)
public <T> T fetchObject(String object, Class<T> objectType, Parameter... parameters)
FacebookClient
objectType
.fetchObject
in interface FacebookClient
T
- Java type to map to.object
- ID of the object to fetch, e.g. "me"
.objectType
- Object type token.parameters
- URL parameters to include in the API call (optional).objectType
which contains the requested
object's data.FacebookClient.fetchObject(String,
Class, com.restfb.Parameter[])
public <T> T fetchObjects(List<String> ids, Class<T> objectType, Parameter... parameters)
FacebookClient
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.fetchObjects
in interface FacebookClient
T
- Java type to map to.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).objectType
which contains the requested
objects' data.FacebookClient.fetchObjects(java.util.List,
Class, com.restfb.Parameter[])
public <T> T publish(String connection, Class<T> objectType, InputStream binaryAttachment, Parameter... parameters)
FacebookClient
connection
and includes a file -
a photo, for example - in the publish request, and mapping the result to an
instance of objectType
.publish
in interface FacebookClient
T
- Java type to map to.connection
- The Connection to publish to.objectType
- Object type token.binaryAttachment
- The file to include in the publish request - a photo, for example.parameters
- URL parameters to include in the API call.objectType
which contains the Facebook
response to your publish request.FacebookClient.publish(String, Class,
java.io.InputStream, com.restfb.Parameter[])
public <T> T publish(String connection, Class<T> objectType, Parameter... parameters)
FacebookClient
connection
, mapping the result
to an instance of objectType
.publish
in interface FacebookClient
T
- Java type to map to.connection
- The Connection to publish to.objectType
- Object type token.parameters
- URL parameters to include in the API call.objectType
which contains the Facebook
response to your publish request.FacebookClient.publish(String, Class,
com.restfb.Parameter[])
public <T> T executeMultiquery(Map<String,String> queries, Class<T> objectType, Parameter... parameters)
FacebookClient
objectType
) to hold
the results. See http://restfb.com for an
example of how to do this.executeMultiquery
in interface FacebookClient
T
- Java type to map to.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).objectType
which contains the requested
objects' data.FacebookClient.executeMultiquery(java.util.Map,
Class, com.restfb.Parameter[])
public <T> List<T> executeQuery(String query, Class<T> objectType, Parameter... parameters)
FacebookClient
executeQuery
in interface FacebookClient
T
- Java type to map to.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).objectType
which map to the query
results.FacebookClient.executeQuery(String,
Class, com.restfb.Parameter[])
public List<FacebookClient.AccessToken> convertSessionKeysToAccessTokens(String appId, String secretKey, String... sessionKeys)
FacebookClient
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.convertSessionKeysToAccessTokens
in interface FacebookClient
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.sessionKeys
argument list.FacebookClient.convertSessionKeysToAccessTokens(String,
String, String[])
protected String makeRequest(String endpoint, Parameter... parameters)
endpoint
- Facebook Graph API endpoint.parameters
- Arbitrary number of parameters to send along to Facebook as part
of the API call.FacebookException
- If an error occurs while making the Facebook API POST or
processing the response.protected String makeRequest(String endpoint, boolean useLegacyEndpoint, boolean executeAsPost, boolean executeAsDelete, InputStream binaryAttachment, Parameter... parameters)
endpoint
- Facebook Graph API endpoint.useLegacyEndpoint
- Should we hit the legacy endpoint (true
) or the new Graph
endpoint (false
)?executeAsPost
- true
to execute the web request as a POST
,
false
to execute as a GET
.executeAsDelete
- true
to add a special 'treat this request as a
DELETE
' parameter.binaryAttachment
- A binary file to include in a POST
request. Pass
null
if no attachment should be sent.parameters
- Arbitrary number of parameters to send along to Facebook as part
of the API call.FacebookException
- If an error occurs while making the Facebook API POST or
processing the response.protected String makeRequestAndProcessResponse(DefaultFacebookClient.Requestor requestor)
protected void throwFacebookResponseStatusExceptionIfNecessary(String json)
error
JSON field is present, we've got a response status
error for this API call.
For Legacy errors (e.g. FQL):
If the error_code
JSON field is present, we've got a response
status error for this API call.json
- The JSON returned by Facebook in response to an API call.FacebookGraphException
- If the JSON contains a Graph API error response.FacebookResponseStatusException
- If the JSON contains an Legacy API error response.FacebookJsonMappingException
- If an error occurs while processing the JSON.protected FacebookGraphExceptionMapper createFacebookGraphExceptionMapper()
protected String toParameterString(Parameter... parameters)
parameters
- Arbitrary number of extra parameters to include in the request.FacebookJsonMappingException
- If an error occurs when building the parameter string.protected String getFacebookGraphEndpointUrl()
protected String getFacebookLegacyEndpointUrl()
protected void throwLegacyFacebookResponseStatusExceptionIfNecessary(String json)
error_code
JSON field is present, we've got a response
status error for this API call. Extracts relevant information from the JSON
and throws an exception which encapsulates it for end-user consumption.json
- The JSON returned by Facebook in response to an API call.FacebookResponseStatusException
- If the JSON contains an error code.FacebookJsonMappingException
- If an error occurs while processing the JSON.protected Parameter[] parametersWithAdditionalParameter(Parameter parameter, Parameter... parameters)
parameter
to the given parameters
array.parameter
- The parameter value to append.parameters
- The parameters to which the given parameter
is appended.parameter
and
parameters
.protected String queriesToJson(Map<String,String> queries)
queries
- The query map to convert.queries
in JSON string format.IllegalArgumentException
- If the provided queries
are invalid.protected String urlEncodedValueForParameterName(String name, String value)
value
for the parameter
named name
.
Includes special-case handling for access token parameters where we check
if the token is already URL-encoded - if so, we don't encode again. All
other parameter types are always URL-encoded.name
- The name of the parameter whose value should be URL-encoded and
returned.value
- The value of the parameter which should be URL-encoded and
returned.value
.protected void verifyParameterLegality(Parameter... parameters)
parameters
- The parameters to check.IllegalArgumentException
- If there's a parameter name collision.protected void verifyParameterPresence(String parameterName, String parameter)
parameter
isn't null
or an empty string.parameterName
- The name of the parameter (to be used in exception message).parameter
- The parameter to check.IllegalArgumentException
- If parameter
is null
or an empty string.protected void verifyParameterPresence(String parameterName, Object parameter)
parameter
isn't null
.parameterName
- The name of the parameter (to be used in exception message).parameter
- The parameter to check.IllegalArgumentException
- If parameter
is null
.Copyright © 2014. All rights reserved.