path: root/core/java/android/app/AssistAction.java

/*
 * Copyright (C) 2015 The Android Open Source Project
 *
 * 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 android.app;

import android.annotation.NonNull;
import android.annotation.Nullable;
import android.net.Uri;
import android.os.Bundle;
import android.text.TextUtils;

import com.android.internal.util.Preconditions;

/**
 * Helper class for building a {@link Bundle} representing an action being performed by the user,
 * to be included in the Bundle generated by {@link Activity#onProvideAssistData}.
 *
 * @see Activity#onProvideAssistData
 */
public final class AssistAction {

    /**
     * Key name for the Bundle containing the schema.org representation of
     * an action performed, and should be stored in the Bundle generated by
     * {@link Activity#onProvideAssistData}.
     */
    public static final String ASSIST_ACTION_KEY = "android:assist_action";

    /** Bundle key to specify the schema.org ID of the content. */
    public static final String KEY_ID = "@id";

    /** Bundle key to specify the schema.org type of the content. */
    public static final String KEY_TYPE = "@type";

    /** Bundle key to specify the name of the content. */
    public static final String KEY_NAME = "name";

    /** Bundle key to specify the description of the content. */
    public static final String KEY_DESCRIPTION = "description";

    /** Bundle key to specify the URL of the content. */
    public static final String KEY_URL = "url";

    /** Bundle key to specify the object of an action. */
    public static final String KEY_ACTION_OBJECT = "object";

    /** Bundle key to specify the action's status. */
    public static final String KEY_ACTION_STATUS = "actionStatus";

    /** The act of editing by adding an object to a collection. */
    public static final String TYPE_ADD_ACTION = "AddAction";

    /** The act of bookmarking an object. */
    public static final String TYPE_BOOKMARK_ACTION = "BookmarkAction";

    /** The act of liking an object. */
    public static final String TYPE_LIKE_ACTION = "LikeAction";

    /** The act of consuming audio content. */
    public static final String TYPE_LISTEN_ACTION = "ListenAction";

    /** The act of consuming static visual content. */
    public static final String TYPE_VIEW_ACTION = "ViewAction";

    /** The act of expressing a desire about the object. */
    public static final String TYPE_WANT_ACTION = "WantAction";

    /** The act of watching an object. */
    public static final String TYPE_WATCH_ACTION = "WatchAction";

    /** The status of an active action. */
    public static final String STATUS_TYPE_ACTIVE = "ActiveActionStatus";

    /** The status of a completed action. */
    public static final String STATUS_TYPE_COMPLETED = "CompletedActionStatus";

    private AssistAction() {
    }

    /**
     * Update the Bundle passed into {@link Activity#onProvideAssistData} with the action Bundle,
     * built with {@link ActionBuilder}.
     *
     * @param assistDataBundle The Bundle provided to {@link Activity#onProvideAssistData}.
     * @param actionBundle The Bundle representing an schema.org action.
     */
    public static void updateAssistData(Bundle assistDataBundle, Bundle actionBundle) {
        Preconditions.checkNotNull(assistDataBundle);
        Preconditions.checkNotNull(actionBundle);

        Preconditions.checkNotNull(actionBundle.getString(KEY_TYPE),
                "The '@type' property is required in the provided actionBundle");
        assistDataBundle.putParcelable(ASSIST_ACTION_KEY, actionBundle);
    }

    /**
     * Builds a {@link Bundle} representing a schema.org entity.
     */
    public static final class ThingBuilder {
        private final Bundle mBundle;

        public ThingBuilder() {
            mBundle = new Bundle();
        }

        /**
         * Sets the name of the content.
         *
         * @param name The name of the content.
         */
        public ThingBuilder setName(@Nullable String name) {
            set(KEY_NAME, name);
            return this;
        }

        /**
         * Sets the app URI of the content.
         *
         * @param uri The app URI of the content.
         */
        public ThingBuilder setUrl(@Nullable Uri uri) {
            if (uri != null) {
                set(KEY_URL, uri.toString());
            }
            return this;
        }

        /**
         * Sets the ID of the content.
         *
         * @param id Set the ID of the content.
         */
        public ThingBuilder setId(@Nullable String id) {
            set(KEY_ID, id);
            return this;
        }

        /**
        * Sets the schema.org type of the content.
        *
        * @param type The schema.org type.
        */
        public ThingBuilder setType(@Nullable String type) {
            set(KEY_TYPE, type);
            return this;
        }

        /**
         * Sets the optional description of the content.
         *
         * @param description The description of the content.
         */
        public ThingBuilder setDescription(@Nullable String description) {
            set(KEY_DESCRIPTION, description);
            return this;
        }

        /**
         * Sets a property of the content.
         *
         * @param key The schema.org property. Must not be null.
         * @param value The value of the schema.org property.
         *              If null, the value will be ignored.
         */
        public ThingBuilder set(@NonNull String key, @Nullable String value) {
            if (value != null) {
                mBundle.putString(key, value);
            }
            return this;
        }

        /**
         * Sets a property of the content.
         *
         * @param key The schema.org property. Must not be null.
         * @param value The value of the schema.org property represented as a bundle.
         *              If null, the value will be ignored.
         */
        public ThingBuilder set(@NonNull String key, @Nullable Bundle value) {
            if (value != null) {
                mBundle.putParcelable(key, value);
            }
            return this;
        }

        /**
         * Build the {@link Bundle} object representing the schema.org entity.
         */
        public Bundle build() {
            return mBundle;
        }
    }

    /**
     * Builds a {@link Bundle} representing a schema.org action.
     */
    public static final class ActionBuilder {
        private final Bundle mBundle;

        public ActionBuilder() {
            mBundle = new Bundle();
        }

        /**
         * Sets the schema.org type of the action.
         *
         * @param type The schema.org type.
         */
        public ActionBuilder setType(@Nullable String type) {
            set(KEY_TYPE, type);
            return this;
        }

        /**
         * Sets the schema.org object of the action.
         *
         * @param object The schema.org object of the action.
         */
        public ActionBuilder setObject(@Nullable Bundle object) {
            set(KEY_ACTION_OBJECT, object);
            return this;
        }

        /**
         * Sets a property of the action.
         *
         * @param key The schema.org property. Must not be null.
         * @param value The value of the schema.org property.
         *              If null, the value will be ignored.
         */
        public ActionBuilder set(@NonNull String key, @Nullable String value) {
            if (value != null) {
                mBundle.putString(key, value);
            }
            return this;
        }

        /**
         * Sets a property of the action.
         *
         * @param key The schema.org property. Must not be null.
         * @param value The value of the schema.org property represented as a bundle.
         *              If null, the value will be ignored.
         */
        public ActionBuilder set(@NonNull String key, @Nullable Bundle value) {
            if (value != null) {
                mBundle.putParcelable(key, value);
            }
            return this;
        }

        /**
         * Build the {@link Bundle} object representing the schema.org action.
         */
        public Bundle build() {
            if (TextUtils.isEmpty(mBundle.getString(KEY_TYPE, null))) {
                // Defaults to the base action type http://schema.org/Action.
                setType("Action");
            }

            return mBundle;
        }
    }
}