recommendation/src/android/support/app/recommendation/RecommendationExtender.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.support.app.recommendation;

import android.app.Notification;
import android.os.Bundle;

/**
 * <p>
 * Helper class to add content info extensions to notifications. To create a notification with
 * content info extensions:
 * <ol>
 * <li>Create an {@link Notification.Builder}, setting any desired properties.
 * <li>Create a {@link RecommendationExtender}.
 * <li>Set content info specific properties using the {@code add} and {@code set} methods of
 * {@link RecommendationExtender}.
 * <li>Call {@link android.app.Notification.Builder#extend(Notification.Extender) 
 * Notification.Builder.extend(Notification.Extender)} to apply the extensions to a notification.
 * </ol>
 *
 * <pre class="prettyprint">Notification notification = new Notification.Builder(context) * ... * .extend(new RecommendationExtender() * .set*(...)) * .build(); * </pre>
 * <p>
 * Content info extensions can be accessed on an existing notification by using the
 * {@code RecommendationExtender(Notification)} constructor, and then using the {@code get} methods
 * to access values.
 */
public final class RecommendationExtender implements Notification.Extender {
    private static final String TAG = "RecommendationExtender";

    // Key for the Content info extensions bundle in the main Notification extras bundle
    private static final String EXTRA_CONTENT_INFO_EXTENDER = "android.CONTENT_INFO_EXTENSIONS";

    // Keys within EXTRA_CONTENT_INFO_EXTENDER for individual content info options.

    private static final String KEY_CONTENT_TYPE = "android.contentType";

    private static final String KEY_CONTENT_GENRES = "android.contentGenre";

    private static final String KEY_CONTENT_PRICING_TYPE = "android.contentPricing.type";

    private static final String KEY_CONTENT_PRICING_VALUE = "android.contentPricing.value";

    private static final String KEY_CONTENT_STATUS = "android.contentStatus";

    private static final String KEY_CONTENT_MATURITY_RATING = "android.contentMaturity";

    private static final String KEY_CONTENT_RUN_LENGTH = "android.contentLength";

    private String[] mTypes;
    private String[] mGenres;
    private String mPricingType;
    private String mPricingValue;
    private int mContentStatus = -1;
    private String mMaturityRating;
    private long mRunLength = -1;

    /**
     * Create a {@link RecommendationExtender} with default options.
     */
    public RecommendationExtender() {
    }

    /**
     * Create a {@link RecommendationExtender} from the RecommendationExtender options of an
     * existing Notification.
     *
     * @param notif The notification from which to copy options.
     */
    public RecommendationExtender(Notification notif) {
        Bundle contentBundle = notif.extras == null ?
                null : notif.extras.getBundle(EXTRA_CONTENT_INFO_EXTENDER);
        if (contentBundle != null) {
            mTypes = contentBundle.getStringArray(KEY_CONTENT_TYPE);
            mGenres = contentBundle.getStringArray(KEY_CONTENT_GENRES);
            mPricingType = contentBundle.getString(KEY_CONTENT_PRICING_TYPE);
            mPricingValue = contentBundle.getString(KEY_CONTENT_PRICING_VALUE);
            mContentStatus = contentBundle.getInt(KEY_CONTENT_STATUS, -1);
            mMaturityRating = contentBundle.getString(KEY_CONTENT_MATURITY_RATING);
            mRunLength = contentBundle.getLong(KEY_CONTENT_RUN_LENGTH, -1);
        }
    }

    /**
     * Apply content extensions to a notification that is being built. This is typically called by
     * the {@link android.app.Notification.Builder#extend(Notification.Extender) 
     * Notification.Builder.extend(Notification.Extender)} method of {@link Notification.Builder}.
     */
    @Override
    public Notification.Builder extend(Notification.Builder builder) {
        Bundle contentBundle = new Bundle();

        if (mTypes != null) {
            contentBundle.putStringArray(KEY_CONTENT_TYPE, mTypes);
        }
        if (mGenres != null) {
            contentBundle.putStringArray(KEY_CONTENT_GENRES, mGenres);
        }
        if (mPricingType != null) {
            contentBundle.putString(KEY_CONTENT_PRICING_TYPE, mPricingType);
        }
        if (mPricingValue != null) {
            contentBundle.putString(KEY_CONTENT_PRICING_VALUE, mPricingValue);
        }
        if (mContentStatus != -1) {
            contentBundle.putInt(KEY_CONTENT_STATUS, mContentStatus);
        }
        if (mMaturityRating != null) {
            contentBundle.putString(KEY_CONTENT_MATURITY_RATING, mMaturityRating);
        }
        if (mRunLength > 0) {
            contentBundle.putLong(KEY_CONTENT_RUN_LENGTH, mRunLength);
        }

        builder.getExtras().putBundle(EXTRA_CONTENT_INFO_EXTENDER, contentBundle);
        return builder;
    }

    /**
     * Sets the content types associated with the notification content. The first tag entry will be
     * considered the primary type for the content and will be used for ranking purposes. Other
     * secondary type tags may be provided, if applicable, and may be used for filtering purposes.
     *
     * @param types Array of predefined type tags (see the <code>CONTENT_TYPE_*</code> constants)
     *            that describe the content referred to by a notification.
     */
    public RecommendationExtender setContentTypes(String[] types) {
        mTypes = types;
        return this;
    }

    /**
     * Returns an array containing the content types that describe the content associated with the
     * notification. The first tag entry is considered the primary type for the content, and is used
     * for content ranking purposes.
     *
     * @return An array of predefined type tags (see the <code>CONTENT_TYPE_*</code> constants) that
     *         describe the content associated with the notification.
     * @see RecommendationExtender#setContentTypes
     */
    public String[] getContentTypes() {
        return mTypes;
    }

    /**
     * Returns the primary content type tag for the content associated with the notification.
     *
     * @return A predefined type tag (see the <code>CONTENT_TYPE_*</code> constants) indicating the
     *         primary type for the content associated with the notification.
     * @see RecommendationExtender#setContentTypes
     */
    public String getPrimaryContentType() {
        if (mTypes == null || mTypes.length == 0) {
            return null;
        }
        return mTypes[0];
    }

    /**
     * Sets the content genres associated with the notification content. These genres may be used
     * for content ranking. Genres are open ended String tags.
     * <p>
     * Some examples: "comedy", "action", "dance", "electronica", "racing", etc.
     *
     * @param genres Array of genre string tags that describe the content referred to by a
     *            notification.
     */
    public RecommendationExtender setGenres(String[] genres) {
        mGenres = genres;
        return this;
    }

    /**
     * Returns an array containing the content genres that describe the content associated with the
     * notification.
     *
     * @return An array of genre tags that describe the content associated with the notification.
     * @see RecommendationExtender#setGenres
     */
    public String[] getGenres() {
        return mGenres;
    }

    /**
     * Sets the pricing and availability information for the content associated with the
     * notification. The provided information will indicate the access model for the content (free,
     * rental, purchase or subscription) and the price value (if not free).
     *
     * @param priceType Pricing type for this content. Must be one of the predefined pricing type
     *            tags (see the <code>CONTENT_PRICING_*</code> constants).
     * @param priceValue A string containing a representation of the content price in the current
     *            locale and currency.
     * @return This object for method chaining.
     */
    public RecommendationExtender setPricingInformation(
            @ContentRecommendation.ContentPricing String priceType, String priceValue) {
        mPricingType = priceType;
        mPricingValue = priceValue;
        return this;
    }

    /**
     * Gets the pricing type for the content associated with the notification.
     *
     * @return A predefined tag indicating the pricing type for the content (see the <code> CONTENT_PRICING_*</code>
     *         constants).
     * @see RecommendationExtender#setPricingInformation
     */
    public String getPricingType() {
        return mPricingType;
    }

    /**
     * Gets the price value (when applicable) for the content associated with a notification. The
     * value will be provided as a String containing the price in the appropriate currency for the
     * current locale.
     *
     * @return A string containing a representation of the content price in the current locale and
     *         currency.
     * @see RecommendationExtender#setPricingInformation
     */
    public String getPricingValue() {
        if (mPricingType == null) {
            return null;
        }
        return mPricingValue;
    }

    /**
     * Sets the availability status for the content associated with the notification. This status
     * indicates whether the referred content is ready to be consumed on the device, or if the user
     * must first purchase, rent, subscribe to, or download the content.
     *
     * @param contentStatus The status value for this content. Must be one of the predefined content
     *            status values (see the <code>CONTENT_STATUS_*</code> constants).
     */
    public RecommendationExtender setStatus(
            @ContentRecommendation.ContentStatus int contentStatus) {
        mContentStatus = contentStatus;
        return this;
    }

    /**
     * Returns status value for the content associated with the notification. This status indicates
     * whether the referred content is ready to be consumed on the device, or if the user must first
     * purchase, rent, subscribe to, or download the content.
     *
     * @return The status value for this content, or -1 is a valid status has not been specified
     *         (see the <code>CONTENT_STATUS_*</code> for the defined valid status values).
     * @see RecommendationExtender#setStatus
     */
    public int getStatus() {
        return mContentStatus;
    }

    /**
     * Sets the maturity level rating for the content associated with the notification.
     *
     * @param maturityRating A tag indicating the maturity level rating for the content. This tag
     *            must be one of the predefined maturity rating tags (see the <code> CONTENT_MATURITY_*</code>
     *            constants).
     */
    public RecommendationExtender setMaturityRating(
            @ContentRecommendation.ContentMaturity String maturityRating) {
        mMaturityRating = maturityRating;
        return this;
    }

    /**
     * Returns the maturity level rating for the content associated with the notification.
     *
     * @return returns a predefined tag indicating the maturity level rating for the content (see
     *         the <code>CONTENT_MATURITY_*</code> constants).
     * @see RecommendationExtender#setMaturityRating
     */
    public String getMaturityRating() {
        return mMaturityRating;
    }

    /**
     * Sets the running time (when applicable) for the content associated with the notification.
     *
     * @param length The runing time, in seconds, of the content associated with the notification.
     */
    public RecommendationExtender setRunningTime(long length) {
        if (length < 0) {
            throw new IllegalArgumentException("Invalid value for Running Time");
        }
        mRunLength = length;
        return this;
    }

    /**
     * Returns the running time for the content associated with the notification.
     *
     * @return The running time, in seconds, of the content associated with the notification.
     * @see RecommendationExtender#setRunningTime
     */
    public long getRunningTime() {
        return mRunLength;
    }
}