com.facebook

Class Request

java.lang.Object

com.facebook.Request

public class Request
extends Object

A single request to be sent to the Facebook Platform through either the Graph API or REST API. The Request class provides functionality relating to serializing and deserializing requests and responses, making calls in batches (with a single round-trip to the service) and making calls asynchronously. The particular service endpoint that a request targets is determined by either a graph path (see the setGraphPath method) or a REST method name (see the setRestMethod method); a single request may not target both. A Request can be executed either anonymously or representing an authenticated user. In the former case, no Session needs to be specified, while in the latter, a Session that is in an opened state must be provided. If requests are executed in a batch, a Facebook application ID must be associated with the batch, either by supplying a Session for at least one of the requests in the batch (the first one found in the batch will be used) or by calling the setDefaultBatchApplicationId method. After completion of a request, its Session, if any, will be checked to determine if its Facebook access token needs to be extended; if so, a request to extend it will be issued in the background.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Request.Callback Specifies the interface that consumers of the Request class can implement in order to be notified when a particular request completes, either successfully or with an error.
static interface	Request.GraphPlaceListCallback Specifies the interface that consumers of executePlacesSearchRequestAsync(Session, android.location.Location, int, int, String, com.facebook.Request.GraphPlaceListCallback) can use to be notified when the request completes, either successfully or with an error.
static interface	Request.GraphUserCallback Specifies the interface that consumers of executeMeRequestAsync(Session, com.facebook.Request.GraphUserCallback) can use to be notified when the request completes, either successfully or with an error.
static interface	Request.GraphUserListCallback Specifies the interface that consumers of executeMyFriendsRequestAsync(Session, com.facebook.Request.GraphUserListCallback) can use to be notified when the request completes, either successfully or with an error.

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAXIMUM_BATCH_SIZE The maximum number of requests that can be submitted in a single batch.

Constructor Summary

Constructors

Constructor and Description
Request() Constructs a request without a session, graph path, or any other parameters.
Request(Session session, String graphPath) Constructs a request with a Session to retrieve a particular graph path.
Request(Session session, String graphPath, android.os.Bundle parameters, HttpMethod httpMethod) Constructs a request with a specific Session, graph path, parameters, and HTTP method.
Request(Session session, String graphPath, android.os.Bundle parameters, HttpMethod httpMethod, Request.Callback callback) Constructs a request with a specific Session, graph path, parameters, and HTTP method.

Method Summary

Methods

Modifier and Type	Method and Description
Response	executeAndWait() Executes this request and returns the response.
static Response	executeAndWait(Request request) Executes a single request on the current thread and returns the response.
RequestAsyncTask	executeAsync() Executes this request and returns the response.
static List<Response>	executeBatchAndWait(Collection<Request> requests) Executes requests as a single batch on the current thread and returns the responses.
static List<Response>	executeBatchAndWait(Request... requests) Executes requests on the current thread as a single batch and returns the responses.
static List<Response>	executeBatchAndWait(RequestBatch requests) Executes requests on the current thread as a single batch and returns the responses.
static RequestAsyncTask	executeBatchAsync(Collection<Request> requests) Executes requests as a single batch asynchronously.
static RequestAsyncTask	executeBatchAsync(Request... requests) Executes requests as a single batch asynchronously.
static RequestAsyncTask	executeBatchAsync(RequestBatch requests) Executes requests as a single batch asynchronously.
static List<Response>	executeConnectionAndWait(HttpURLConnection connection, Collection<Request> requests) Executes requests that have already been serialized into an HttpURLConnection.
static List<Response>	executeConnectionAndWait(HttpURLConnection connection, RequestBatch requests) Executes requests that have already been serialized into an HttpURLConnection.
static RequestAsyncTask	executeConnectionAsync(android.os.Handler callbackHandler, HttpURLConnection connection, RequestBatch requests) Asynchronously executes requests that have already been serialized into an HttpURLConnection.
static RequestAsyncTask	executeConnectionAsync(HttpURLConnection connection, RequestBatch requests) Asynchronously executes requests that have already been serialized into an HttpURLConnection.
static RequestAsyncTask	executeGraphPathRequestAsync(Session session, String graphPath, Request.Callback callback) Creates a new Request configured to retrieve a particular graph path.
static RequestAsyncTask	executeMeRequestAsync(Session session, Request.GraphUserCallback callback) Creates a new Request configured to retrieve a user's own profile.
static RequestAsyncTask	executeMyFriendsRequestAsync(Session session, Request.GraphUserListCallback callback) Creates a new Request configured to retrieve a user's friend list.
static RequestAsyncTask	executePlacesSearchRequestAsync(Session session, android.location.Location location, int radiusInMeters, int resultsLimit, String searchText, Request.GraphPlaceListCallback callback) Creates a new Request that is configured to perform a search for places near a specified location via the Graph API.
static RequestAsyncTask	executePostRequestAsync(Session session, String graphPath, GraphObject graphObject, Request.Callback callback) Starts a new Request configured to post a GraphObject to a particular graph path, to either create or update the object at that path.
static RequestAsyncTask	executeRestRequestAsync(Session session, String restMethod, android.os.Bundle parameters, HttpMethod httpMethod) Creates a new Request configured to make a call to the Facebook REST API.
static RequestAsyncTask	executeStatusUpdateRequestAsync(Session session, String message, Request.Callback callback) Creates a new Request configured to post a status update to a user's feed.
static RequestAsyncTask	executeUploadPhotoRequestAsync(Session session, android.graphics.Bitmap image, Request.Callback callback) Creates a new Request configured to upload a photo to the user's default photo album.
static RequestAsyncTask	executeUploadPhotoRequestAsync(Session session, File file, Request.Callback callback) Creates a new Request configured to upload a photo to the user's default photo album.
String	getBatchEntryDependsOn() Returns the name of the request that this request entry explicitly depends on in a batched request.
String	getBatchEntryName() Returns the name of this request's entry in a batched request.
boolean	getBatchEntryOmitResultOnSuccess() Returns whether or not this batch entry will return a response if it is successful.
Request.Callback	getCallback() Returns the callback which will be called when the request finishes.
static String	getDefaultBatchApplicationId() Gets the default Facebook application ID that will be used to submit batched requests if none of those requests specifies a Session.
GraphObject	getGraphObject() Returns the GraphObject, if any, associated with this request.
String	getGraphPath() Returns the graph path of this request, if any.
HttpMethod	getHttpMethod() Returns the HttpMethod to use for this request.
android.os.Bundle	getParameters() Returns the parameters for this request.
String	getRestMethod() Returns the REST method to call for this request.
Session	getSession() Returns the Session associated with this request.
static Request	newGraphPathRequest(Session session, String graphPath, Request.Callback callback) Creates a new Request configured to retrieve a particular graph path.
static Request	newMeRequest(Session session, Request.GraphUserCallback callback) Creates a new Request configured to retrieve a user's own profile.
static Request	newMyFriendsRequest(Session session, Request.GraphUserListCallback callback) Creates a new Request configured to retrieve a user's friend list.
static Request	newPlacesSearchRequest(Session session, android.location.Location location, int radiusInMeters, int resultsLimit, String searchText, Request.GraphPlaceListCallback callback) Creates a new Request that is configured to perform a search for places near a specified location via the Graph API.
static Request	newPostRequest(Session session, String graphPath, GraphObject graphObject, Request.Callback callback) Creates a new Request configured to post a GraphObject to a particular graph path, to either create or update the object at that path.
static Request	newRestRequest(Session session, String restMethod, android.os.Bundle parameters, HttpMethod httpMethod) Creates a new Request configured to make a call to the Facebook REST API.
static Request	newStatusUpdateRequest(Session session, String message, Request.Callback callback) Creates a new Request configured to post a status update to a user's feed.
static Request	newUploadPhotoRequest(Session session, android.graphics.Bitmap image, Request.Callback callback) Creates a new Request configured to upload a photo to the user's default photo album.
static Request	newUploadPhotoRequest(Session session, File file, Request.Callback callback) Creates a new Request configured to upload a photo to the user's default photo album.
static Request	newUploadVideoRequest(Session session, File file, Request.Callback callback) Creates a new Request configured to upload a photo to the user's default photo album.
void	setBatchEntryDependsOn(String batchEntryDependsOn) Sets the name of the request entry that this request explicitly depends on in a batched request.
void	setBatchEntryName(String batchEntryName) Sets the name of this request's entry in a batched request.
void	setBatchEntryOmitResultOnSuccess(boolean batchEntryOmitResultOnSuccess) Sets whether or not this batch entry will return a response if it is successful.
void	setCallback(Request.Callback callback) Sets the callback which will be called when the request finishes.
static void	setDefaultBatchApplicationId(String applicationId) Sets the default application ID that will be used to submit batched requests if none of those requests specifies a Session.
void	setGraphObject(GraphObject graphObject) Sets the GraphObject associated with this request.
void	setGraphPath(String graphPath) Sets the graph path of this request.
void	setHttpMethod(HttpMethod httpMethod) Sets the HttpMethod to use for this request.
void	setParameters(android.os.Bundle parameters) Sets the parameters for this request.
void	setRestMethod(String restMethod) Sets the REST method to call for this request.
void	setSession(Session session) Sets the Session to use for this request.
static HttpURLConnection	toHttpConnection(Collection<Request> requests) Serializes one or more requests but does not execute them.
static HttpURLConnection	toHttpConnection(Request... requests) Serializes one or more requests but does not execute them.
static HttpURLConnection	toHttpConnection(RequestBatch requests) Serializes one or more requests but does not execute them.
String	toString() Returns a string representation of this Request, useful for debugging.

Methods inherited from class java.lang.Object

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

Field Detail

MAXIMUM_BATCH_SIZE

public static final int MAXIMUM_BATCH_SIZE

The maximum number of requests that can be submitted in a single batch. This limit is enforced on the service side by the Facebook platform, not by the Request class.

See Also:

Constant Field Values

Constructor Detail

Request

public Request()

Constructs a request without a session, graph path, or any other parameters.

Request

public Request(Session session,
       String graphPath)

Constructs a request with a Session to retrieve a particular graph path. A Session need not be provided, in which case the request is sent without an access token and thus is not executed in the context of any particular user. Only certain graph requests can be expected to succeed in this case. If a Session is provided, it must be in an opened state or the request will fail.

Parameters:

session - the Session to use, or null

graphPath - the graph path to retrieve

Request

public Request(Session session,
       String graphPath,
       android.os.Bundle parameters,
       HttpMethod httpMethod)

Constructs a request with a specific Session, graph path, parameters, and HTTP method. A Session need not be provided, in which case the request is sent without an access token and thus is not executed in the context of any particular user. Only certain graph requests can be expected to succeed in this case. If a Session is provided, it must be in an opened state or the request will fail. Depending on the httpMethod parameter, the object at the graph path may be retrieved, created, or deleted.

Parameters:

session - the Session to use, or null

graphPath - the graph path to retrieve, create, or delete

parameters - additional parameters to pass along with the Graph API request; parameters must be Strings, Numbers, Bitmaps, Dates, or Byte arrays.

httpMethod - the HttpMethod to use for the request, or null for default (HttpMethod.GET)

Request

public Request(Session session,
       String graphPath,
       android.os.Bundle parameters,
       HttpMethod httpMethod,
       Request.Callback callback)

Constructs a request with a specific Session, graph path, parameters, and HTTP method. A Session need not be provided, in which case the request is sent without an access token and thus is not executed in the context of any particular user. Only certain graph requests can be expected to succeed in this case. If a Session is provided, it must be in an opened state or the request will fail. Depending on the httpMethod parameter, the object at the graph path may be retrieved, created, or deleted.

Parameters:

session - the Session to use, or null

graphPath - the graph path to retrieve, create, or delete

parameters - additional parameters to pass along with the Graph API request; parameters must be Strings, Numbers, Bitmaps, Dates, or Byte arrays.

httpMethod - the HttpMethod to use for the request, or null for default (HttpMethod.GET)

callback - a callback that will be called when the request is completed to handle success or error conditions

Method Detail

newPostRequest

public static Request newPostRequest(Session session,
                     String graphPath,
                     GraphObject graphObject,
                     Request.Callback callback)

Creates a new Request configured to post a GraphObject to a particular graph path, to either create or update the object at that path.

Parameters:

session - the Session to use, or null; if non-null, the session must be in an opened state

graphPath - the graph path to retrieve, create, or delete

graphObject - the GraphObject to create or update

callback - a callback that will be called when the request is completed to handle success or error conditions

Returns:

a Request that is ready to execute

newRestRequest

public static Request newRestRequest(Session session,
                     String restMethod,
                     android.os.Bundle parameters,
                     HttpMethod httpMethod)

Creates a new Request configured to make a call to the Facebook REST API.

Parameters:

session - the Session to use, or null; if non-null, the session must be in an opened state

restMethod - the method in the Facebook REST API to execute

parameters - additional parameters to pass along with the Graph API request; parameters must be Strings, Numbers, Bitmaps, Dates, or Byte arrays.

httpMethod - the HTTP method to use for the request; must be one of GET, POST, or DELETE

Returns:

a Request that is ready to execute

newMeRequest

public static Request newMeRequest(Session session,
                   Request.GraphUserCallback callback)

Creates a new Request configured to retrieve a user's own profile.

Parameters:

session - the Session to use, or null; if non-null, the session must be in an opened state

callback - a callback that will be called when the request is completed to handle success or error conditions

Returns:

a Request that is ready to execute

newMyFriendsRequest

public static Request newMyFriendsRequest(Session session,
                          Request.GraphUserListCallback callback)

Creates a new Request configured to retrieve a user's friend list.

Parameters:

session - the Session to use, or null; if non-null, the session must be in an opened state

callback - a callback that will be called when the request is completed to handle success or error conditions

Returns:

a Request that is ready to execute

newUploadPhotoRequest

public static Request newUploadPhotoRequest(Session session,
                            android.graphics.Bitmap image,
                            Request.Callback callback)

Creates a new Request configured to upload a photo to the user's default photo album.

Parameters:

session - the Session to use, or null; if non-null, the session must be in an opened state

image - the image to upload

callback - a callback that will be called when the request is completed to handle success or error conditions

Returns:

a Request that is ready to execute

newUploadPhotoRequest

public static Request newUploadPhotoRequest(Session session,
                            File file,
                            Request.Callback callback)
                                     throws FileNotFoundException

Creates a new Request configured to upload a photo to the user's default photo album. The photo will be read from the specified stream.

Parameters:

session - the Session to use, or null; if non-null, the session must be in an opened state

file - the file containing the photo to upload

callback - a callback that will be called when the request is completed to handle success or error conditions

Returns:

a Request that is ready to execute

Throws:

FileNotFoundException

newUploadVideoRequest

public static Request newUploadVideoRequest(Session session,
                            File file,
                            Request.Callback callback)
                                     throws FileNotFoundException

Creates a new Request configured to upload a photo to the user's default photo album. The photo will be read from the specified file descriptor.

Parameters:

session - the Session to use, or null; if non-null, the session must be in an opened state

file - the file to upload

callback - a callback that will be called when the request is completed to handle success or error conditions

Returns:

a Request that is ready to execute

Throws:

FileNotFoundException

newGraphPathRequest

public static Request newGraphPathRequest(Session session,
                          String graphPath,
                          Request.Callback callback)

Creates a new Request configured to retrieve a particular graph path.

Parameters:

session - the Session to use, or null; if non-null, the session must be in an opened state

graphPath - the graph path to retrieve

callback - a callback that will be called when the request is completed to handle success or error conditions

Returns:

a Request that is ready to execute

newPlacesSearchRequest

public static Request newPlacesSearchRequest(Session session,
                             android.location.Location location,
                             int radiusInMeters,
                             int resultsLimit,
                             String searchText,
                             Request.GraphPlaceListCallback callback)

Creates a new Request that is configured to perform a search for places near a specified location via the Graph API. At least one of location or searchText must be specified.

Parameters:

session - the Session to use, or null; if non-null, the session must be in an opened state

location - the location around which to search; only the latitude and longitude components of the location are meaningful

radiusInMeters - the radius around the location to search, specified in meters; this is ignored if no location is specified

resultsLimit - the maximum number of results to return

searchText - optional text to search for as part of the name or type of an object

callback - a callback that will be called when the request is completed to handle success or error conditions

Returns:

a Request that is ready to execute

Throws:

FacebookException - If neither location nor searchText is specified

newStatusUpdateRequest

public static Request newStatusUpdateRequest(Session session,
                             String message,
                             Request.Callback callback)

Creates a new Request configured to post a status update to a user's feed.

Parameters:

session - the Session to use, or null; if non-null, the session must be in an opened state

message - the text of the status update

callback - a callback that will be called when the request is completed to handle success or error conditions

Returns:

a Request that is ready to execute

getGraphObject

public final GraphObject getGraphObject()

Returns the GraphObject, if any, associated with this request.

Returns:

the GraphObject associated with this requeset, or null if there is none

setGraphObject

public final void setGraphObject(GraphObject graphObject)

Sets the GraphObject associated with this request. This is meaningful only for POST requests.

Parameters:

graphObject - the GraphObject to upload along with this request

getGraphPath

public final String getGraphPath()

Returns the graph path of this request, if any.

Returns:

the graph path of this request, or null if there is none

setGraphPath

public final void setGraphPath(String graphPath)

Sets the graph path of this request. A graph path may not be set if a REST method has been specified.

Parameters:

graphPath - the graph path for this request

getHttpMethod

public final HttpMethod getHttpMethod()

Returns the HttpMethod to use for this request.

Returns:

the HttpMethod

setHttpMethod

public final void setHttpMethod(HttpMethod httpMethod)

Sets the HttpMethod to use for this request.

Parameters:

httpMethod - the HttpMethod, or null for the default (HttpMethod.GET).

getParameters

public final android.os.Bundle getParameters()

Returns the parameters for this request.

Returns:

the parameters

setParameters

public final void setParameters(android.os.Bundle parameters)

Sets the parameters for this request.

Parameters:

parameters - the parameters

getRestMethod

public final String getRestMethod()

Returns the REST method to call for this request.

Returns:

the REST method

setRestMethod

public final void setRestMethod(String restMethod)

Sets the REST method to call for this request. A REST method may not be set if a graph path has been specified.

Parameters:

restMethod - the REST method to call

getSession

public final Session getSession()

Returns the Session associated with this request.

Returns:

the Session associated with this request, or null if none has been specified

setSession

public final void setSession(Session session)

Sets the Session to use for this request. The Session does not need to be opened at the time it is specified, but it must be opened by the time the request is executed.

Parameters:

session - the Session to use for this request

getBatchEntryName

public final String getBatchEntryName()

Returns the name of this request's entry in a batched request.

Returns:

the name of this request's batch entry, or null if none has been specified

setBatchEntryName

public final void setBatchEntryName(String batchEntryName)

Sets the name of this request's entry in a batched request. This value is only used if this request is submitted as part of a batched request. It can be used to specified dependencies between requests. See Batch Requests in the Graph API documentation for more details.

Parameters:

batchEntryName - the name of this request's entry in a batched request, which must be unique within a particular batch of requests

getBatchEntryDependsOn

public final String getBatchEntryDependsOn()

Returns the name of the request that this request entry explicitly depends on in a batched request.

Returns:

the name of this request's dependency, or null if none has been specified

setBatchEntryDependsOn

public final void setBatchEntryDependsOn(String batchEntryDependsOn)

Sets the name of the request entry that this request explicitly depends on in a batched request. This value is only used if this request is submitted as part of a batched request. It can be used to specified dependencies between requests. See Batch Requests in the Graph API documentation for more details.

Parameters:

batchEntryDependsOn - the name of the request entry that this entry depends on in a batched request

getBatchEntryOmitResultOnSuccess

public final boolean getBatchEntryOmitResultOnSuccess()

Returns whether or not this batch entry will return a response if it is successful. Only applies if another request entry in the batch specifies this entry as a dependency.

Returns:

the name of this request's dependency, or null if none has been specified

setBatchEntryOmitResultOnSuccess

public final void setBatchEntryOmitResultOnSuccess(boolean batchEntryOmitResultOnSuccess)

Sets whether or not this batch entry will return a response if it is successful. Only applies if another request entry in the batch specifies this entry as a dependency. See Batch Requests in the Graph API documentation for more details.

Parameters:

batchEntryOmitResultOnSuccess - the name of the request entry that this entry depends on in a batched request

getDefaultBatchApplicationId

public static final String getDefaultBatchApplicationId()

Gets the default Facebook application ID that will be used to submit batched requests if none of those requests specifies a Session. Batched requests require an application ID, so either at least one request in a batch must specify a Session or the application ID must be specified explicitly.

Returns:

the Facebook application ID to use for batched requests if none can be determined

setDefaultBatchApplicationId

public static final void setDefaultBatchApplicationId(String applicationId)

Sets the default application ID that will be used to submit batched requests if none of those requests specifies a Session. Batched requests require an application ID, so either at least one request in a batch must specify a Session or the application ID must be specified explicitly.

Parameters:

applicationId - the Facebook application ID to use for batched requests if none can be determined

getCallback

public final Request.Callback getCallback()

Returns the callback which will be called when the request finishes.

Returns:

the callback

setCallback

public final void setCallback(Request.Callback callback)

Sets the callback which will be called when the request finishes.

Parameters:

callback - the callback

executePostRequestAsync

public static RequestAsyncTask executePostRequestAsync(Session session,
                                       String graphPath,
                                       GraphObject graphObject,
                                       Request.Callback callback)

Starts a new Request configured to post a GraphObject to a particular graph path, to either create or update the object at that path.

This should only be called from the UI thread.

Parameters:

session - the Session to use, or null; if non-null, the session must be in an opened state

graphPath - the graph path to retrieve, create, or delete

graphObject - the GraphObject to create or update

callback - a callback that will be called when the request is completed to handle success or error conditions

Returns:

a RequestAsyncTask that is executing the request

executeRestRequestAsync

public static RequestAsyncTask executeRestRequestAsync(Session session,
                                       String restMethod,
                                       android.os.Bundle parameters,
                                       HttpMethod httpMethod)

Creates a new Request configured to make a call to the Facebook REST API.

This should only be called from the UI thread.

Parameters:

session - the Session to use, or null; if non-null, the session must be in an opened state

restMethod - the method in the Facebook REST API to execute

parameters - additional parameters to pass along with the Graph API request; parameters must be Strings, Numbers, Bitmaps, Dates, or Byte arrays.

httpMethod - the HTTP method to use for the request; must be one of GET, POST, or DELETE

Returns:

a RequestAsyncTask that is executing the request

executeMeRequestAsync

public static RequestAsyncTask executeMeRequestAsync(Session session,
                                     Request.GraphUserCallback callback)

Creates a new Request configured to retrieve a user's own profile.

This should only be called from the UI thread.

Parameters:

session - the Session to use, or null; if non-null, the session must be in an opened state

callback - a callback that will be called when the request is completed to handle success or error conditions

Returns:

a RequestAsyncTask that is executing the request

executeMyFriendsRequestAsync

public static RequestAsyncTask executeMyFriendsRequestAsync(Session session,
                                            Request.GraphUserListCallback callback)

Creates a new Request configured to retrieve a user's friend list.

This should only be called from the UI thread.

Parameters:

session - the Session to use, or null; if non-null, the session must be in an opened state

callback - a callback that will be called when the request is completed to handle success or error conditions

Returns:

a RequestAsyncTask that is executing the request

executeUploadPhotoRequestAsync

public static RequestAsyncTask executeUploadPhotoRequestAsync(Session session,
                                              android.graphics.Bitmap image,
                                              Request.Callback callback)

Creates a new Request configured to upload a photo to the user's default photo album.

This should only be called from the UI thread.

Parameters:

session - the Session to use, or null; if non-null, the session must be in an opened state

image - the image to upload

callback - a callback that will be called when the request is completed to handle success or error conditions

Returns:

a RequestAsyncTask that is executing the request

executeUploadPhotoRequestAsync

public static RequestAsyncTask executeUploadPhotoRequestAsync(Session session,
                                              File file,
                                              Request.Callback callback)
                                                       throws FileNotFoundException

Creates a new Request configured to upload a photo to the user's default photo album. The photo will be read from the specified stream.

This should only be called from the UI thread.

Parameters:

session - the Session to use, or null; if non-null, the session must be in an opened state

file - the file containing the photo to upload

callback - a callback that will be called when the request is completed to handle success or error conditions

Returns:

a RequestAsyncTask that is executing the request

Throws:

FileNotFoundException

executeGraphPathRequestAsync

public static RequestAsyncTask executeGraphPathRequestAsync(Session session,
                                            String graphPath,
                                            Request.Callback callback)

Creates a new Request configured to retrieve a particular graph path.

This should only be called from the UI thread.

Parameters:

session - the Session to use, or null; if non-null, the session must be in an opened state

graphPath - the graph path to retrieve

callback - a callback that will be called when the request is completed to handle success or error conditions

Returns:

a RequestAsyncTask that is executing the request

executePlacesSearchRequestAsync

public static RequestAsyncTask executePlacesSearchRequestAsync(Session session,
                                               android.location.Location location,
                                               int radiusInMeters,
                                               int resultsLimit,
                                               String searchText,
                                               Request.GraphPlaceListCallback callback)

Creates a new Request that is configured to perform a search for places near a specified location via the Graph API.

This should only be called from the UI thread.

Parameters:

session - the Session to use, or null; if non-null, the session must be in an opened state

location - the location around which to search; only the latitude and longitude components of the location are meaningful

radiusInMeters - the radius around the location to search, specified in meters

resultsLimit - the maximum number of results to return

searchText - optional text to search for as part of the name or type of an object

callback - a callback that will be called when the request is completed to handle success or error conditions

Returns:

a RequestAsyncTask that is executing the request

Throws:

FacebookException - If neither location nor searchText is specified

executeStatusUpdateRequestAsync

public static RequestAsyncTask executeStatusUpdateRequestAsync(Session session,
                                               String message,
                                               Request.Callback callback)

Creates a new Request configured to post a status update to a user's feed.

This should only be called from the UI thread.

Parameters:

session - the Session to use, or null; if non-null, the session must be in an opened state

message - the text of the status update

callback - a callback that will be called when the request is completed to handle success or error conditions

Returns:

a RequestAsyncTask that is executing the request

executeAndWait

public final Response executeAndWait()

Executes this request and returns the response.

This should only be called if you have transitioned off the UI thread.

Returns:

the Response object representing the results of the request

Throws:

FacebookException - If there was an error in the protocol used to communicate with the service

IllegalArgumentException

executeAsync

public final RequestAsyncTask executeAsync()

Executes this request and returns the response.

This should only be called from the UI thread.

Returns:

a RequestAsyncTask that is executing the request

Throws:

IllegalArgumentException

toHttpConnection

public static HttpURLConnection toHttpConnection(Request... requests)

Serializes one or more requests but does not execute them. The resulting HttpURLConnection can be executed explicitly by the caller.

Parameters:

requests - one or more Requests to serialize

Returns:

an HttpURLConnection which is ready to execute

Throws:

FacebookException - If any of the requests in the batch are badly constructed or if there are problems contacting the service

IllegalArgumentException - if the passed in array is zero-length

NullPointerException - if the passed in array or any of its contents are null

toHttpConnection

public static HttpURLConnection toHttpConnection(Collection<Request> requests)

Serializes one or more requests but does not execute them. The resulting HttpURLConnection can be executed explicitly by the caller.

Parameters:

requests - one or more Requests to serialize

Returns:

an HttpURLConnection which is ready to execute

Throws:

FacebookException - If any of the requests in the batch are badly constructed or if there are problems contacting the service

IllegalArgumentException - if the passed in collection is empty

NullPointerException - if the passed in collection or any of its contents are null

toHttpConnection

public static HttpURLConnection toHttpConnection(RequestBatch requests)

Serializes one or more requests but does not execute them. The resulting HttpURLConnection can be executed explicitly by the caller.

Parameters:

requests - a RequestBatch to serialize

Returns:

an HttpURLConnection which is ready to execute

Throws:

FacebookException - If any of the requests in the batch are badly constructed or if there are problems contacting the service

IllegalArgumentException

executeAndWait

public static Response executeAndWait(Request request)

Executes a single request on the current thread and returns the response.

This should only be used if you have transitioned off the UI thread.

Parameters:

request - the Request to execute

Returns:

the Response object representing the results of the request

Throws:

FacebookException - If there was an error in the protocol used to communicate with the service

executeBatchAndWait

public static List<Response> executeBatchAndWait(Request... requests)

Executes requests on the current thread as a single batch and returns the responses.

This should only be used if you have transitioned off the UI thread.

Parameters:

requests - the Requests to execute

Returns:

a list of Response objects representing the results of the requests; responses are returned in the same order as the requests were specified.

Throws:

NullPointerException - In case of a null request

FacebookException - If there was an error in the protocol used to communicate with the service

executeBatchAndWait

public static List<Response> executeBatchAndWait(Collection<Request> requests)

Executes requests as a single batch on the current thread and returns the responses.

This should only be used if you have transitioned off the UI thread.

Parameters:

requests - the Requests to execute

Returns:

a list of Response objects representing the results of the requests; responses are returned in the same order as the requests were specified.

Throws:

FacebookException - If there was an error in the protocol used to communicate with the service

executeBatchAndWait

public static List<Response> executeBatchAndWait(RequestBatch requests)

Executes requests on the current thread as a single batch and returns the responses.

This should only be used if you have transitioned off the UI thread.

Parameters:

requests - the batch of Requests to execute

Returns:

a list of Response objects representing the results of the requests; responses are returned in the same order as the requests were specified.

Throws:

FacebookException - If there was an error in the protocol used to communicate with the service

IllegalArgumentException - if the passed in RequestBatch is empty

NullPointerException - if the passed in RequestBatch or any of its contents are null

executeBatchAsync

public static RequestAsyncTask executeBatchAsync(Request... requests)

Executes requests as a single batch asynchronously. This function will return immediately, and the requests will be processed on a separate thread. In order to process results of a request, or determine whether a request succeeded or failed, a callback must be specified (see the setCallback method).

This should only be called from the UI thread.

Parameters:

requests - the Requests to execute

Returns:

a RequestAsyncTask that is executing the request

Throws:

NullPointerException - If a null request is passed in

executeBatchAsync

public static RequestAsyncTask executeBatchAsync(Collection<Request> requests)

Executes requests as a single batch asynchronously. This function will return immediately, and the requests will be processed on a separate thread. In order to process results of a request, or determine whether a request succeeded or failed, a callback must be specified (see the setCallback method).

This should only be called from the UI thread.

Parameters:

requests - the Requests to execute

Returns:

a RequestAsyncTask that is executing the request

Throws:

IllegalArgumentException - if the passed in collection is empty

NullPointerException - if the passed in collection or any of its contents are null

executeBatchAsync

public static RequestAsyncTask executeBatchAsync(RequestBatch requests)

Executes requests as a single batch asynchronously. This function will return immediately, and the requests will be processed on a separate thread. In order to process results of a request, or determine whether a request succeeded or failed, a callback must be specified (see the setCallback method).

This should only be called from the UI thread.

Parameters:

requests - the RequestBatch to execute

Returns:

a RequestAsyncTask that is executing the request

Throws:

IllegalArgumentException - if the passed in RequestBatch is empty

NullPointerException - if the passed in RequestBatch or any of its contents are null

executeConnectionAndWait

public static List<Response> executeConnectionAndWait(HttpURLConnection connection,
                                      Collection<Request> requests)

Executes requests that have already been serialized into an HttpURLConnection. No validation is done that the contents of the connection actually reflect the serialized requests, so it is the caller's responsibility to ensure that it will correctly generate the desired responses.

This should only be called if you have transitioned off the UI thread.

Parameters:

connection - the HttpURLConnection that the requests were serialized into

requests - the requests represented by the HttpURLConnection

Returns:

a list of Responses corresponding to the requests

Throws:

FacebookException - If there was an error in the protocol used to communicate with the service

executeConnectionAndWait

public static List<Response> executeConnectionAndWait(HttpURLConnection connection,
                                      RequestBatch requests)

Executes requests that have already been serialized into an HttpURLConnection. No validation is done that the contents of the connection actually reflect the serialized requests, so it is the caller's responsibility to ensure that it will correctly generate the desired responses.

This should only be called if you have transitioned off the UI thread.

Parameters:

connection - the HttpURLConnection that the requests were serialized into

requests - the RequestBatch represented by the HttpURLConnection

Returns:

a list of Responses corresponding to the requests

Throws:

FacebookException - If there was an error in the protocol used to communicate with the service

executeConnectionAsync

public static RequestAsyncTask executeConnectionAsync(HttpURLConnection connection,
                                      RequestBatch requests)

Asynchronously executes requests that have already been serialized into an HttpURLConnection. No validation is done that the contents of the connection actually reflect the serialized requests, so it is the caller's responsibility to ensure that it will correctly generate the desired responses. This function will return immediately, and the requests will be processed on a separate thread. In order to process results of a request, or determine whether a request succeeded or failed, a callback must be specified (see the setCallback method).

This should only be called from the UI thread.

Parameters:

connection - the HttpURLConnection that the requests were serialized into

requests - the requests represented by the HttpURLConnection

Returns:

a RequestAsyncTask that is executing the request

executeConnectionAsync

public static RequestAsyncTask executeConnectionAsync(android.os.Handler callbackHandler,
                                      HttpURLConnection connection,
                                      RequestBatch requests)

Asynchronously executes requests that have already been serialized into an HttpURLConnection. No validation is done that the contents of the connection actually reflect the serialized requests, so it is the caller's responsibility to ensure that it will correctly generate the desired responses. This function will return immediately, and the requests will be processed on a separate thread. In order to process results of a request, or determine whether a request succeeded or failed, a callback must be specified (see the setCallback method)

This should only be called from the UI thread.

Parameters:

callbackHandler - a Handler that will be used to post calls to the callback for each request; if null, a Handler will be instantiated on the calling thread

connection - the HttpURLConnection that the requests were serialized into

requests - the requests represented by the HttpURLConnection

Returns:

a RequestAsyncTask that is executing the request

toString

public String toString()

Returns a string representation of this Request, useful for debugging.

Overrides:

toString in class Object

Returns:

the debugging information