com.facebook
Class Request

java.lang.Object
  extended by 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
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
static int MAXIMUM_BATCH_SIZE
          The maximum number of requests that can be submitted in a single batch.
 
Constructor Summary
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, Bundle parameters, HttpMethod httpMethod)
          Constructs a request with a specific Session, graph path, parameters, and HTTP method.
Request(Session session, String graphPath, Bundle parameters, HttpMethod httpMethod, Request.Callback callback)
          Constructs a request with a specific Session, graph path, parameters, and HTTP method.
 
Method Summary
 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(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, 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, 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, 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.
 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, 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, 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, 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(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,
               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,
               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,
                                     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,
                                            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,
                                             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 Bundle getParameters()
Returns the parameters for this request.

Returns:
the parameters

setParameters

public final void setParameters(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,
                                                       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,
                                                              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,
                                                               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(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