/**
 * 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.widget;

import android.app.Activity;
import android.content.Context;
import android.content.Intent;
import android.graphics.Bitmap;
import android.os.Bundle;
import android.os.Parcel;
import android.os.Parcelable;
import android.support.v4.app.Fragment;
import com.facebook.*;
import com.facebook.internal.AnalyticsEvents;
import com.facebook.internal.NativeProtocol;
import com.facebook.internal.Utility;
import com.facebook.internal.Validate;
import com.facebook.model.*;
import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;

import java.io.File;
import java.util.*;

/*
 * Provides an interface for presenting dialogs provided by the Facebook application for Android. This class
 * provides builders that present a strongly-typed interface to generate properly-formed Intents for launching
 * the appropriate Activities provided by the Facebook application.
 */
public class FacebookDialog {

    public static final String COMPLETION_GESTURE_CANCEL = "cancel";

    private static final String EXTRA_DIALOG_COMPLETE_KEY = "com.facebook.platform.extra.DID_COMPLETE";
    private static final String EXTRA_DIALOG_COMPLETION_GESTURE_KEY =
            "com.facebook.platform.extra.COMPLETION_GESTURE";
    private static final String EXTRA_DIALOG_COMPLETION_ID_KEY = "com.facebook.platform.extra.POST_ID";

    private static NativeAppCallAttachmentStore attachmentStore;

    /**
     * Defines a callback interface that will be called when the user completes interacting with a Facebook
     * dialog, or if an error occurs.
     */
    public interface Callback {
        /**
         * Called when the user completes interacting with a Facebook dialog.
         *
         * @param pendingCall a PendingCall containing the call ID and original Intent used to launch the dialog
         * @param data        a Bundle containing the results of the dialog, whose contents will vary depending on the
         *                    type of dialog being displayed.
         */
        void onComplete(PendingCall pendingCall, Bundle data);

        /**
         * Called if an error occurred while presenting a Facebook dialog.
         *
         * @param pendingCall a PendingCall containing the call ID and original Intent used to launch the dialog
         * @param error       the error that occurred
         * @param data        the full set of extras associated with the activity result
         */
        void onError(PendingCall pendingCall, Exception error, Bundle data);
    }

    private interface DialogFeature {
        String getAction();
        int getMinVersion();
    }

    /**
     * Defines a set of features that may be supported by the native Share dialog exposed by the Facebook application.
     * As additional features are added, these flags may be passed to
     * {@link com.facebook.widget.FacebookDialog#canPresentShareDialog(android.content.Context,
     * com.facebook.widget.FacebookDialog.ShareDialogFeature...)}
     * to determine whether the version of the Facebook application installed on the user's device is recent
     * enough to support specific features, which in turn may be used to determine which UI, etc., to present to the
     * user.
     */
    public enum ShareDialogFeature implements DialogFeature {
        /**
         * Indicates whether the native Share dialog itself is supported by the installed version of the
         * Facebook application.
         */
        SHARE_DIALOG(NativeProtocol.PROTOCOL_VERSION_20130618),
        /**
         * Indicates whether the native Share dialog supports sharing of photo images.
         */
        PHOTOS(NativeProtocol.PROTOCOL_VERSION_20140204),
        ;

        private int minVersion;

        private ShareDialogFeature(int minVersion) {
            this.minVersion = minVersion;
        }

        /**
         * This method is for internal use only.
         */
        public String getAction() {
            return NativeProtocol.ACTION_FEED_DIALOG;
        }

        /**
         * This method is for internal use only.
         */
        public int getMinVersion() {
            return minVersion;
        }
    }

    /**
     * Defines a set of features that may be supported by the native Message dialog exposed by the Facebook Messenger application.
     * As additional features are added, these flags may be passed to
     * {@link com.facebook.widget.FacebookDialog#canPresentMessageDialog(android.content.Context,
     * com.facebook.widget.FacebookDialog.MessageDialogFeature...)}
     * to determine whether the version of the Facebook application installed on the user's device is recent
     * enough to support specific features, which in turn may be used to determine which UI, etc., to present to the
     * user.
     */
    public enum MessageDialogFeature implements DialogFeature {
        /**
         * Indicates whether the native Message dialog itself is supported by the installed version of the
         * Facebook application.
         */
        MESSAGE_DIALOG(NativeProtocol.PROTOCOL_VERSION_20140204),
        /**
         * Indicates whether the native Message dialog supports sharing of photo images.
         */
        PHOTOS(NativeProtocol.PROTOCOL_VERSION_20140324),
        ;

        private int minVersion;

        private MessageDialogFeature(int minVersion) {
            this.minVersion = minVersion;
        }

        /**
         * This method is for internal use only.
         */
        public String getAction() {
            return NativeProtocol.ACTION_MESSAGE_DIALOG;
        }

        /**
         * This method is for internal use only.
         */
        public int getMinVersion() {
            return minVersion;
        }
    }


    /**
     * Defines a set of features that may be supported by the native Open Graph dialogs exposed by the Facebook
     * application. As additional features are added, these flags may be passed to
     * {@link com.facebook.widget.FacebookDialog#canPresentOpenGraphActionDialog(android.content.Context,
     * com.facebook.widget.FacebookDialog.OpenGraphActionDialogFeature...)}
     * to determine whether the version of the Facebook application installed on the user's device is recent
     * enough to support specific features, which in turn may be used to determine which UI, etc., to present to the
     * user.
     */
    public enum OpenGraphActionDialogFeature implements DialogFeature {
        /**
         * Indicates whether the native Open Graph action dialog itself is supported by the installed version of the
         * Facebook application.
         */
        OG_ACTION_DIALOG(NativeProtocol.PROTOCOL_VERSION_20130618);

        private int minVersion;

        private OpenGraphActionDialogFeature(int minVersion) {
            this.minVersion = minVersion;
        }

        /**
         * This method is for internal use only.
         */
        public String getAction() {
            return NativeProtocol.ACTION_OGACTIONPUBLISH_DIALOG;
        }

        /**
         * This method is for internal use only.
         */
        public int getMinVersion() {
            return minVersion;
        }
    }

    /**
     * Defines a set of features that may be supported by the native Open Graph Message dialogs exposed by the Facebook
     * application. As additional features are added, these flags may be passed to
     * {@link com.facebook.widget.FacebookDialog#canPresentOpenGraphMessageDialog(android.content.Context,
     * com.facebook.widget.FacebookDialog.OpenGraphMessageDialogFeature...)}
     * to determine whether the version of the Facebook application installed on the user's device is recent
     * enough to support specific features, which in turn may be used to determine which UI, etc., to present to the
     * user.
     */
    public enum OpenGraphMessageDialogFeature implements DialogFeature {
        /**
         * Indicates whether the native Open Graph Message dialog itself is supported by the installed version of the
         * Messenger application.
         */
        OG_MESSAGE_DIALOG(NativeProtocol.PROTOCOL_VERSION_20140204);

        private int minVersion;

        private OpenGraphMessageDialogFeature(int minVersion) {
            this.minVersion = minVersion;
        }

        /**
         * This method is for internal use only.
         */
        public String getAction() {
            return NativeProtocol.ACTION_OGMESSAGEPUBLISH_DIALOG;
        }

        /**
         * This method is for internal use only.
         */
        public int getMinVersion() {
            return minVersion;
        }
    }

    interface OnPresentCallback {
        void onPresent(Context context) throws Exception;
    }

    /**
     * Determines whether the native dialog completed normally (without error or exception).
     *
     * @param result the bundle passed back to onActivityResult
     * @return true if the native dialog completed normally
     */
    public static boolean getNativeDialogDidComplete(Bundle result) {
        return result.getBoolean(EXTRA_DIALOG_COMPLETE_KEY, false);
    }

    /**
     * Returns the gesture with which the user completed the native dialog. This is only returned if the
     * user has previously authorized the calling app with basic permissions.
     *
     * @param result the bundle passed back to onActivityResult
     * @return "post" or "cancel" as the completion gesture
     */
    public static String getNativeDialogCompletionGesture(Bundle result) {
        return result.getString(EXTRA_DIALOG_COMPLETION_GESTURE_KEY);
    }

    /**
     * Returns the id of the published post. This is only returned if the user has previously given the
     * app publish permissions.
     *
     * @param result the bundle passed back to onActivityResult
     * @return the id of the published post
     */
    public static String getNativeDialogPostId(Bundle result) {
        return result.getString(EXTRA_DIALOG_COMPLETION_ID_KEY);
    }

    private Activity activity;
    private Fragment fragment;
    private PendingCall appCall;
    private OnPresentCallback onPresentCallback;

    private FacebookDialog(Activity activity, Fragment fragment, PendingCall appCall,
            OnPresentCallback onPresentCallback) {
        this.activity = activity;
        this.fragment = fragment;
        this.appCall = appCall;
        this.onPresentCallback = onPresentCallback;
    }

    /**
     * Launches an activity in the Facebook application to present the desired dialog. This method returns a
     * PendingCall that contains a unique ID associated with this call to the Facebook application. In general,
     * a calling Activity should use UiLifecycleHelper to handle incoming activity results, in order to ensure
     * proper processing of the results from this dialog.
     *
     * @return a PendingCall containing the unique call ID corresponding to this call to the Facebook application
     */
    public PendingCall present() {
        logDialogActivity(activity, fragment, getEventName(appCall.getRequestIntent()),
                AnalyticsEvents.PARAMETER_DIALOG_OUTCOME_VALUE_COMPLETED);

        if (onPresentCallback != null) {
            try {
                onPresentCallback.onPresent(activity);
            } catch (Exception e) {
                throw new FacebookException(e);
            }
        }

        if (fragment != null) {
            fragment.startActivityForResult(appCall.getRequestIntent(), appCall.getRequestCode());
        } else {
            activity.startActivityForResult(appCall.getRequestIntent(), appCall.getRequestCode());
        }
        return appCall;
    }

    /**
     * Parses the results of a dialog activity and calls the appropriate method on the provided Callback.
     *
     * @param context     the Context that is handling the activity result
     * @param appCall     an PendingCall containing the call ID and original Intent used to launch the dialog
     * @param requestCode the request code for the activity result
     * @param data        the result Intent
     * @param callback    a callback to call after parsing the results
     * @return true if the activity result was handled, false if not
     */
    public static boolean handleActivityResult(Context context, PendingCall appCall, int requestCode, Intent data,
            Callback callback) {
        if (requestCode != appCall.getRequestCode()) {
            return false;
        }

        if (attachmentStore != null) {
            attachmentStore.cleanupAttachmentsForCall(context, appCall.getCallId());
        }

        if (callback != null) {
            if (NativeProtocol.isErrorResult(data)) {
                Exception error = NativeProtocol.getErrorFromResult(data);
                callback.onError(appCall, error, data.getExtras());
            } else {
                callback.onComplete(appCall, data.getExtras());
            }
        }

        return true;
    }

    /**
     * Determines whether the version of the Facebook application installed on the user's device is recent
     * enough to support specific features of the native Share dialog, which in turn may be used to determine
     * which UI, etc., to present to the user.
     *
     * @param context  the calling Context
     * @param features zero or more features to check for; {@link com.facebook.widget.FacebookDialog.ShareDialogFeature#SHARE_DIALOG} is implicitly checked
     *                 if not explicitly specified
     * @return true if all of the specified features are supported by the currently installed version of the
     *         Facebook application; false if any of the features are not supported
     */
    public static boolean canPresentShareDialog(Context context, ShareDialogFeature... features) {
        return handleCanPresent(context, EnumSet.of(ShareDialogFeature.SHARE_DIALOG, features));
    }

    /**
     * Determines whether the version of the Facebook application installed on the user's device is recent
     * enough to support specific features of the native Message dialog, which in turn may be used to determine
     * which UI, etc., to present to the user.
     *
     * @param context  the calling Context
     * @param features zero or more features to check for; {@link com.facebook.widget.FacebookDialog.MessageDialogFeature#MESSAGE_DIALOG} is implicitly
     *                 checked if not explicitly specified
     * @return true if all of the specified features are supported by the currently installed version of the
     *         Facebook application; false if any of the features are not supported
     */
    public static boolean canPresentMessageDialog(Context context, MessageDialogFeature... features) {
        return handleCanPresent(context, EnumSet.of(MessageDialogFeature.MESSAGE_DIALOG, features));
    }

    /**
     * Determines whether the version of the Facebook application installed on the user's device is recent
     * enough to support specific features of the native Open Graph action dialog, which in turn may be used to
     * determine which UI, etc., to present to the user.
     *
     * @param context  the calling Context
     * @param features zero or more features to check for; {@link com.facebook.widget.FacebookDialog.OpenGraphActionDialogFeature#OG_ACTION_DIALOG} is implicitly
     *                 checked if not explicitly specified
     * @return true if all of the specified features are supported by the currently installed version of the
     *         Facebook application; false if any of the features are not supported
     */
    public static boolean canPresentOpenGraphActionDialog(Context context, OpenGraphActionDialogFeature... features) {
        return handleCanPresent(context, EnumSet.of(OpenGraphActionDialogFeature.OG_ACTION_DIALOG, features));
    }

    /**
     * Determines whether the version of the Facebook application installed on the user's device is recent
     * enough to support specific features of the native Open Graph Message dialog, which in turn may be used to
     * determine which UI, etc., to present to the user.
     *
     * @param context  the calling Context
     * @param features zero or more features to check for; {@link com.facebook.widget.FacebookDialog.OpenGraphMessageDialogFeature#OG_MESSAGE_DIALOG} is
     *                 implicitly checked if not explicitly specified
     * @return true if all of the specified features are supported by the currently installed version of the
     *         Facebook application; false if any of the features are not supported
     */
    public static boolean canPresentOpenGraphMessageDialog(Context context, OpenGraphMessageDialogFeature... features) {
        return handleCanPresent(context, EnumSet.of(OpenGraphMessageDialogFeature.OG_MESSAGE_DIALOG, features));
    }

    private static boolean handleCanPresent(Context context, Iterable<? extends DialogFeature> features) {
        return getProtocolVersionForNativeDialog(context, getActionForFeatures(features), getMinVersionForFeatures(features))
                != NativeProtocol.NO_PROTOCOL_AVAILABLE;
    }

    private static int getProtocolVersionForNativeDialog(Context context, String action, int requiredVersion) {
        return NativeProtocol.getLatestAvailableProtocolVersionForAction(context, action, requiredVersion);
    }

    private static NativeAppCallAttachmentStore getAttachmentStore() {
        if (attachmentStore == null) {
            attachmentStore = new NativeAppCallAttachmentStore();
        }
        return attachmentStore;
    }

    private static int getMinVersionForFeatures(Iterable<? extends DialogFeature> features) {
        int minVersion = Integer.MIN_VALUE;
        for (DialogFeature feature : features) {
            // Minimum version to support all features is the maximum of each feature's minimum version.
            minVersion = Math.max(minVersion, feature.getMinVersion());
        }
        return minVersion;
    }

    private static String getActionForFeatures(Iterable<? extends DialogFeature> features) {
        String action = null;
        for (DialogFeature feature : features) {
            // All actions in a set of DialogFeatures should have the same action
            // So we can break after assigning the first one
            action = feature.getAction();
            break;
        }
        return action;
    }

    private static void logDialogActivity(Activity activity, Fragment fragment, String eventName, String outcome) {
        AppEventsLogger logger = AppEventsLogger.newLogger(fragment != null ? fragment.getActivity() : activity);
        Bundle parameters = new Bundle();
        parameters.putString(AnalyticsEvents.PARAMETER_DIALOG_OUTCOME, outcome);
        logger.logSdkEvent(eventName, null, parameters);
    }

    static private String getEventName(Intent intent) {
        String action = intent.getStringExtra(NativeProtocol.EXTRA_PROTOCOL_ACTION);
        boolean hasPhotos = intent.hasExtra(NativeProtocol.EXTRA_PHOTOS);
        return getEventName(action, hasPhotos);
    }

    static private String getEventName(String action, boolean hasPhotos) {
        String eventName;

        if (action.equals(NativeProtocol.ACTION_FEED_DIALOG)) {
            eventName = hasPhotos ?
                    AnalyticsEvents.EVENT_NATIVE_DIALOG_TYPE_PHOTO_SHARE :
                    AnalyticsEvents.EVENT_NATIVE_DIALOG_TYPE_SHARE;
        } else if (action.equals(NativeProtocol.ACTION_MESSAGE_DIALOG)) {
            eventName = hasPhotos ?
                    AnalyticsEvents.EVENT_NATIVE_DIALOG_TYPE_PHOTO_MESSAGE :
                    AnalyticsEvents.EVENT_NATIVE_DIALOG_TYPE_MESSAGE;
        } else if (action.equals(NativeProtocol.ACTION_OGACTIONPUBLISH_DIALOG)) {
            eventName = AnalyticsEvents.EVENT_NATIVE_DIALOG_TYPE_OG_SHARE;
        } else if (action.equals(NativeProtocol.ACTION_OGMESSAGEPUBLISH_DIALOG)) {
            eventName = AnalyticsEvents.EVENT_NATIVE_DIALOG_TYPE_OG_MESSAGE;
        } else {
            throw new FacebookException("An unspecified action was presented");
        }
        return eventName;
    }

    abstract static class Builder<CONCRETE extends Builder<?>> {
        final protected Activity activity;
        final protected String applicationId;
        final protected PendingCall appCall;
        protected Fragment fragment;
        protected String applicationName;
        protected HashMap<String, Bitmap> imageAttachments = new HashMap<String, Bitmap>();
        protected HashMap<String, File> imageAttachmentFiles = new HashMap<String, File>();

        Builder(Activity activity) {
            Validate.notNull(activity, "activity");

            this.activity = activity;
            applicationId = Utility.getMetadataApplicationId(activity);
            appCall = new PendingCall(NativeProtocol.DIALOG_REQUEST_CODE);
        }

        /**
         * Sets the request code that will be passed to handleActivityResult when this activity completes; the
         * default is NativeProtocol.DIALOG_REQUEST_CODE.
         *
         * @param requestCode the request code
         * @return this instance of the builder
         */
        public CONCRETE setRequestCode(int requestCode) {
            this.appCall.setRequestCode(requestCode);
            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        /**
         * Sets the name of the application to be displayed in the dialog. If provided, this optimizes the user
         * experience as a preview of a shared item, etc., can be displayed sooner.
         *
         * @param applicationName the name of the Facebook application
         * @return this instance of the builder
         */
        public CONCRETE setApplicationName(String applicationName) {
            this.applicationName = applicationName;
            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        /**
         * Sets the fragment that should launch the dialog. This allows the dialog to be
         * launched from a Fragment, and will allow the fragment to receive the
         * {@link Fragment#onActivityResult(int, int, android.content.Intent) onActivityResult}
         * call rather than the Activity.
         *
         * @param fragment the fragment that contains this control
         */
        public CONCRETE setFragment(Fragment fragment) {
            this.fragment = fragment;
            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        /**
         * Constructs a FacebookDialog with an Intent that is correctly populated to present the dialog within
         * the Facebook application.
         *
         * @return a FacebookDialog instance
         */
        public FacebookDialog build() {
            validate();

            Bundle extras = new Bundle();
            putExtra(extras, NativeProtocol.EXTRA_APPLICATION_ID, applicationId);
            putExtra(extras, NativeProtocol.EXTRA_APPLICATION_NAME, applicationName);
            extras = setBundleExtras(extras);

            String action = getActionForFeatures(getDialogFeatures());
            int protocolVersion = getProtocolVersionForNativeDialog(activity, action,
                    getMinVersionForFeatures(getDialogFeatures()));

            Intent intent = NativeProtocol.createPlatformActivityIntent(activity, action, protocolVersion, extras);
            if (intent == null) {
                logDialogActivity(activity, fragment,
                        getEventName(action, extras.containsKey(NativeProtocol.EXTRA_PHOTOS)),
                        AnalyticsEvents.PARAMETER_DIALOG_OUTCOME_VALUE_FAILED);

                throw new FacebookException(
                        "Unable to create Intent; this likely means the Facebook app is not installed.");
            }
            appCall.setRequestIntent(intent);

            return new FacebookDialog(activity, fragment, appCall, getOnPresentCallback());
        }

        /**
         * Determines whether the native dialog can be presented (i.e., whether the required version of the
         * Facebook application is installed on the device, and whether the installed version supports all of
         * the parameters specified for the dialog).
         *
         * @return true if the dialog can be presented; false if not
         */
        public boolean canPresent() {
            return handleCanPresent(activity, getDialogFeatures());
        }

        void validate() {
        }

        OnPresentCallback getOnPresentCallback() {
            return new OnPresentCallback() {
                @Override
                public void onPresent(Context context) throws Exception {
                    // We're actually being presented, so put our attachments in the content provider.
                    if (imageAttachments != null && imageAttachments.size() > 0) {
                        getAttachmentStore().addAttachmentsForCall(context, appCall.getCallId(), imageAttachments);
                    }
                    if (imageAttachmentFiles != null && imageAttachmentFiles.size() > 0) {
                        getAttachmentStore().addAttachmentFilesForCall(context, appCall.getCallId(),
                                imageAttachmentFiles);
                    }
                }
            };
        }

        protected List<String> addImageAttachments(Collection<Bitmap> bitmaps) {
            ArrayList<String> attachmentUrls = new ArrayList<String>();
            for (Bitmap bitmap : bitmaps) {
                String attachmentName = UUID.randomUUID().toString();

                addImageAttachment(attachmentName, bitmap);

                String url = NativeAppCallContentProvider.getAttachmentUrl(applicationId, appCall.getCallId(),
                        attachmentName);
                attachmentUrls.add(url);
            }

            return attachmentUrls;
        }

        protected List<String> addImageAttachmentFiles(Collection<File> bitmapFiles) {
            ArrayList<String> attachmentUrls = new ArrayList<String>();
            for (File bitmapFile : bitmapFiles) {
                String attachmentName = UUID.randomUUID().toString();

                addImageAttachment(attachmentName, bitmapFile);

                String url = NativeAppCallContentProvider.getAttachmentUrl(applicationId, appCall.getCallId(),
                        attachmentName);
                attachmentUrls.add(url);
            }

            return attachmentUrls;
        }

        List<String> getImageAttachmentNames() {
            return new ArrayList<String>(imageAttachments.keySet());
        }

        abstract Bundle setBundleExtras(Bundle extras);

        void putExtra(Bundle extras, String key, String value) {
            if (value != null) {
                extras.putString(key, value);
            }
        }

        abstract EnumSet<? extends DialogFeature> getDialogFeatures();

        protected CONCRETE addImageAttachment(String imageName, Bitmap bitmap) {
            imageAttachments.put(imageName, bitmap);
            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        protected CONCRETE addImageAttachment(String imageName, File attachment) {
            imageAttachmentFiles.put(imageName, attachment);
            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }
    }

    private abstract static class ShareDialogBuilderBase<CONCRETE extends ShareDialogBuilderBase<?>> extends Builder<CONCRETE> {
        private String name;
        private String caption;
        private String description;
        protected String link;
        private String picture;
        private String place;
        private ArrayList<String> friends;
        private String ref;
        private boolean dataErrorsFatal;

        /**
         * Constructor.
         *
         * @param activity the Activity which is presenting the native Share dialog; must not be null
         */
        public ShareDialogBuilderBase(Activity activity) {
            super(activity);
        }

        /**
         * Sets the title of the item to be shared.
         *
         * @param name the title
         * @return this instance of the builder
         */
        public CONCRETE setName(String name) {
            this.name = name;
            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        /**
         * Sets the subtitle of the item to be shared.
         *
         * @param caption the subtitle
         * @return this instance of the builder
         */
        public CONCRETE setCaption(String caption) {
            this.caption = caption;
            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        /**
         * Sets the description of the item to be shared.
         *
         * @param description the description
         * @return this instance of the builder
         */
        public CONCRETE setDescription(String description) {
            this.description = description;
            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        /**
         * Sets the URL of the item to be shared.
         *
         * @param link the URL
         * @return this instance of the builder
         */
        public CONCRETE setLink(String link) {
            this.link = link;
            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        /**
         * Sets the URL of the image of the item to be shared.
         *
         * @param picture the URL of the image
         * @return this instance of the builder
         */
        public CONCRETE setPicture(String picture) {
            this.picture = picture;
            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        /**
         * Sets the place for the item to be shared.
         *
         * @param place the Facebook ID of the place
         * @return this instance of the builder
         */
        public CONCRETE setPlace(String place) {
            this.place = place;
            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        /**
         * Sets the tagged friends for the item to be shared.
         *
         * @param friends a list of Facebook IDs of the friends to be tagged in the shared item
         * @return this instance of the builder
         */
        public CONCRETE setFriends(List<String> friends) {
            this.friends = new ArrayList<String>(friends);
            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        /**
         * Sets the 'ref' property of the item to be shared.
         *
         * @param ref the 'ref' property
         * @return this instance of the builder
         */
        public CONCRETE setRef(String ref) {
            this.ref = ref;
            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        /**
         * Sets whether errors encountered during previewing the shared item should be considered fatal and
         * cause the dialog to return an error
         *
         * @param dataErrorsFatal true if data errors should be fatal; false if not
         * @return this instance of the builder
         */
        public CONCRETE setDataErrorsFatal(boolean dataErrorsFatal) {
            this.dataErrorsFatal = dataErrorsFatal;
            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        @Override
        Bundle setBundleExtras(Bundle extras) {
            putExtra(extras, NativeProtocol.EXTRA_APPLICATION_ID, applicationId);
            putExtra(extras, NativeProtocol.EXTRA_APPLICATION_NAME, applicationName);
            putExtra(extras, NativeProtocol.EXTRA_TITLE, name);
            putExtra(extras, NativeProtocol.EXTRA_SUBTITLE, caption);
            putExtra(extras, NativeProtocol.EXTRA_DESCRIPTION, description);
            putExtra(extras, NativeProtocol.EXTRA_LINK, link);
            putExtra(extras, NativeProtocol.EXTRA_IMAGE, picture);
            putExtra(extras, NativeProtocol.EXTRA_PLACE_TAG, place);
            putExtra(extras, NativeProtocol.EXTRA_TITLE, name);
            putExtra(extras, NativeProtocol.EXTRA_REF, ref);

            extras.putBoolean(NativeProtocol.EXTRA_DATA_FAILURES_FATAL, dataErrorsFatal);
            if (!Utility.isNullOrEmpty(friends)) {
                extras.putStringArrayList(NativeProtocol.EXTRA_FRIEND_TAGS, friends);
            }
            return extras;
        }
    }

    /**
     * Provides a builder which can construct a FacebookDialog instance suitable for presenting the native
     * Share dialog. This builder will throw an exception if the Facebook application is not installed, so it
     * should only be used if {@link com.facebook.widget.FacebookDialog#canPresentShareDialog(android.content.Context,
     * com.facebook.widget.FacebookDialog.ShareDialogFeature...)}  indicates the capability is available.
     */
    public static class ShareDialogBuilder extends ShareDialogBuilderBase<ShareDialogBuilder> {

        /**
         * Constructor.
         *
         * @param activity the Activity which is presenting the native Share dialog; must not be null
         */
        public ShareDialogBuilder(Activity activity) {
            super(activity);
        }

        @Override
        EnumSet<? extends DialogFeature> getDialogFeatures() {
            return EnumSet.of(ShareDialogFeature.SHARE_DIALOG);
        }
    }

    private static abstract class PhotoDialogBuilderBase<CONCRETE extends PhotoDialogBuilderBase<?>>
            extends Builder<CONCRETE> {
        static int MAXIMUM_PHOTO_COUNT = 6;
        private String place;
        private ArrayList<String> friends;
        private ArrayList<String> imageAttachmentUrls = new ArrayList<String>();

        /**
         * Constructor.
         *
         * @param activity the Activity which is presenting the native Share dialog; must not be null
         */
        public PhotoDialogBuilderBase(Activity activity) {
            super(activity);
        }

        /**
         * Sets the place for the item to be shared.
         *
         * @param place the Facebook ID of the place
         * @return this instance of the builder
         */
        public CONCRETE setPlace(String place) {
            this.place = place;
            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        /**
         * Sets the tagged friends for the item to be shared.
         *
         * @param friends a list of Facebook IDs of the friends to be tagged in the shared item
         * @return this instance of the builder
         */
        public CONCRETE setFriends(List<String> friends) {
            this.friends = new ArrayList<String>(friends);
            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        /**
         * <p></p>Adds one or more photos to the list of photos to display in the native Share dialog, by providing
         * an in-memory representation of the photos. The dialog's callback will be called once the user has
         * shared the photos, but the photos themselves may be uploaded in the background by the Facebook app;
         * apps wishing to be notified when the photo upload has succeeded or failed should extend the
         * FacebookBroadcastReceiver class and register it in their AndroidManifest.xml.</p>
         * <p>In order for the images to be provided to the Facebook application as part of the app call, the
         * NativeAppCallContentProvider must be specified correctly in the application's AndroidManifest.xml.</p>
         * No more than six photos may be shared at a time.
         * @param photos a collection of Files representing photos to be uploaded
         * @return this instance of the builder
         */
        public CONCRETE addPhotos(Collection<Bitmap> photos) {
            imageAttachmentUrls.addAll(addImageAttachments(photos));
            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        /**
         * Adds one or more photos to the list of photos to display in the native Share dialog, by specifying
         * their location in the file system. The dialog's callback will be called once the user has
         * shared the photos, but the photos themselves may be uploaded in the background by the Facebook app;
         * apps wishing to be notified when the photo upload has succeeded or failed should extend the
         * FacebookBroadcastReceiver class and register it in their AndroidManifest.xml.
         * No more than six photos may be shared at a time.
         * @param photos a collection of Files representing photos to be uploaded
         * @return this instance of the builder
         */
        public CONCRETE addPhotoFiles(Collection<File> photos) {
            imageAttachmentUrls.addAll(addImageAttachmentFiles(photos));
            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        abstract int getMaximumNumberOfPhotos();

        @Override
        void validate() {
            super.validate();

            if (imageAttachmentUrls.isEmpty()) {
                throw new FacebookException("Must specify at least one photo.");
            }

            if (imageAttachmentUrls.size() > getMaximumNumberOfPhotos()) {
                throw new FacebookException(String.format("Cannot add more than %d photos.", getMaximumNumberOfPhotos()));
            }
        }

        @Override
        Bundle setBundleExtras(Bundle extras) {
            putExtra(extras, NativeProtocol.EXTRA_APPLICATION_ID, applicationId);
            putExtra(extras, NativeProtocol.EXTRA_APPLICATION_NAME, applicationName);
            putExtra(extras, NativeProtocol.EXTRA_PLACE_TAG, place);
            extras.putStringArrayList(NativeProtocol.EXTRA_PHOTOS, imageAttachmentUrls);

            if (!Utility.isNullOrEmpty(friends)) {
                extras.putStringArrayList(NativeProtocol.EXTRA_FRIEND_TAGS, friends);
            }
            return extras;
        }
    }

    /**
     * Provides a builder which can construct a FacebookDialog instance suitable for presenting the native
     * Share dialog for sharing photos. This builder will throw an exception if the Facebook application is not
     * installed, so it should only be used if {@link com.facebook.widget.FacebookDialog#canPresentShareDialog(android.content.Context,
     * com.facebook.widget.FacebookDialog.ShareDialogFeature...)}  indicates the capability is available.
     */
    public static class PhotoShareDialogBuilder extends PhotoDialogBuilderBase<PhotoShareDialogBuilder> {
        /**
         * Constructor.
         *
         * @param activity the Activity which is presenting the native Share dialog; must not be null
         */
        public PhotoShareDialogBuilder(Activity activity) {
            super(activity);
        }

        @Override
        EnumSet<? extends DialogFeature> getDialogFeatures() {
            return EnumSet.of(ShareDialogFeature.SHARE_DIALOG, ShareDialogFeature.PHOTOS);
        }

        @Override
        int getMaximumNumberOfPhotos() {
            return MAXIMUM_PHOTO_COUNT;
        }
    }

    /**
     * Provides a builder which can construct a FacebookDialog instance suitable for presenting the native
     * Message dialog for sharing photos. This builder will throw an exception if the Messenger application is not
     * installed, so it should only be used if {@link com.facebook.widget.FacebookDialog#canPresentMessageDialog(android.content.Context,
     * com.facebook.widget.FacebookDialog.MessageDialogFeature...)} indicates the capability is available.
     */
    public static class PhotoMessageDialogBuilder extends PhotoDialogBuilderBase<PhotoMessageDialogBuilder> {
        /**
         * Constructor.
         *
         * @param activity the Activity which is presenting the native Message dialog; must not be null
         */
        public PhotoMessageDialogBuilder(Activity activity) {
            super(activity);
        }

        @Override
        EnumSet<? extends DialogFeature> getDialogFeatures() {
            return EnumSet.of(MessageDialogFeature.MESSAGE_DIALOG, MessageDialogFeature.PHOTOS);
        }

        @Override
        int getMaximumNumberOfPhotos() {
            return MAXIMUM_PHOTO_COUNT;
        }
    }

    /**
     * Provides a builder which can construct a FacebookDialog instance suitable for presenting the native
     * Message dialog. This builder will throw an exception if the Facebook Messenger application is not installed, so it
     * should only be used if {@link com.facebook.widget.FacebookDialog#canPresentMessageDialog(android.content.Context,
     * com.facebook.widget.FacebookDialog.MessageDialogFeature...)}  indicates the capability is available.
     */
    public static class MessageDialogBuilder extends ShareDialogBuilderBase<MessageDialogBuilder> {

        /**
         * Constructor.
         *
         * @param activity the Activity which is presenting the native Message dialog; must not be null
         */
        public MessageDialogBuilder(Activity activity) {
            super(activity);
        }

        @Override
        EnumSet<? extends DialogFeature> getDialogFeatures() {
            return EnumSet.of(MessageDialogFeature.MESSAGE_DIALOG);
        }
    }

    private static abstract class OpenGraphDialogBuilderBase<CONCRETE extends OpenGraphDialogBuilderBase<?>>
            extends Builder<CONCRETE> {

        private String previewPropertyName;
        private OpenGraphAction action;
        private String actionType;
        private boolean dataErrorsFatal;

        /**
         * Constructor.
         *
         * @param activity            the Activity which is presenting the native Open Graph action publish dialog;
         *                            must not be null
         * @param action              the Open Graph action to be published, which must contain a reference to at least one
         *                            Open Graph object with the property name specified by setPreviewPropertyName; the action
         *                            must have had its type specified via the {@link OpenGraphAction#setType(String)} method
         * @param actionType          the type of the Open Graph action to be published, which should be the namespace-qualified
         *                            name of the action type (e.g., "myappnamespace:myactiontype"); this will override the type
         *                            of the action passed in.
         * @param previewPropertyName the name of a property on the Open Graph action that contains the
         *                            Open Graph object which will be displayed as a preview to the user
         */
        @Deprecated
        public OpenGraphDialogBuilderBase(Activity activity, OpenGraphAction action, String actionType,
                String previewPropertyName) {
            super(activity);

            Validate.notNull(action, "action");
            Validate.notNullOrEmpty(actionType, "actionType");
            Validate.notNullOrEmpty(previewPropertyName, "previewPropertyName");
            if (action.getProperty(previewPropertyName) == null) {
                throw new IllegalArgumentException(
                        "A property named \"" + previewPropertyName + "\" was not found on the action.  The name of " +
                                "the preview property must match the name of an action property.");
            }
            String typeOnAction = action.getType();
            if (!Utility.isNullOrEmpty(typeOnAction) && !typeOnAction.equals(actionType)) {
                throw new IllegalArgumentException("'actionType' must match the type of 'action' if it is specified. " +
                        "Consider using OpenGraphDialogBuilderBase(Activity activity, OpenGraphAction action, " +
                        "String previewPropertyName) instead.");
            }
            this.action = action;
            this.actionType = actionType;
            this.previewPropertyName = previewPropertyName;
        }

        /**
         * Constructor.
         *
         * @param activity            the Activity which is presenting the native Open Graph action publish dialog;
         *                            must not be null
         * @param action              the Open Graph action to be published, which must contain a reference to at least one
         *                            Open Graph object with the property name specified by setPreviewPropertyName; the action
         *                            must have had its type specified via the {@link OpenGraphAction#setType(String)} method
         * @param previewPropertyName the name of a property on the Open Graph action that contains the
         *                            Open Graph object which will be displayed as a preview to the user
         */
        public OpenGraphDialogBuilderBase(Activity activity, OpenGraphAction action, String previewPropertyName) {
            super(activity);

            Validate.notNull(action, "action");
            Validate.notNullOrEmpty(action.getType(), "action.getType()");
            Validate.notNullOrEmpty(previewPropertyName, "previewPropertyName");
            if (action.getProperty(previewPropertyName) == null) {
                throw new IllegalArgumentException(
                        "A property named \"" + previewPropertyName + "\" was not found on the action.  The name of " +
                                "the preview property must match the name of an action property.");
            }

            this.action = action;
            this.actionType = action.getType();
            this.previewPropertyName = previewPropertyName;
        }

        /**
         * Sets whether errors encountered during previewing the shared item should be considered fatal and
         * cause the dialog to return an error
         *
         * @param dataErrorsFatal true if data errors should be fatal; false if not
         * @return this instance of the builder
         */
        public CONCRETE setDataErrorsFatal(boolean dataErrorsFatal) {
            this.dataErrorsFatal = dataErrorsFatal;
            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        /**
         * <p>Specifies a list of images for the Open Graph action that should be uploaded prior to publishing the
         * action. The action must already have been set prior to calling this method. This method will generate unique
         * names for the image attachments and update the action to refer to these attachments. Note that calling
         * setAction again after calling this method will not clear the image attachments already set, but the new
         * action will have no reference to the existing attachments. The images will not be marked as being
         * user-generated.</p>
         * <p/>
         * <p>In order for the images to be provided to the Facebook application as part of the app call, the
         * NativeAppCallContentProvider must be specified correctly in the application's AndroidManifest.xml.</p>
         *
         * @param bitmaps a list of Bitmaps to be uploaded and attached to the Open Graph action
         * @return this instance of the builder
         */
        public CONCRETE setImageAttachmentsForAction(List<Bitmap> bitmaps) {
            return setImageAttachmentsForAction(bitmaps, false);
        }

        /**
         * <p>Specifies a list of images for the Open Graph action that should be uploaded prior to publishing the
         * action. The action must already have been set prior to calling this method. This method will generate unique
         * names for the image attachments and update the action to refer to these attachments. Note that calling
         * setAction again after calling this method will not clear the image attachments already set, but the new
         * action will have no reference to the existing attachments. The images may be marked as being
         * user-generated -- refer to
         * <a href="https://developers.facebook.com/docs/opengraph/howtos/adding-photos-to-stories/">this article</a>
         * for more information.</p>
         * <p/>
         * <p>In order for the images to be provided to the Facebook application as part of the app call, the
         * NativeAppCallContentProvider must be specified correctly in the application's AndroidManifest.xml.</p>
         *
         * @param bitmaps         a list of Bitmaps to be uploaded and attached to the Open Graph action
         * @param isUserGenerated if true, specifies that the user_generated flag should be set for these images
         * @return this instance of the builder
         */
        public CONCRETE setImageAttachmentsForAction(List<Bitmap> bitmaps,
                boolean isUserGenerated) {
            Validate.containsNoNulls(bitmaps, "bitmaps");
            if (action == null) {
                throw new FacebookException("Can not set attachments prior to setting action.");
            }

            List<String> attachmentUrls = addImageAttachments(bitmaps);
            updateActionAttachmentUrls(attachmentUrls, isUserGenerated);

            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        /**
         * <p>Specifies a list of images for the Open Graph action that should be uploaded prior to publishing the
         * action. The action must already have been set prior to calling this method.  The images will not be marked
         * as being user-generated. This method will generate unique names for the image attachments and update the
         * action to refer to these attachments. Note that calling setAction again after calling this method will
         * not clear the image attachments already set, but the new action will have no reference to the existing
         * attachments.</p>
         * <p/>
         * <p>In order for the images to be provided to the Facebook application as part of the app call, the
         * NativeAppCallContentProvider must be specified correctly in the application's AndroidManifest.xml.</p>
         *
         * @param bitmapFiles a list of Files containing bitmaps to be uploaded and attached to the Open Graph action
         * @return this instance of the builder
         */
        public CONCRETE setImageAttachmentFilesForAction(List<File> bitmapFiles) {
            return setImageAttachmentFilesForAction(bitmapFiles, false);
        }

        /**
         * <p>Specifies a list of images for the Open Graph action that should be uploaded prior to publishing the
         * action. The action must already have been set prior to calling this method. The images may be marked as being
         * user-generated -- refer to
         * <a href="https://developers.facebook.com/docs/opengraph/howtos/adding-photos-to-stories/">this article</a>
         * for more information. This method will generate unique
         * names for the image attachments and update the action to refer to these attachments. Note that calling
         * setAction again after calling this method will not clear the image attachments already set, but the new
         * action will have no reference to the existing attachments.</p>
         * <p/>
         * <p>In order for the images to be provided to the Facebook application as part of the app call, the
         * NativeAppCallContentProvider must be specified correctly in the application's AndroidManifest.xml.</p>
         *
         * @param bitmapFiles     a list of Files containing bitmaps to be uploaded and attached to the Open Graph action
         * @param isUserGenerated if true, specifies that the user_generated flag should be set for these images
         * @return this instance of the builder
         */
        public CONCRETE setImageAttachmentFilesForAction(List<File> bitmapFiles,
                boolean isUserGenerated) {
            Validate.containsNoNulls(bitmapFiles, "bitmapFiles");
            if (action == null) {
                throw new FacebookException("Can not set attachments prior to setting action.");
            }

            List<String> attachmentUrls = addImageAttachmentFiles(bitmapFiles);
            updateActionAttachmentUrls(attachmentUrls, isUserGenerated);

            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        private void updateActionAttachmentUrls(List<String> attachmentUrls, boolean isUserGenerated) {
            List<JSONObject> attachments = action.getImage();
            if (attachments == null) {
                attachments = new ArrayList<JSONObject>(attachmentUrls.size());
            }

            for (String url : attachmentUrls) {
                JSONObject jsonObject = new JSONObject();
                try {
                    jsonObject.put(NativeProtocol.IMAGE_URL_KEY, url);
                    if (isUserGenerated) {
                        jsonObject.put(NativeProtocol.IMAGE_USER_GENERATED_KEY, true);
                    }
                } catch (JSONException e) {
                    throw new FacebookException("Unable to attach images", e);
                }
                attachments.add(jsonObject);
            }
            action.setImage(attachments);
        }


        /**
         * <p>Specifies a list of images for an Open Graph object referenced by the action that should be uploaded
         * prior to publishing the action. The images will not be marked as user-generated.
         * The action must already have been set prior to calling this method, and
         * the action must have a GraphObject-valued property with the specified property name. This method will
         * generate unique names for the image attachments and update the graph object to refer to these
         * attachments. Note that calling setObject again after calling this method, or modifying the value of the
         * specified property, will not clear the image attachments already set, but the new action (or objects)
         * will have no reference to the existing attachments.</p>
         * <p/>
         * <p>In order for the images to be provided to the Facebook application as part of the app call, the
         * NativeAppCallContentProvider must be specified correctly in the application's AndroidManifest.xml.</p>
         *
         * @param objectProperty the name of a property on the action that corresponds to an Open Graph object;
         *                       the object must be marked as a new object to be created
         *                       (i.e., {@link com.facebook.model.OpenGraphObject#getCreateObject()} must return
         *                       true) or an exception will be thrown
         * @param bitmaps        a list of Files containing bitmaps to be uploaded and attached to the Open Graph object
         * @return this instance of the builder
         */
        public CONCRETE setImageAttachmentsForObject(String objectProperty, List<Bitmap> bitmaps) {
            return setImageAttachmentsForObject(objectProperty, bitmaps, false);
        }

        /**
         * <p>Specifies a list of images for an Open Graph object referenced by the action that should be uploaded
         * prior to publishing the action. The images may be marked as being
         * user-generated -- refer to
         * <a href="https://developers.facebook.com/docs/opengraph/howtos/adding-photos-to-stories/">this article</a>
         * for more information.
         * The action must already have been set prior to calling this method, and
         * the action must have a GraphObject-valued property with the specified property name. This method will
         * generate unique names for the image attachments and update the graph object to refer to these
         * attachments. Note that calling setObject again after calling this method, or modifying the value of the
         * specified property, will not clear the image attachments already set, but the new action (or objects)
         * will have no reference to the existing attachments.</p>
         * <p/>
         * <p>In order for the images to be provided to the Facebook application as part of the app call, the
         * NativeAppCallContentProvider must be specified correctly in the application's AndroidManifest.xml.</p>
         *
         * @param objectProperty  the name of a property on the action that corresponds to an Open Graph object;
         *                        the object must be marked as a new object to be created
         *                        (i.e., {@link com.facebook.model.OpenGraphObject#getCreateObject()} must return
         *                        true) or an exception will be thrown
         * @param objectProperty  the name of a property on the action that corresponds to an Open Graph object
         * @param bitmaps         a list of Files containing bitmaps to be uploaded and attached to the Open Graph object
         * @param isUserGenerated if true, specifies that the user_generated flag should be set for these images
         * @return this instance of the builder
         */
        public CONCRETE setImageAttachmentsForObject(String objectProperty, List<Bitmap> bitmaps,
                boolean isUserGenerated) {
            Validate.notNull(objectProperty, "objectProperty");
            Validate.containsNoNulls(bitmaps, "bitmaps");
            if (action == null) {
                throw new FacebookException("Can not set attachments prior to setting action.");
            }

            List<String> attachmentUrls = addImageAttachments(bitmaps);
            updateObjectAttachmentUrls(objectProperty, attachmentUrls, isUserGenerated);

            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        /**
         * <p>Specifies a list of images for an Open Graph object referenced by the action that should be uploaded
         * prior to publishing the action. The images will not be marked as user-generated.
         * The action must already have been set prior to calling this method, and
         * the action must have a GraphObject-valued property with the specified property name. This method will
         * generate unique names for the image attachments and update the graph object to refer to these
         * attachments. Note that calling setObject again after calling this method, or modifying the value of the
         * specified property, will not clear the image attachments already set, but the new action (or objects)
         * will have no reference to the existing attachments.</p>
         * <p/>
         * <p>In order for the images to be provided to the Facebook application as part of the app call, the
         * NativeAppCallContentProvider must be specified correctly in the application's AndroidManifest.xml.</p>
         *
         * @param objectProperty the name of a property on the action that corresponds to an Open Graph object;
         *                       the object must be marked as a new object to be created
         *                       (i.e., {@link com.facebook.model.OpenGraphObject#getCreateObject()} must return
         *                       true) or an exception will be thrown
         * @param bitmapFiles    a list of Bitmaps to be uploaded and attached to the Open Graph object
         * @return this instance of the builder
         */
        public CONCRETE setImageAttachmentFilesForObject(String objectProperty,
                List<File> bitmapFiles) {
            return setImageAttachmentFilesForObject(objectProperty, bitmapFiles, false);
        }

        /**
         * <p>Specifies a list of images for an Open Graph object referenced by the action that should be uploaded
         * prior to publishing the action. The images may be marked as being
         * user-generated -- refer to
         * <a href="https://developers.facebook.com/docs/opengraph/howtos/adding-photos-to-stories/">this article</a>
         * for more information.
         * The action must already have been set prior to calling this method, and
         * the action must have a GraphObject-valued property with the specified property name. This method will
         * generate unique names for the image attachments and update the graph object to refer to these
         * attachments. Note that calling setObject again after calling this method, or modifying the value of the
         * specified property, will not clear the image attachments already set, but the new action (or objects)
         * will have no reference to the existing attachments.</p>
         * <p/>
         * <p>In order for the images to be provided to the Facebook application as part of the app call, the
         * NativeAppCallContentProvider must be specified correctly in the application's AndroidManifest.xml.</p>
         *
         * @param objectProperty  the name of a property on the action that corresponds to an Open Graph object;
         *                        the object must be marked as a new object to be created
         *                        (i.e., {@link com.facebook.model.OpenGraphObject#getCreateObject()} must return
         *                        true) or an exception will be thrown
         * @param bitmapFiles     a list of Bitmaps to be uploaded and attached to the Open Graph object
         * @param isUserGenerated if true, specifies that the user_generated flag should be set for these images
         * @return this instance of the builder
         */
        public CONCRETE setImageAttachmentFilesForObject(String objectProperty,
                List<File> bitmapFiles, boolean isUserGenerated) {
            Validate.notNull(objectProperty, "objectProperty");
            Validate.containsNoNulls(bitmapFiles, "bitmapFiles");
            if (action == null) {
                throw new FacebookException("Can not set attachments prior to setting action.");
            }

            List<String> attachmentUrls = addImageAttachmentFiles(bitmapFiles);
            updateObjectAttachmentUrls(objectProperty, attachmentUrls, isUserGenerated);

            @SuppressWarnings("unchecked")
            CONCRETE result = (CONCRETE) this;
            return result;
        }

        void updateObjectAttachmentUrls(String objectProperty, List<String> attachmentUrls, boolean isUserGenerated) {
            final OpenGraphObject object;
            try {
                object = action.getPropertyAs(objectProperty, OpenGraphObject.class);
                if (object == null) {
                    throw new IllegalArgumentException("Action does not contain a property '" + objectProperty + "'");
                }
            } catch (FacebookGraphObjectException exception) {
                throw new IllegalArgumentException("Property '" + objectProperty + "' is not a graph object");
            }
            if (!object.getCreateObject()) {
                throw new IllegalArgumentException(
                        "The Open Graph object in '" + objectProperty + "' is not marked for creation");
            }

            GraphObjectList<GraphObject> attachments = object.getImage();
            if (attachments == null) {
                attachments = GraphObject.Factory.createList(GraphObject.class);
            }
            for (String url : attachmentUrls) {
                GraphObject graphObject = GraphObject.Factory.create();
                graphObject.setProperty(NativeProtocol.IMAGE_URL_KEY, url);
                if (isUserGenerated) {
                    graphObject.setProperty(NativeProtocol.IMAGE_USER_GENERATED_KEY, true);
                }
                attachments.add(graphObject);
            }
            object.setImage(attachments);
        }

        @Override
        Bundle setBundleExtras(Bundle extras) {
            putExtra(extras, NativeProtocol.EXTRA_PREVIEW_PROPERTY_NAME, previewPropertyName);
            putExtra(extras, NativeProtocol.EXTRA_ACTION_TYPE, actionType);
            extras.putBoolean(NativeProtocol.EXTRA_DATA_FAILURES_FATAL, dataErrorsFatal);

            JSONObject jsonAction = action.getInnerJSONObject();
            jsonAction = flattenChildrenOfGraphObject(jsonAction);

            String jsonString = jsonAction.toString();
            putExtra(extras, NativeProtocol.EXTRA_ACTION, jsonString);

            return extras;
        }

        private JSONObject flattenChildrenOfGraphObject(JSONObject graphObject) {
            try {
                // Clone the existing object to avoid modifying it from under the caller.
                graphObject = new JSONObject(graphObject.toString());

                @SuppressWarnings("unchecked")
                Iterator<String> keys = graphObject.keys();
                while (keys.hasNext()) {
                    String key = keys.next();
                    // The "image" property should not be flattened
                    if (!key.equalsIgnoreCase("image")) {
                        Object object = graphObject.get(key);

                        object = flattenObject(object);
                        graphObject.put(key, object);
                    }
                }

                return graphObject;
            } catch (JSONException e) {
                throw new FacebookException(e);
            }
        }

        private Object flattenObject(Object object) throws JSONException {
            if (object == null) {
                return null;
            }

            if (object instanceof JSONObject) {
                JSONObject jsonObject = (JSONObject) object;

                // Don't flatten objects that are marked as create_object.
                if (jsonObject.optBoolean(NativeProtocol.OPEN_GRAPH_CREATE_OBJECT_KEY)) {
                    return object;
                }
                if (jsonObject.has("id")) {
                    return jsonObject.getString("id");
                } else if (jsonObject.has("url")) {
                    return jsonObject.getString("url");
                }
            } else if (object instanceof JSONArray) {
                JSONArray jsonArray = (JSONArray) object;
                JSONArray newArray = new JSONArray();
                int length = jsonArray.length();

                for (int i = 0; i < length; ++i) {
                    newArray.put(flattenObject(jsonArray.get(i)));
                }

                return newArray;
            }

            return object;
        }
    }

    /**
     * Provides a builder which can construct a FacebookDialog instance suitable for presenting the native
     * Open Graph action publish dialog. This builder allows the caller to specify binary images for both the
     * action and any Open Graph objects to be created prior to publishing the action.
     * This builder will throw an exception if the Facebook application is not installed, so it
     * should only be used if {@link com.facebook.widget.FacebookDialog#canPresentOpenGraphActionDialog(android.content.Context,
     * com.facebook.widget.FacebookDialog.OpenGraphActionDialogFeature...)} indicates the capability is available.
     */
    public static class OpenGraphActionDialogBuilder extends OpenGraphDialogBuilderBase<OpenGraphActionDialogBuilder> {
        /**
         * Constructor.
         *
         * @param activity            the Activity which is presenting the native Open Graph action publish dialog;
         *                            must not be null
         * @param action              the Open Graph action to be published, which must contain a reference to at least one
         *                            Open Graph object with the property name specified by setPreviewPropertyName; the action
         *                            must have had its type specified via the {@link OpenGraphAction#setType(String)} method
         * @param actionType          the type of the Open Graph action to be published, which should be the namespace-qualified
         *                            name of the action type (e.g., "myappnamespace:myactiontype"); this will override the type
         *                            of the action passed in.
         * @param previewPropertyName the name of a property on the Open Graph action that contains the
         *                            Open Graph object which will be displayed as a preview to the user
         */
        @Deprecated
        public OpenGraphActionDialogBuilder(Activity activity, OpenGraphAction action, String actionType,
                String previewPropertyName) {
            super(activity, action, actionType, previewPropertyName);
        }

        /**
         * Constructor.
         *
         * @param activity            the Activity which is presenting the native Open Graph action publish dialog;
         *                            must not be null
         * @param action              the Open Graph action to be published, which must contain a reference to at least one
         *                            Open Graph object with the property name specified by setPreviewPropertyName; the action
         *                            must have had its type specified via the {@link OpenGraphAction#setType(String)} method
         * @param previewPropertyName the name of a property on the Open Graph action that contains the
         *                            Open Graph object which will be displayed as a preview to the user
         */
        public OpenGraphActionDialogBuilder(Activity activity, OpenGraphAction action, String previewPropertyName) {
            super(activity, action, previewPropertyName);
        }

        @Override
        EnumSet<? extends DialogFeature> getDialogFeatures() {
            return EnumSet.of(OpenGraphActionDialogFeature.OG_ACTION_DIALOG);
        }
    }

    /**
     * Provides a builder which can construct a FacebookDialog instance suitable for presenting the native
     * Open Graph action message dialog. This builder allows the caller to specify binary images for both the
     * action and any Open Graph objects to be created prior to publishing the action.
     * This builder will throw an exception if the Facebook application is not installed, so it
     * should only be used if {@link com.facebook.widget.FacebookDialog#canPresentOpenGraphMessageDialog(android.content.Context,
     * com.facebook.widget.FacebookDialog.OpenGraphMessageDialogFeature...)} indicates the capability is available.
     */
    public static class OpenGraphMessageDialogBuilder extends OpenGraphDialogBuilderBase<OpenGraphMessageDialogBuilder> {
        /**
         * Constructor.
         *
         * @param activity            the Activity which is presenting the native Open Graph action message dialog;
         *                            must not be null
         * @param action              the Open Graph action to be sent, which must contain a reference to at least one
         *                            Open Graph object with the property name specified by setPreviewPropertyName; the action
         *                            must have had its type specified via the {@link OpenGraphAction#setType(String)} method
         * @param previewPropertyName the name of a property on the Open Graph action that contains the
         *                            Open Graph object which will be displayed as a preview to the user
         */
        public OpenGraphMessageDialogBuilder(Activity activity, OpenGraphAction action, String previewPropertyName) {
            super(activity, action, previewPropertyName);
        }

        @Override
        EnumSet<? extends DialogFeature> getDialogFeatures() {
            return EnumSet.of(OpenGraphMessageDialogFeature.OG_MESSAGE_DIALOG);
        }
    }

    /**
     * Encapsulates information about a call being made to the Facebook application for Android. A unique String
     * call ID is used to track calls through their lifecycle.
     */
    public static class PendingCall implements Parcelable {
        private UUID callId;
        private Intent requestIntent;
        private int requestCode;

        /**
         * Constructor.
         *
         * @param requestCode the request code for this app call
         */
        public PendingCall(int requestCode) {
            callId = UUID.randomUUID();
            this.requestCode = requestCode;
        }

        private PendingCall(Parcel in) {
            callId = UUID.fromString(in.readString());
            requestIntent = in.readParcelable(null);
            requestCode = in.readInt();
        }

        private void setRequestIntent(Intent requestIntent) {
            this.requestIntent = requestIntent;
            this.requestIntent.putExtra(NativeProtocol.EXTRA_PROTOCOL_CALL_ID, callId.toString());
        }

        /**
         * Returns the Intent that was used to initiate this call to the Facebook application.
         *
         * @return the Intent
         */
        public Intent getRequestIntent() {
            return requestIntent;
        }

        /**
         * Returns the unique ID of this call to the Facebook application.
         *
         * @return the unique ID
         */
        public UUID getCallId() {
            return callId;
        }

        private void setRequestCode(int requestCode) {
            this.requestCode = requestCode;
        }

        /**
         * Gets the request code for this call.
         *
         * @return the request code that will be passed to handleActivityResult upon completion.
         */
        public int getRequestCode() {
            return requestCode;
        }

        @Override
        public int describeContents() {
            return 0;
        }

        @Override
        public void writeToParcel(Parcel parcel, int i) {
            parcel.writeString(callId.toString());
            parcel.writeParcelable(requestIntent, 0);
            parcel.writeInt(requestCode);
        }

        public static final Creator<PendingCall> CREATOR
                = new Creator<PendingCall>() {
            public PendingCall createFromParcel(Parcel in) {
                return new PendingCall(in);
            }

            public PendingCall[] newArray(int size) {
                return new PendingCall[size];
            }
        };
    }
}
