Subversion Repositories SmartDukaan

/**

 * Copyright 2010-present Facebook.

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *    http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

package com.facebook;

import android.content.Context;

import android.graphics.Bitmap;

import android.location.Location;

import android.net.Uri;

import android.os.*;

import android.text.TextUtils;

import android.util.Log;

import android.util.Pair;

import com.facebook.internal.*;

import com.facebook.model.*;

import org.json.JSONArray;

import org.json.JSONException;

import org.json.JSONObject;

import java.io.*;

import java.net.HttpURLConnection;

import java.net.MalformedURLException;

import java.net.URL;

import java.net.URLEncoder;

import java.text.SimpleDateFormat;

import java.util.*;

import java.util.Map.Entry;

import java.util.regex.Matcher;

import java.util.regex.Pattern;

/**

 * A single request to be sent to the Facebook Platform through the <a

 * href="https://developers.facebook.com/docs/reference/api/">Graph API</a>. 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 a graph path (see the

 * {@link #setGraphPath(String) setGraphPath} method).

 *

 * 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

 * {@link #setDefaultBatchApplicationId(String) 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.

 */

public class Request {

    /**

     * 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.

     */

    public static final int MAXIMUM_BATCH_SIZE = 50;

    public static final String TAG = Request.class.getSimpleName();

    private static final String ME = "me";

    private static final String MY_FRIENDS = "me/friends";

    private static final String MY_PHOTOS = "me/photos";

    private static final String MY_VIDEOS = "me/videos";

    private static final String VIDEOS_SUFFIX = "/videos";

    private static final String SEARCH = "search";

    private static final String MY_FEED = "me/feed";

    private static final String MY_STAGING_RESOURCES = "me/staging_resources";

    private static final String MY_OBJECTS_FORMAT = "me/objects/%s";

    private static final String MY_ACTION_FORMAT = "me/%s";

    private static final String USER_AGENT_BASE = "FBAndroidSDK";

    private static final String USER_AGENT_HEADER = "User-Agent";

    private static final String CONTENT_TYPE_HEADER = "Content-Type";

    private static final String ACCEPT_LANGUAGE_HEADER = "Accept-Language";

    // Parameter names/values

    private static final String PICTURE_PARAM = "picture";

    private static final String FORMAT_PARAM = "format";

    private static final String FORMAT_JSON = "json";

    private static final String SDK_PARAM = "sdk";

    private static final String SDK_ANDROID = "android";

    private static final String ACCESS_TOKEN_PARAM = "access_token";

    private static final String BATCH_ENTRY_NAME_PARAM = "name";

    private static final String BATCH_ENTRY_OMIT_RESPONSE_ON_SUCCESS_PARAM = "omit_response_on_success";

    private static final String BATCH_ENTRY_DEPENDS_ON_PARAM = "depends_on";

    private static final String BATCH_APP_ID_PARAM = "batch_app_id";

    private static final String BATCH_RELATIVE_URL_PARAM = "relative_url";

    private static final String BATCH_BODY_PARAM = "body";

    private static final String BATCH_METHOD_PARAM = "method";

    private static final String BATCH_PARAM = "batch";

    private static final String ATTACHMENT_FILENAME_PREFIX = "file";

    private static final String ATTACHED_FILES_PARAM = "attached_files";

    private static final String ISO_8601_FORMAT_STRING = "yyyy-MM-dd'T'HH:mm:ssZ";

    private static final String STAGING_PARAM = "file";

    private static final String OBJECT_PARAM = "object";

    private static final String MIME_BOUNDARY = "3i2ndDfv2rTHiSisAbouNdArYfORhtTPEefj3q2f";

    private static String defaultBatchApplicationId;

    // Group 1 in the pattern is the path without the version info

    private static Pattern versionPattern = Pattern.compile("^/?v\\d+\\.\\d+/(.*)");

    private Session session;

    private HttpMethod httpMethod;

    private String graphPath;

    private GraphObject graphObject;

    private String batchEntryName;

    private String batchEntryDependsOn;

    private boolean batchEntryOmitResultOnSuccess = true;

    private Bundle parameters;

    private Callback callback;

    private String overriddenURL;

    private Object tag;

    private String version;

    private boolean skipClientToken = false;

    /**

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

     */

    public Request() {

        this(null, null, null, null, null);

    }

    /**

     * 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.

     *

     * @param session

     *            the Session to use, or null

     * @param graphPath

     *            the graph path to retrieve

     */

    public Request(Session session, String graphPath) {

        this(session, graphPath, null, null, null);

    }

    /**

     * 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.

     *

     * @param session

     *            the Session to use, or null

     * @param graphPath

     *            the graph path to retrieve, create, or delete

     * @param parameters

     *            additional parameters to pass along with the Graph API request; parameters must be Strings, Numbers,

     *            Bitmaps, Dates, or Byte arrays.

     * @param httpMethod

     *            the {@link HttpMethod} to use for the request, or null for default (HttpMethod.GET)

     */

    public Request(Session session, String graphPath, Bundle parameters, HttpMethod httpMethod) {

        this(session, graphPath, parameters, httpMethod, null);

    }

    /**

     * 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.

     *

     * @param session

     *            the Session to use, or null

     * @param graphPath

     *            the graph path to retrieve, create, or delete

     * @param parameters

     *            additional parameters to pass along with the Graph API request; parameters must be Strings, Numbers,

     *            Bitmaps, Dates, or Byte arrays.

     * @param httpMethod

     *            the {@link HttpMethod} to use for the request, or null for default (HttpMethod.GET)

     * @param callback

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

     */

    public Request(Session session, String graphPath, Bundle parameters, HttpMethod httpMethod, Callback callback) {

        this(session, graphPath, parameters, httpMethod, callback, null);

    }

    /**

     * 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.

     *

     * @param session

     *            the Session to use, or null

     * @param graphPath

     *            the graph path to retrieve, create, or delete

     * @param parameters

     *            additional parameters to pass along with the Graph API request; parameters must be Strings, Numbers,

     *            Bitmaps, Dates, or Byte arrays.

     * @param httpMethod

     *            the {@link HttpMethod} to use for the request, or null for default (HttpMethod.GET)

     * @param callback

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

     * @param version

     *            the version of the Graph API

     */

    public Request(Session session, String graphPath, Bundle parameters, HttpMethod httpMethod, Callback callback, String version) {

        this.session = session;

        this.graphPath = graphPath;

        this.callback = callback;

        this.version = version;

        setHttpMethod(httpMethod);

        if (parameters != null) {

            this.parameters = new Bundle(parameters);

        } else {

            this.parameters = new Bundle();

        }

        if (this.version == null) {

            this.version = ServerProtocol.getAPIVersion();

        }

    }

    Request(Session session, URL overriddenURL) {

        this.session = session;

        this.overriddenURL = overriddenURL.toString();

        setHttpMethod(HttpMethod.GET);

        this.parameters = new Bundle();

    }

    /**

     * Creates a new Request configured to post a GraphObject to a particular graph path, to either create or update the

     * object at that path.

     *

     * @param session

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

     * @param graphPath

     *            the graph path to retrieve, create, or delete

     * @param graphObject

     *            the GraphObject to create or update

     * @param callback

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

     * @return a Request that is ready to execute

     */

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

        Request request = new Request(session, graphPath, null, HttpMethod.POST , callback);

        request.setGraphObject(graphObject);

        return request;

    }

    /**

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

     *

     * @param session

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

     * @param callback

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

     * @return a Request that is ready to execute

     */

    public static Request newMeRequest(Session session, final GraphUserCallback callback) {

        Callback wrapper = new Callback() {

            @Override

            public void onCompleted(Response response) {

                if (callback != null) {

                    callback.onCompleted(response.getGraphObjectAs(GraphUser.class), response);

                }

            }

        };

        return new Request(session, ME, null, null, wrapper);

    }

    /**

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

     *

     * @param session

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

     * @param callback

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

     * @return a Request that is ready to execute

     */

    public static Request newMyFriendsRequest(Session session, final GraphUserListCallback callback) {

        Callback wrapper = new Callback() {

            @Override

            public void onCompleted(Response response) {

                if (callback != null) {

                    callback.onCompleted(typedListFromResponse(response, GraphUser.class), response);

                }

            }

        };

        return new Request(session, MY_FRIENDS, null, null, wrapper);

    }

    /**

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

     *

     * @param session

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

     * @param image

     *            the image to upload

     * @param callback

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

     * @return a Request that is ready to execute

     */

    public static Request newUploadPhotoRequest(Session session, Bitmap image, Callback callback) {

        Bundle parameters = new Bundle(1);

        parameters.putParcelable(PICTURE_PARAM, image);

        return new Request(session, MY_PHOTOS, parameters, HttpMethod.POST, callback);

    }

    /**

     * 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.

     *

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

     * @param file     the file containing the photo to upload

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

     * @return a Request that is ready to execute

     */

    public static Request newUploadPhotoRequest(Session session, File file,

            Callback callback) throws FileNotFoundException {

        ParcelFileDescriptor descriptor = ParcelFileDescriptor.open(file, ParcelFileDescriptor.MODE_READ_ONLY);

        Bundle parameters = new Bundle(1);

        parameters.putParcelable(PICTURE_PARAM, descriptor);

        return new Request(session, MY_PHOTOS, parameters, HttpMethod.POST, callback);

    }

    /**

     * 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.

     *

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

     * @param file     the file to upload

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

     * @return a Request that is ready to execute

     */

    public static Request newUploadVideoRequest(Session session, File file,

            Callback callback) throws FileNotFoundException {

        ParcelFileDescriptor descriptor = ParcelFileDescriptor.open(file, ParcelFileDescriptor.MODE_READ_ONLY);

        Bundle parameters = new Bundle(1);

        parameters.putParcelable(file.getName(), descriptor);

        return new Request(session, MY_VIDEOS, parameters, HttpMethod.POST, callback);

    }

    /**

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

     *

     * @param session

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

     * @param graphPath

     *            the graph path to retrieve

     * @param callback

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

     * @return a Request that is ready to execute

     */

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

        return new Request(session, graphPath, null, null, 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.

     *

     * @param session

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

     * @param location

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

     *            meaningful

     * @param radiusInMeters

     *            the radius around the location to search, specified in meters; this is ignored if

     *            no location is specified

     * @param resultsLimit

     *            the maximum number of results to return

     * @param searchText

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

     * @param callback

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

     * @return a Request that is ready to execute

     *

     * @throws FacebookException If neither location nor searchText is specified

     */

    public static Request newPlacesSearchRequest(Session session, Location location, int radiusInMeters,

            int resultsLimit, String searchText, final GraphPlaceListCallback callback) {

        if (location == null && Utility.isNullOrEmpty(searchText)) {

            throw new FacebookException("Either location or searchText must be specified.");

        }

        Bundle parameters = new Bundle(5);

        parameters.putString("type", "place");

        parameters.putInt("limit", resultsLimit);

        if (location != null) {

            parameters.putString("center",

                    String.format(Locale.US, "%f,%f", location.getLatitude(), location.getLongitude()));

            parameters.putInt("distance", radiusInMeters);

        }

        if (!Utility.isNullOrEmpty(searchText)) {

            parameters.putString("q", searchText);

        }

        Callback wrapper = new Callback() {

            @Override

            public void onCompleted(Response response) {

                if (callback != null) {

                    callback.onCompleted(typedListFromResponse(response, GraphPlace.class), response);

                }

            }

        };

        return new Request(session, SEARCH, parameters, HttpMethod.GET, wrapper);

    }

    /**

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

     *

     * @param session

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

     * @param message

     *            the text of the status update

     * @param callback

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

     * @return a Request that is ready to execute

     */

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

        return newStatusUpdateRequest(session, message, (String)null, null, callback);

    }

    /**

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

     *

     * @param session

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

     * @param message

     *            the text of the status update

     * @param placeId

     *            an optional place id to associate with the post

     * @param tagIds

     *            an optional list of user ids to tag in the post

     * @param callback

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

     * @return a Request that is ready to execute

     */

    private static Request newStatusUpdateRequest(Session session, String message, String placeId, List<String> tagIds,

            Callback callback) {

        Bundle parameters = new Bundle();

        parameters.putString("message", message);

        if (placeId != null) {

            parameters.putString("place", placeId);

        }

        if (tagIds != null && tagIds.size() > 0) {

            String tags = TextUtils.join(",", tagIds);

            parameters.putString("tags", tags);

        }

        return new Request(session, MY_FEED, parameters, HttpMethod.POST, callback);

    }

    /**

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

     *

     * @param session

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

     * @param message

     *            the text of the status update

     * @param place

     *            an optional place to associate with the post

     * @param tags

     *            an optional list of users to tag in the post

     * @param callback

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

     * @return a Request that is ready to execute

     */

    public static Request newStatusUpdateRequest(Session session, String message, GraphPlace place,

            List<GraphUser> tags, Callback callback) {

        List<String> tagIds = null;

        if (tags != null) {

            tagIds = new ArrayList<String>(tags.size());

            for (GraphUser tag: tags) {

                tagIds.add(tag.getId());

            }

        }

        String placeId = place == null ? null : place.getId();

        return newStatusUpdateRequest(session, message, placeId, tagIds, callback);

    }

    /**

     * Creates a new Request configured to retrieve an App User ID for the app's Facebook user.  Callers

     * will send this ID back to their own servers, collect up a set to create a Facebook Custom Audience with,

     * and then use the resultant Custom Audience to target ads.

     * <p/>

     * The GraphObject in the response will include an "custom_audience_third_party_id" property, with the value

     * being the ID retrieved.  This ID is an encrypted encoding of the Facebook user's ID and the

     * invoking Facebook app ID.  Multiple calls with the same user will return different IDs, thus these IDs cannot be

     * used to correlate behavior across devices or applications, and are only meaningful when sent back to Facebook

     * for creating Custom Audiences.

     * <p/>

     * The ID retrieved represents the Facebook user identified in the following way: if the specified session

     * (or activeSession if the specified session is `null`) is open, the ID will represent the user associated with

     * the activeSession; otherwise the ID will represent the user logged into the native Facebook app on the device.

     * A `null` ID will be provided into the callback if a) there is no native Facebook app, b) no one is logged into

     * it, or c) the app has previously called

     * {@link Settings#setLimitEventAndDataUsage(android.content.Context, boolean)} with `true` for this user.

     * <b>You must call this method from a background thread for it to work properly.</b>

     *

     * @param session

     *            the Session to issue the Request on, or null; if non-null, the session must be in an opened state.

     *            If there is no logged-in Facebook user, null is the expected choice.

     * @param context

     *            the Application context from which the app ID will be pulled, and from which the 'attribution ID'

     *            for the Facebook user is determined.  If there has been no app ID set, an exception will be thrown.

     * @param callback

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

     *            The GraphObject in the Response will contain a "custom_audience_third_party_id" property that

     *            represents the user as described above.

     * @return a Request that is ready to execute

     */

    public static Request newCustomAudienceThirdPartyIdRequest(Session session, Context context, Callback callback) {

        return newCustomAudienceThirdPartyIdRequest(session, context, null, callback);

    }

    /**

     * Creates a new Request configured to retrieve an App User ID for the app's Facebook user.  Callers

     * will send this ID back to their own servers, collect up a set to create a Facebook Custom Audience with,

     * and then use the resultant Custom Audience to target ads.

     * <p/>

     * The GraphObject in the response will include an "custom_audience_third_party_id" property, with the value

     * being the ID retrieved.  This ID is an encrypted encoding of the Facebook user's ID and the

     * invoking Facebook app ID.  Multiple calls with the same user will return different IDs, thus these IDs cannot be

     * used to correlate behavior across devices or applications, and are only meaningful when sent back to Facebook

     * for creating Custom Audiences.

     * <p/>

     * The ID retrieved represents the Facebook user identified in the following way: if the specified session

     * (or activeSession if the specified session is `null`) is open, the ID will represent the user associated with

     * the activeSession; otherwise the ID will represent the user logged into the native Facebook app on the device.

     * A `null` ID will be provided into the callback if a) there is no native Facebook app, b) no one is logged into

     * it, or c) the app has previously called

     * {@link Settings#setLimitEventAndDataUsage(android.content.Context, boolean)} ;} with `true` for this user.

     * <b>You must call this method from a background thread for it to work properly.</b>

     *

     * @param session

     *            the Session to issue the Request on, or null; if non-null, the session must be in an opened state.

     *            If there is no logged-in Facebook user, null is the expected choice.

     * @param context

     *            the Application context from which the app ID will be pulled, and from which the 'attribution ID'

     *            for the Facebook user is determined.  If there has been no app ID set, an exception will be thrown.

     * @param applicationId

     *            explicitly specified Facebook App ID.  If null, and there's a valid session, then the application ID

     *            from the session will be used, otherwise the application ID from metadata will be used.

     * @param callback

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

     *            The GraphObject in the Response will contain a "custom_audience_third_party_id" property that

     *            represents the user as described above.

     * @return a Request that is ready to execute

     */

    public static Request newCustomAudienceThirdPartyIdRequest(Session session,

            Context context, String applicationId, Callback callback) {

        // if provided session or activeSession is opened, use it.

        if (session == null) {

            session = Session.getActiveSession();

        }

        if (session != null && !session.isOpened()) {

            session = null;

        }

        if (applicationId == null) {

            if (session != null) {

                applicationId = session.getApplicationId();

            } else {

                applicationId = Utility.getMetadataApplicationId(context);

            }

        }

        if (applicationId == null) {

            throw new FacebookException("Facebook App ID cannot be determined");

        }

        String endpoint = applicationId + "/custom_audience_third_party_id";

        AttributionIdentifiers attributionIdentifiers = AttributionIdentifiers.getAttributionIdentifiers(context);

        Bundle parameters = new Bundle();

        if (session == null) {

            // Only use the attributionID if we don't have an open session.  If we do have an open session, then

            // the user token will be used to identify the user, and is more reliable than the attributionID.

            String udid = attributionIdentifiers.getAttributionId() != null

                ? attributionIdentifiers.getAttributionId()

                : attributionIdentifiers.getAndroidAdvertiserId();

            if (attributionIdentifiers.getAttributionId() != null) {

                parameters.putString("udid", udid);

            }

        }

        // Server will choose to not provide the App User ID in the event that event usage has been limited for

        // this user for this app.

        if (Settings.getLimitEventAndDataUsage(context) || attributionIdentifiers.isTrackingLimited()) {

            parameters.putString("limit_event_usage", "1");

        }

        return new Request(session, endpoint, parameters, HttpMethod.GET, callback);

    }

    /**

     * Creates a new Request configured to upload an image to create a staging resource. Staging resources

     * allow you to post binary data such as images, in preparation for a post of an Open Graph object or action

     * which references the image. The URI returned when uploading a staging resource may be passed as the image

     * property for an Open Graph object or action.

     *

     * @param session

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

     * @param image

     *            the image to upload

     * @param callback

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

     * @return a Request that is ready to execute

     */

    public static Request newUploadStagingResourceWithImageRequest(Session session,

            Bitmap image, Callback callback) {

        Bundle parameters = new Bundle(1);

        parameters.putParcelable(STAGING_PARAM, image);

        return new Request(session, MY_STAGING_RESOURCES, parameters, HttpMethod.POST, callback);

    }

    /**

     * Creates a new Request configured to upload an image to create a staging resource. Staging resources

     * allow you to post binary data such as images, in preparation for a post of an Open Graph object or action

     * which references the image. The URI returned when uploading a staging resource may be passed as the image

     * property for an Open Graph object or action.

     *

     * @param session

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

     * @param file

     *            the file containing the image to upload

     * @param callback

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

     * @return a Request that is ready to execute

     */

    public static Request newUploadStagingResourceWithImageRequest(Session session,

            File file, Callback callback) throws FileNotFoundException {

        ParcelFileDescriptor descriptor = ParcelFileDescriptor.open(file, ParcelFileDescriptor.MODE_READ_ONLY);

        ParcelFileDescriptorWithMimeType descriptorWithMimeType = new ParcelFileDescriptorWithMimeType(descriptor, "image/png");

        Bundle parameters = new Bundle(1);

        parameters.putParcelable(STAGING_PARAM, descriptorWithMimeType);

        return new Request(session, MY_STAGING_RESOURCES, parameters, HttpMethod.POST, callback);

    }

    /**

     * Creates a new Request configured to create a user owned Open Graph object.

     *

     * @param session

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

     * @param openGraphObject

     *            the Open Graph object to create; must not be null, and must have a non-empty type and title

     * @param callback

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

     * @return a Request that is ready to execute

     */

    public static Request newPostOpenGraphObjectRequest(Session session,

            OpenGraphObject openGraphObject, Callback callback) {

        if (openGraphObject == null) {

            throw new FacebookException("openGraphObject cannot be null");

        }

        if (Utility.isNullOrEmpty(openGraphObject.getType())) {

            throw new FacebookException("openGraphObject must have non-null 'type' property");

        }

        if (Utility.isNullOrEmpty(openGraphObject.getTitle())) {

            throw new FacebookException("openGraphObject must have non-null 'title' property");

        }

        String path = String.format(MY_OBJECTS_FORMAT, openGraphObject.getType());

        Bundle bundle = new Bundle();

        bundle.putString(OBJECT_PARAM, openGraphObject.getInnerJSONObject().toString());

        return new Request(session, path, bundle, HttpMethod.POST, callback);

    }

    /**

     * Creates a new Request configured to create a user owned Open Graph object.

     *

     * @param session

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

     * @param type

     *            the fully-specified Open Graph object type (e.g., my_app_namespace:my_object_name); must not be null

     * @param title

     *            the title of the Open Graph object; must not be null

     * @param imageUrl

     *            the link to an image to be associated with the Open Graph object; may be null

     * @param url

     *            the url to be associated with the Open Graph object; may be null

     * @param description

     *            the description to be associated with the object; may be null

     * @param objectProperties

     *            any additional type-specific properties for the Open Graph object; may be null

     * @param callback

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

     *            may be null

     * @return a Request that is ready to execute

     */

    public static Request newPostOpenGraphObjectRequest(Session session, String type, String title, String imageUrl,

            String url, String description, GraphObject objectProperties, Callback callback) {

        OpenGraphObject openGraphObject = OpenGraphObject.Factory.createForPost(OpenGraphObject.class, type, title,

                imageUrl, url, description);

        if (objectProperties != null) {

            openGraphObject.setData(objectProperties);

        }

        return newPostOpenGraphObjectRequest(session, openGraphObject, callback);

    }

    /**

     * Creates a new Request configured to publish an Open Graph action.

     *

     * @param session

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

     * @param openGraphAction

     *            the Open Graph object to create; must not be null, and must have a non-empty 'type'

     * @param callback

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

     * @return a Request that is ready to execute

     */

    public static Request newPostOpenGraphActionRequest(Session session, OpenGraphAction openGraphAction,

            Callback callback) {

        if (openGraphAction == null) {

            throw new FacebookException("openGraphAction cannot be null");

        }

        if (Utility.isNullOrEmpty(openGraphAction.getType())) {

            throw new FacebookException("openGraphAction must have non-null 'type' property");

        }

        String path = String.format(MY_ACTION_FORMAT, openGraphAction.getType());

        return newPostRequest(session, path, openGraphAction, callback);

    }

    /**

     * Creates a new Request configured to delete a resource through the Graph API.

     *

     * @param session

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

     * @param id

     *            the id of the object to delete

     * @param callback

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

     * @return a Request that is ready to execute

     */

    public static Request newDeleteObjectRequest(Session session, String id, Callback callback) {

        return new Request(session, id, null, HttpMethod.DELETE, callback);

    }

    /**

     * Creates a new Request configured to update a user owned Open Graph object.

     *

     * @param session

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

     * @param openGraphObject

     *            the Open Graph object to update, which must have a valid 'id' property

     * @param callback

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

     * @return a Request that is ready to execute

     */

    public static Request newUpdateOpenGraphObjectRequest(Session session, OpenGraphObject openGraphObject,

            Callback callback) {

        if (openGraphObject == null) {

            throw new FacebookException("openGraphObject cannot be null");

        }

        String path = openGraphObject.getId();

        if (path == null) {

            throw new FacebookException("openGraphObject must have an id");

        }

        Bundle bundle = new Bundle();

        bundle.putString(OBJECT_PARAM, openGraphObject.getInnerJSONObject().toString());

        return new Request(session, path, bundle, HttpMethod.POST, callback);

    }

    /**

     * Creates a new Request configured to update a user owned Open Graph object.

     *

     * @param session

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

     * @param id

     *            the id of the Open Graph object

     * @param title

     *            the title of the Open Graph object

     * @param imageUrl

     *            the link to an image to be associated with the Open Graph object

     * @param url

     *            the url to be associated with the Open Graph object

     * @param description

     *            the description to be associated with the object

     * @param objectProperties

     *            any additional type-specific properties for the Open Graph object

     * @param callback

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

     * @return a Request that is ready to execute

     */

    public static Request newUpdateOpenGraphObjectRequest(Session session, String id, String title, String imageUrl,

            String url, String description, GraphObject objectProperties, Callback callback) {

        OpenGraphObject openGraphObject = OpenGraphObject.Factory.createForPost(OpenGraphObject.class, null, title,

                imageUrl, url, description);

        openGraphObject.setId(id);

        openGraphObject.setData(objectProperties);

        return newUpdateOpenGraphObjectRequest(session, openGraphObject, callback);

    }

    /**

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

     *

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

     */

    public final GraphObject getGraphObject() {

        return this.graphObject;

    }

    /**

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

     *

     * @param graphObject

     *            the GraphObject to upload along with this request

     */

    public final void setGraphObject(GraphObject graphObject) {

        this.graphObject = graphObject;

    }

    /**

     * Returns the graph path of this request, if any.

     *

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

     */

    public final String getGraphPath() {

        return this.graphPath;

    }

    /**

     * Sets the graph path of this request.

     *

     * @param graphPath

     *            the graph path for this request

     */

    public final void setGraphPath(String graphPath) {

        this.graphPath = graphPath;

    }

    /**

     * Returns the {@link HttpMethod} to use for this request.

     *

     * @return the HttpMethod

     */

    public final HttpMethod getHttpMethod() {

        return this.httpMethod;

    }

    /**

     * Sets the {@link HttpMethod} to use for this request.

     *

     * @param httpMethod

     *            the HttpMethod, or null for the default (HttpMethod.GET).

     */

    public final void setHttpMethod(HttpMethod httpMethod) {

        if (overriddenURL != null && httpMethod != HttpMethod.GET) {

            throw new FacebookException("Can't change HTTP method on request with overridden URL.");

            }

        this.httpMethod = (httpMethod != null) ? httpMethod : HttpMethod.GET;

    }

    /**

     * Returns the version of the API that this request will use.  By default this is the current API at the time

     * the SDK is released.

     *

     * @return the version that this request will use

     */

    public final String getVersion() {

        return this.version;

    }

    /**

     * Set the version to use for this request.  By default the version will be the current API at the time the SDK

     * is released.  Only use this if you need to explicitly override.

     *

     * @param version The version to use.  Should look like "v2.0"

     */

    public final void setVersion(String version) {

        this.version = version;

    }

    /**

     * This is an internal function that is not meant to be used by developers.

     */

    public final void setSkipClientToken(boolean skipClientToken) {

        this.skipClientToken = skipClientToken;

    }

    /**

     * Returns the parameters for this request.

     *

     * @return the parameters

     */

    public final Bundle getParameters() {

        return this.parameters;

    }

    /**

     * Sets the parameters for this request.

     *

     * @param parameters

     *            the parameters

     */

    public final void setParameters(Bundle parameters) {

        this.parameters = parameters;

    }

    /**

     * Returns the Session associated with this request.

     *

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

     */

    public final Session getSession() {

        return this.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.

     *

     * @param session

     *            the Session to use for this request

     */

    public final void setSession(Session session) {

        this.session = session;

    }

    /**

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

     *

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

     */

    public final String getBatchEntryName() {

        return this.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 <a

     * href="https://developers.facebook.com/docs/reference/api/batch/">Batch Requests</a> in the Graph API

     * documentation for more details.

     *

     * @param batchEntryName

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

     *            of requests

     */

    public final void setBatchEntryName(String batchEntryName) {

        this.batchEntryName = batchEntryName;

    }

    /**

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

     *

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

     */

    public final String getBatchEntryDependsOn() {

        return this.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 <a href="https://developers.facebook.com/docs/reference/api/batch/">Batch Requests</a> in

     * the Graph API documentation for more details.

     *

     * @param batchEntryDependsOn

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

     */

    public final void setBatchEntryDependsOn(String batchEntryDependsOn) {

        this.batchEntryDependsOn = batchEntryDependsOn;

    }