|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.facebook.Request
public class Request
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 |
---|
public static final int MAXIMUM_BATCH_SIZE
Constructor Detail |
---|
public Request()
public Request(Session session, String graphPath)
session
- the Session to use, or nullgraphPath
- the graph path to retrievepublic Request(Session session, String graphPath, Bundle parameters, HttpMethod httpMethod)
session
- the Session to use, or nullgraphPath
- the graph path to retrieve, create, or deleteparameters
- 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)public Request(Session session, String graphPath, Bundle parameters, HttpMethod httpMethod, Request.Callback callback)
session
- the Session to use, or nullgraphPath
- the graph path to retrieve, create, or deleteparameters
- 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 conditionsMethod Detail |
---|
public static Request newPostRequest(Session session, String graphPath, GraphObject graphObject, Request.Callback callback)
session
- the Session to use, or null; if non-null, the session must be in an opened stategraphPath
- the graph path to retrieve, create, or deletegraphObject
- the GraphObject to create or updatecallback
- a callback that will be called when the request is completed to handle success or error conditions
public static Request newRestRequest(Session session, String restMethod, Bundle parameters, HttpMethod httpMethod)
session
- the Session to use, or null; if non-null, the session must be in an opened staterestMethod
- the method in the Facebook REST API to executeparameters
- 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
public static Request newMeRequest(Session session, Request.GraphUserCallback callback)
session
- the Session to use, or null; if non-null, the session must be in an opened statecallback
- a callback that will be called when the request is completed to handle success or error conditions
public static Request newMyFriendsRequest(Session session, Request.GraphUserListCallback callback)
session
- the Session to use, or null; if non-null, the session must be in an opened statecallback
- a callback that will be called when the request is completed to handle success or error conditions
public static Request newUploadPhotoRequest(Session session, Bitmap image, Request.Callback callback)
session
- the Session to use, or null; if non-null, the session must be in an opened stateimage
- the image to uploadcallback
- a callback that will be called when the request is completed to handle success or error conditions
public static Request newUploadPhotoRequest(Session session, File file, Request.Callback callback) throws FileNotFoundException
session
- the Session to use, or null; if non-null, the session must be in an opened statefile
- the file containing the photo to uploadcallback
- a callback that will be called when the request is completed to handle success or error conditions
FileNotFoundException
public static Request newUploadVideoRequest(Session session, File file, Request.Callback callback) throws FileNotFoundException
session
- the Session to use, or null; if non-null, the session must be in an opened statefile
- the file to uploadcallback
- a callback that will be called when the request is completed to handle success or error conditions
FileNotFoundException
public static Request newGraphPathRequest(Session session, String graphPath, Request.Callback callback)
session
- the Session to use, or null; if non-null, the session must be in an opened stategraphPath
- the graph path to retrievecallback
- a callback that will be called when the request is completed to handle success or error conditions
public static Request newPlacesSearchRequest(Session session, Location location, int radiusInMeters, int resultsLimit, String searchText, Request.GraphPlaceListCallback callback)
session
- the Session to use, or null; if non-null, the session must be in an opened statelocation
- the location around which to search; only the latitude and longitude components of the location are
meaningfulradiusInMeters
- the radius around the location to search, specified in meters; this is ignored if
no location is specifiedresultsLimit
- the maximum number of results to returnsearchText
- optional text to search for as part of the name or type of an objectcallback
- a callback that will be called when the request is completed to handle success or error conditions
FacebookException
- If neither location nor searchText is specifiedpublic static Request newStatusUpdateRequest(Session session, String message, Request.Callback callback)
session
- the Session to use, or null; if non-null, the session must be in an opened statemessage
- the text of the status updatecallback
- a callback that will be called when the request is completed to handle success or error conditions
public final GraphObject getGraphObject()
public final void setGraphObject(GraphObject graphObject)
graphObject
- the GraphObject to upload along with this requestpublic final String getGraphPath()
public final void setGraphPath(String graphPath)
graphPath
- the graph path for this requestpublic final HttpMethod getHttpMethod()
HttpMethod
to use for this request.
public final void setHttpMethod(HttpMethod httpMethod)
HttpMethod
to use for this request.
httpMethod
- the HttpMethod, or null for the default (HttpMethod.GET).public final Bundle getParameters()
public final void setParameters(Bundle parameters)
parameters
- the parameterspublic final String getRestMethod()
public final void setRestMethod(String restMethod)
restMethod
- the REST method to callpublic final Session getSession()
public final void setSession(Session session)
session
- the Session to use for this requestpublic final String getBatchEntryName()
public final void setBatchEntryName(String batchEntryName)
batchEntryName
- the name of this request's entry in a batched request, which must be unique within a particular batch
of requestspublic final String getBatchEntryDependsOn()
public final void setBatchEntryDependsOn(String batchEntryDependsOn)
batchEntryDependsOn
- the name of the request entry that this entry depends on in a batched requestpublic final boolean getBatchEntryOmitResultOnSuccess()
public final void setBatchEntryOmitResultOnSuccess(boolean batchEntryOmitResultOnSuccess)
batchEntryOmitResultOnSuccess
- the name of the request entry that this entry depends on in a batched requestpublic static final String getDefaultBatchApplicationId()
public static final void setDefaultBatchApplicationId(String applicationId)
applicationId
- the Facebook application ID to use for batched requests if none can be determinedpublic final Request.Callback getCallback()
public final void setCallback(Request.Callback callback)
callback
- the callbackpublic static RequestAsyncTask executePostRequestAsync(Session session, String graphPath, GraphObject graphObject, Request.Callback callback)
session
- the Session to use, or null; if non-null, the session must be in an opened stategraphPath
- the graph path to retrieve, create, or deletegraphObject
- the GraphObject to create or updatecallback
- a callback that will be called when the request is completed to handle success or error conditions
public static RequestAsyncTask executeRestRequestAsync(Session session, String restMethod, Bundle parameters, HttpMethod httpMethod)
session
- the Session to use, or null; if non-null, the session must be in an opened staterestMethod
- the method in the Facebook REST API to executeparameters
- 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
public static RequestAsyncTask executeMeRequestAsync(Session session, Request.GraphUserCallback callback)
session
- the Session to use, or null; if non-null, the session must be in an opened statecallback
- a callback that will be called when the request is completed to handle success or error conditions
public static RequestAsyncTask executeMyFriendsRequestAsync(Session session, Request.GraphUserListCallback callback)
session
- the Session to use, or null; if non-null, the session must be in an opened statecallback
- a callback that will be called when the request is completed to handle success or error conditions
public static RequestAsyncTask executeUploadPhotoRequestAsync(Session session, Bitmap image, Request.Callback callback)
session
- the Session to use, or null; if non-null, the session must be in an opened stateimage
- the image to uploadcallback
- a callback that will be called when the request is completed to handle success or error conditions
public static RequestAsyncTask executeUploadPhotoRequestAsync(Session session, File file, Request.Callback callback) throws FileNotFoundException
session
- the Session to use, or null; if non-null, the session must be in an opened statefile
- the file containing the photo to uploadcallback
- a callback that will be called when the request is completed to handle success or error conditions
FileNotFoundException
public static RequestAsyncTask executeGraphPathRequestAsync(Session session, String graphPath, Request.Callback callback)
session
- the Session to use, or null; if non-null, the session must be in an opened stategraphPath
- the graph path to retrievecallback
- a callback that will be called when the request is completed to handle success or error conditions
public static RequestAsyncTask executePlacesSearchRequestAsync(Session session, Location location, int radiusInMeters, int resultsLimit, String searchText, Request.GraphPlaceListCallback callback)
session
- the Session to use, or null; if non-null, the session must be in an opened statelocation
- the location around which to search; only the latitude and longitude components of the location are
meaningfulradiusInMeters
- the radius around the location to search, specified in metersresultsLimit
- the maximum number of results to returnsearchText
- optional text to search for as part of the name or type of an objectcallback
- a callback that will be called when the request is completed to handle success or error conditions
FacebookException
- If neither location nor searchText is specifiedpublic static RequestAsyncTask executeStatusUpdateRequestAsync(Session session, String message, Request.Callback callback)
session
- the Session to use, or null; if non-null, the session must be in an opened statemessage
- the text of the status updatecallback
- a callback that will be called when the request is completed to handle success or error conditions
public final Response executeAndWait()
FacebookException
- If there was an error in the protocol used to communicate with the service
IllegalArgumentException
public final RequestAsyncTask executeAsync()
IllegalArgumentException
public static HttpURLConnection toHttpConnection(Request... requests)
requests
- one or more Requests to serialize
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 nullpublic static HttpURLConnection toHttpConnection(Collection<Request> requests)
requests
- one or more Requests to serialize
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 nullpublic static HttpURLConnection toHttpConnection(RequestBatch requests)
requests
- a RequestBatch to serialize
FacebookException
- If any of the requests in the batch are badly constructed or if there are problems
contacting the service
IllegalArgumentException
public static Response executeAndWait(Request request)
request
- the Request to execute
FacebookException
- If there was an error in the protocol used to communicate with the servicepublic static List<Response> executeBatchAndWait(Request... requests)
requests
- the Requests to execute
NullPointerException
- In case of a null request
FacebookException
- If there was an error in the protocol used to communicate with the servicepublic static List<Response> executeBatchAndWait(Collection<Request> requests)
requests
- the Requests to execute
FacebookException
- If there was an error in the protocol used to communicate with the servicepublic static List<Response> executeBatchAndWait(RequestBatch requests)
requests
- the batch of Requests to execute
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 nullpublic static RequestAsyncTask executeBatchAsync(Request... requests)
setCallback
method).
This should only be called from the UI thread.
requests
- the Requests to execute
NullPointerException
- If a null request is passed inpublic static RequestAsyncTask executeBatchAsync(Collection<Request> requests)
setCallback
method).
This should only be called from the UI thread.
requests
- the Requests to execute
IllegalArgumentException
- if the passed in collection is empty
NullPointerException
- if the passed in collection or any of its contents are nullpublic static RequestAsyncTask executeBatchAsync(RequestBatch requests)
setCallback
method).
This should only be called from the UI thread.
requests
- the RequestBatch to execute
IllegalArgumentException
- if the passed in RequestBatch is empty
NullPointerException
- if the passed in RequestBatch or any of its contents are nullpublic static List<Response> executeConnectionAndWait(HttpURLConnection connection, Collection<Request> requests)
connection
- the HttpURLConnection that the requests were serialized intorequests
- the requests represented by the HttpURLConnection
FacebookException
- If there was an error in the protocol used to communicate with the servicepublic static List<Response> executeConnectionAndWait(HttpURLConnection connection, RequestBatch requests)
connection
- the HttpURLConnection that the requests were serialized intorequests
- the RequestBatch represented by the HttpURLConnection
FacebookException
- If there was an error in the protocol used to communicate with the servicepublic static RequestAsyncTask executeConnectionAsync(HttpURLConnection connection, RequestBatch requests)
setCallback
method).
This should only be called from the UI thread.
connection
- the HttpURLConnection that the requests were serialized intorequests
- the requests represented by the HttpURLConnection
public static RequestAsyncTask executeConnectionAsync(Handler callbackHandler, HttpURLConnection connection, RequestBatch requests)
setCallback
method)
This should only be called from the UI thread.
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 threadconnection
- the HttpURLConnection that the requests were serialized intorequests
- the requests represented by the HttpURLConnection
public String toString()
toString
in class Object
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |