xref: /frameworks/base/media/java/android/media/tv/TvContentRating.java

/*
 * Copyright (C) 2014 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.media.tv;

import android.annotation.NonNull;
import android.annotation.SystemApi;
import android.text.TextUtils;

import com.android.internal.util.Preconditions;

import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.Objects;

/**
 * A class representing a TV content rating. When a TV input service inserts the content rating
 * information on a program into the database, this class can be used to generate the formatted
 * string for
 * {@link TvContract.Programs#COLUMN_CONTENT_RATING TvContract.Programs.COLUMN_CONTENT_RATING}.
 * To create a {@code TvContentRating} object, use the
 * {@link #createRating TvContentRating.createRating} method with valid rating system string
 * constants.
 *
 * <p>It is possible for an application to define its own content rating system by supplying a
 * content rating system definition XML resource (see example below) and declaring a broadcast
 * receiver that filters {@link TvInputManager#ACTION_QUERY_CONTENT_RATING_SYSTEMS} in its manifest.
 *
 * <h3> Example: Rating system definition for the TV Parental Guidelines</h3>
 * The following XML example shows how the TV Parental Guidelines in the United States can be
 * defined:
 * <p><pre class="prettyprint">
 * {@literal
 * <rating-system-definitions xmlns:android="http://schemas.android.com/apk/res/android"
 *     android:versionCode="1">
 *     <rating-system-definition android:name="US_TV"
 *         android:country="US"
 *         android:description="@string/description_us_tv">
 *         <sub-rating-definition android:name="US_TV_D"
 *             android:title="D"
 *             android:description="@string/description_us_tv_d" />
 *         <sub-rating-definition android:name="US_TV_L"
 *             android:title="L"
 *             android:description="@string/description_us_tv_l" />
 *         <sub-rating-definition android:name="US_TV_S"
 *             android:title="S"
 *             android:description="@string/description_us_tv_s" />
 *         <sub-rating-definition android:name="US_TV_V"
 *             android:title="V"
 *             android:description="@string/description_us_tv_v" />
 *         <sub-rating-definition android:name="US_TV_FV"
 *             android:title="FV"
 *             android:description="@string/description_us_tv_fv" />
 *
 *         <rating-definition android:name="US_TV_Y"
 *             android:title="TV-Y"
 *             android:description="@string/description_us_tv_y"
 *             android:icon="@drawable/icon_us_tv_y"
 *             android:contentAgeHint="0" />
 *         <rating-definition android:name="US_TV_Y7"
 *             android:title="TV-Y7"
 *             android:description="@string/description_us_tv_y7"
 *             android:icon="@drawable/icon_us_tv_y7"
 *             android:contentAgeHint="7">
 *             <sub-rating android:name="US_TV_FV" />
 *         </rating-definition>
 *         <rating-definition android:name="US_TV_G"
 *             android:title="TV-G"
 *             android:description="@string/description_us_tv_g"
 *             android:icon="@drawable/icon_us_tv_g"
 *             android:contentAgeHint="0" />
 *         <rating-definition android:name="US_TV_PG"
 *             android:title="TV-PG"
 *             android:description="@string/description_us_tv_pg"
 *             android:icon="@drawable/icon_us_tv_pg"
 *             android:contentAgeHint="14">
 *             <sub-rating android:name="US_TV_D" />
 *             <sub-rating android:name="US_TV_L" />
 *             <sub-rating android:name="US_TV_S" />
 *             <sub-rating android:name="US_TV_V" />
 *         </rating-definition>
 *         <rating-definition android:name="US_TV_14"
 *             android:title="TV-14"
 *             android:description="@string/description_us_tv_14"
 *             android:icon="@drawable/icon_us_tv_14"
 *             android:contentAgeHint="14">
 *             <sub-rating android:name="US_TV_D" />
 *             <sub-rating android:name="US_TV_L" />
 *             <sub-rating android:name="US_TV_S" />
 *             <sub-rating android:name="US_TV_V" />
 *         </rating-definition>
 *         <rating-definition android:name="US_TV_MA"
 *             android:title="TV-MA"
 *             android:description="@string/description_us_tv_ma"
 *             android:icon="@drawable/icon_us_tv_ma"
 *             android:contentAgeHint="17">
 *             <sub-rating android:name="US_TV_L" />
 *             <sub-rating android:name="US_TV_S" />
 *             <sub-rating android:name="US_TV_V" />
 *         </rating-definition>
 *         <rating-order>
 *             <rating android:name="US_TV_Y" />
 *             <rating android:name="US_TV_Y7" />
 *         </rating-order>
 *         <rating-order>
 *             <rating android:name="US_TV_G" />
 *             <rating android:name="US_TV_PG" />
 *             <rating android:name="US_TV_14" />
 *             <rating android:name="US_TV_MA" />
 *         </rating-order>
 *     </rating-system-definition>
 * </rating-system-definitions>}</pre>
 *
 * <h3>System defined rating strings</h3>
 * The following strings are defined by the system to provide a standard way to create
 * {@code TvContentRating} objects.
 *
 * <p>For example, to create an object that represents TV-PG rating with suggestive dialogue and
 * coarse language from the TV Parental Guidelines in the United States, one can use the following
 * code snippet:
 *
 * <pre>
 * TvContentRating rating = TvContentRating.createRating(
 *         "com.android.tv",
 *         "US_TV",
 *         "US_TV_PG",
 *         "US_TV_D", "US_TV_L");
 * </pre>
 * <h4>System defined string for domains</h4>
 * <table>
 *     <tr>
 *         <th>Constant Value</th>
 *         <th>Description</th>
 *     </tr>
 *     <tr>
 *         <td>com.android.tv</td>
 *         <td>Used for creating system defined content ratings</td>
 *     </tr>
 * </table>
 *
 * <h4>System defined strings for rating systems</h4>
 * <table>
 *     <tr>
 *         <th>Constant Value</th>
 *         <th>Description</th>
 *     </tr>
 *     <tr>
 *         <td>AR_TV</td>
 *         <td>TV content rating system for Argentina</td>
 *     </tr>
 *     <tr>
 *         <td>AU_TV</td>
 *         <td>TV content rating system for Australia</td>
 *     </tr>
 *     <tr>
 *         <td>BR_TV</td>
 *         <td>TV content rating system for Brazil</td>
 *     </tr>
 *     <tr>
 *         <td>CA_TV_EN</td>
 *         <td>TV content rating system for Canada (English)</td>
 *     </tr>
 *     <tr>
 *         <td>CA_TV_FR</td>
 *         <td>TV content rating system for Canada (French)</td>
 *     </tr>
 *     <tr>
 *         <td>DVB</td>
 *         <td>DVB content rating system</td>
 *     </tr>
 *     <tr>
 *         <td>ES_DVB</td>
 *         <td>DVB content rating system for Spain</td>
 *     </tr>
 *     <tr>
 *         <td>FR_DVB</td>
 *         <td>DVB content rating system for France</td>
 *     </tr>
 *     <tr>
 *         <td>ISDB</td>
 *         <td>ISDB content rating system</td>
 *     </tr>
 *     <tr>
 *         <td>KR_TV</td>
 *         <td>TV content rating system for South Korea</td>
 *     </tr>
 *     <tr>
 *         <td>SG_TV</td>
 *         <td>TV content rating system for Singapore</td>
 *     </tr>
 *     <tr>
 *         <td>US_MV</td>
 *         <td>Movie content rating system for the United States</td>
 *     </tr>
 *     <tr>
 *         <td>US_TV</td>
 *         <td>TV content rating system for the United States</td>
 *     </tr>
 * </table>
 *
 * <h4>System defined strings for ratings</h4>
 * <table>
 *     <tr>
 *         <th>Rating System</th>
 *         <th>Constant Value</th>
 *         <th>Description</th>
 *     </tr>
 *     <tr>
 *         <td valign="top" rowspan="4">AR_TV</td>
 *         <td>AR_TV_ATP</td>
 *         <td>Suitable for all audiences. Programs may contain mild violence, language and mature
 *         situations</td>
 *     </tr>
 *     <tr>
 *         <td>AR_TV_SAM_13</td>
 *         <td>Suitable for ages 13 and up. Programs may contain mild to moderate language and mild
 *         violence and sexual references</td>
 *     </tr>
 *     <tr>
 *         <td>AR_TV_SAM_16</td>
 *         <td>Suitable for ages 16 and up. Programs may contain more intensive violence and coarse
 *         language, partial nudity and moderate sexual references</td>
 *     </tr>
 *     <tr>
 *         <td>AR_TV_SAM_18</td>
 *         <td>Suitable for mature audiences only. Programs contain strong violence, coarse language
 *         and explicit sexual references</td>
 *     </tr>
 *     <tr>
 *         <td valign="top" rowspan="8">AU_TV</td>
 *         <td>AU_TV_P</td>
 *         <td>Recommended for younger children aged between 2 and 11 years</td>
 *     </tr>
 *     <tr>
 *         <td>AU_TV_C</td>
 *         <td>Recommended for older children aged between 5 and 14 years</td>
 *     </tr>
 *     <tr>
 *         <td>AU_TV_G</td>
 *         <td>Recommended for all ages</td>
 *     </tr>
 *     <tr>
 *         <td>AU_TV_PG</td>
 *         <td>Parental guidance is recommended for young viewers under 15</td>
 *     </tr>
 *     <tr>
 *         <td>AU_TV_M</td>
 *         <td>Recommended for mature audiences aged 15 years and over</td>
 *     </tr>
 *     <tr>
 *         <td>AU_TV_MA</td>
 *         <td>Not suitable for children and teens under 15, due to sexual descriptions, course
 *         language, adult themes or drug use</td>
 *     </tr>
 *     <tr>
 *         <td>AU_TV_AV</td>
 *         <td>Not suitable for children and teens under 15. This category is used specifically for
 *         violent programs</td>
 *     </tr>
 *     <tr>
 *         <td>AU_TV_R</td>
 *         <td>Not for children under 18. Content may include graphic violence, sexual situations,
 *         coarse language and explicit drug use</td>
 *     </tr>
 *     <tr>
 *         <td valign="top" rowspan="6">BR_TV</td>
 *         <td>BR_TV_L</td>
 *         <td>Content is suitable for all audiences</td>
 *     </tr>
 *     <tr>
 *         <td>BR_TV_10</td>
 *         <td>Content suitable for viewers over the age of 10</td>
 *     </tr>
 *     <tr>
 *         <td>BR_TV_12</td>
 *         <td>Content suitable for viewers over the age of 12</td>
 *     </tr>
 *     <tr>
 *         <td>BR_TV_14</td>
 *         <td>Content suitable for viewers over the age of 14</td>
 *     </tr>
 *     <tr>
 *         <td>BR_TV_16</td>
 *         <td>Content suitable for viewers over the age of 16</td>
 *     </tr>
 *     <tr>
 *         <td>BR_TV_18</td>
 *         <td>Content suitable for viewers over the age of 18</td>
 *     </tr>
 *     <tr>
 *         <td valign="top" rowspan="7">CA_TV_EN</td>
 *         <td>CA_TV_EN_EXEMPT</td>
 *         <td>Exempt from ratings</td>
 *     </tr>
 *     <tr>
 *         <td>CA_TV_EN_C</td>
 *         <td>Suitable for children ages 2&#8211;7</td>
 *     </tr>
 *     <tr>
 *         <td>CA_TV_EN_C8</td>
 *         <td>Suitable for children ages 8 and older</td>
 *     </tr>
 *     <tr>
 *         <td>CA_TV_EN_G</td>
 *         <td>Suitable for the entire family</td>
 *     </tr>
 *     <tr>
 *         <td>CA_TV_EN_PG</td>
 *         <td>May contain moderate violence, profanity, nudity, and sexual references</td>
 *     </tr>
 *     <tr>
 *         <td>CA_TV_EN_14</td>
 *         <td>Intended for viewers ages 14 and older</td>
 *     </tr>
 *     <tr>
 *         <td>CA_TV_EN_18</td>
 *         <td>Intended for viewers ages 18 and older</td>
 *     </tr>
 *     <tr>
 *         <td valign="top" rowspan="6">CA_TV_FR</td>
 *         <td>CA_TV_FR_E</td>
 *         <td>Exempt from ratings</td>
 *     </tr>
 *     <tr>
 *         <td>CA_TV_FR_G</td>
 *         <td>Appropriate for all ages</td>
 *     </tr>
 *     <tr>
 *         <td>CA_TV_FR_8</td>
 *         <td>Appropriate for children 8</td>
 *     </tr>
 *     <tr>
 *         <td>CA_TV_FR_13</td>
 *         <td>Suitable for children 13</td>
 *     </tr>
 *     <tr>
 *         <td>CA_TV_FR_16</td>
 *         <td>Recommended for children over the age of 16</td>
 *     </tr>
 *     <tr>
 *         <td>CA_TV_FR_18</td>
 *         <td>Only to be viewed by adults</td>
 *     </tr>
 *     <tr>
 *         <td valign="top" rowspan="15">DVB</td>
 *         <td>DVB_4</td>
 *         <td>Recommended for ages 4 and over</td>
 *     </tr>
 *     <tr>
 *         <td>DVB_5</td>
 *         <td>Recommended for ages 5 and over</td>
 *     </tr>
 *     <tr>
 *         <td>DVB_6</td>
 *         <td>Recommended for ages 6 and over</td>
 *     </tr>
 *     <tr>
 *         <td>DVB_7</td>
 *         <td>Recommended for ages 7 and over</td>
 *     </tr>
 *     <tr>
 *         <td>DVB_8</td>
 *         <td>Recommended for ages 8 and over</td>
 *     </tr>
 *     <tr>
 *         <td>DVB_9</td>
 *         <td>Recommended for ages 9 and over</td>
 *     </tr>
 *     <tr>
 *         <td>DVB_10</td>
 *         <td>Recommended for ages 10 and over</td>
 *     </tr>
 *     <tr>
 *         <td>DVB_11</td>
 *         <td>Recommended for ages 11 and over</td>
 *     </tr>
 *     <tr>
 *         <td>DVB_12</td>
 *         <td>Recommended for ages 12 and over</td>
 *     </tr>
 *     <tr>
 *         <td>DVB_13</td>
 *         <td>Recommended for ages 13 and over</td>
 *     </tr>
 *     <tr>
 *         <td>DVB_14</td>
 *         <td>Recommended for ages 14 and over</td>
 *     </tr>
 *     <tr>
 *         <td>DVB_15</td>
 *         <td>Recommended for ages 15 and over</td>
 *     </tr>
 *     <tr>
 *         <td>DVB_16</td>
 *         <td>Recommended for ages 16 and over</td>
 *     </tr>
 *     <tr>
 *         <td>DVB_17</td>
 *         <td>Recommended for ages 17 and over</td>
 *     </tr>
 *     <tr>
 *         <td>DVB_18</td>
 *         <td>Recommended for ages 18 and over</td>
 *     </tr>
 *     <tr>
 *         <td valign="top" rowspan="18">ES_DVB</td>
 *         <td>ES_DVB_ALL</td>
 *         <td>Recommended for all ages</td>
 *     </tr>
 *     <tr>
 *         <td>ES_DVB_C</td>
 *         <td>Recommended for children</td>
 *     </tr>
 *     <tr>
 *         <td>ES_DVB_X</td>
 *         <td>Recommended for adults</td>
 *     </tr>
 *     <tr>
 *         <td>ES_DVB_4</td>
 *         <td>Recommended for ages 4 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ES_DVB_5</td>
 *         <td>Recommended for ages 5 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ES_DVB_6</td>
 *         <td>Recommended for ages 6 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ES_DVB_7</td>
 *         <td>Recommended for ages 7 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ES_DVB_8</td>
 *         <td>Recommended for ages 8 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ES_DVB_9</td>
 *         <td>Recommended for ages 9 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ES_DVB_10</td>
 *         <td>Recommended for ages 10 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ES_DVB_11</td>
 *         <td>Recommended for ages 11 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ES_DVB_12</td>
 *         <td>Recommended for ages 12 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ES_DVB_13</td>
 *         <td>Recommended for ages 13 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ES_DVB_14</td>
 *         <td>Recommended for ages 14 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ES_DVB_15</td>
 *         <td>Recommended for ages 15 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ES_DVB_16</td>
 *         <td>Recommended for ages 16 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ES_DVB_17</td>
 *         <td>Recommended for ages 17 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ES_DVB_18</td>
 *         <td>Recommended for ages 18 and over</td>
 *     </tr>
 *     <tr>
 *         <td valign="top" rowspan="16">FR_DVB</td>
 *         <td>FR_DVB_U</td>
 *         <td>Recommended for all ages</td>
 *     </tr>
 *     <tr>
 *         <td>FR_DVB_4</td>
 *         <td>Recommended for ages 4 and over</td>
 *     </tr>
 *     <tr>
 *         <td>FR_DVB_5</td>
 *         <td>Recommended for ages 5 and over</td>
 *     </tr>
 *     <tr>
 *         <td>FR_DVB_6</td>
 *         <td>Recommended for ages 6 and over</td>
 *     </tr>
 *     <tr>
 *         <td>FR_DVB_7</td>
 *         <td>Recommended for ages 7 and over</td>
 *     </tr>
 *     <tr>
 *         <td>FR_DVB_8</td>
 *         <td>Recommended for ages 8 and over</td>
 *     </tr>
 *     <tr>
 *         <td>FR_DVB_9</td>
 *         <td>Recommended for ages 9 and over</td>
 *     </tr>
 *     <tr>
 *         <td>FR_DVB_10</td>
 *         <td>Recommended for ages 10 and over</td>
 *     </tr>
 *     <tr>
 *         <td>FR_DVB_11</td>
 *         <td>Recommended for ages 11 and over</td>
 *     </tr>
 *     <tr>
 *         <td>FR_DVB_12</td>
 *         <td>Recommended for ages 12 and over</td>
 *     </tr>
 *     <tr>
 *         <td>FR_DVB_13</td>
 *         <td>Recommended for ages 13 and over</td>
 *     </tr>
 *     <tr>
 *         <td>FR_DVB_14</td>
 *         <td>Recommended for ages 14 and over</td>
 *     </tr>
 *     <tr>
 *         <td>FR_DVB_15</td>
 *         <td>Recommended for ages 15 and over</td>
 *     </tr>
 *     <tr>
 *         <td>FR_DVB_16</td>
 *         <td>Recommended for ages 16 and over</td>
 *     </tr>
 *     <tr>
 *         <td>FR_DVB_17</td>
 *         <td>Recommended for ages 17 and over</td>
 *     </tr>
 *     <tr>
 *         <td>FR_DVB_18</td>
 *         <td>Recommended for ages 18 and over</td>
 *     </tr>
 *     <tr>
 *         <td valign="top" rowspan="17">ISDB</td>
 *         <td>ISDB_4</td>
 *         <td>Recommended for ages 4 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ISDB_5</td>
 *         <td>Recommended for ages 5 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ISDB_6</td>
 *         <td>Recommended for ages 6 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ISDB_7</td>
 *         <td>Recommended for ages 7 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ISDB_8</td>
 *         <td>Recommended for ages 8 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ISDB_9</td>
 *         <td>Recommended for ages 9 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ISDB_10</td>
 *         <td>Recommended for ages 10 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ISDB_11</td>
 *         <td>Recommended for ages 11 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ISDB_12</td>
 *         <td>Recommended for ages 12 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ISDB_13</td>
 *         <td>Recommended for ages 13 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ISDB_14</td>
 *         <td>Recommended for ages 14 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ISDB_15</td>
 *         <td>Recommended for ages 15 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ISDB_16</td>
 *         <td>Recommended for ages 16 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ISDB_17</td>
 *         <td>Recommended for ages 17 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ISDB_18</td>
 *         <td>Recommended for ages 18 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ISDB_19</td>
 *         <td>Recommended for ages 19 and over</td>
 *     </tr>
 *     <tr>
 *         <td>ISDB_20</td>
 *         <td>Recommended for ages 20 and over</td>
 *     </tr>
 *     <tr>
 *         <td valign="top" rowspan="5">KR_TV</td>
 *         <td>KR_TV_ALL</td>
 *         <td>Appropriate for all ages</td>
 *     </tr>
 *     <tr>
 *         <td>KR_TV_7</td>
 *         <td>May contain material inappropriate for children younger than 7, and parental
 *         discretion should be used</td>
 *     </tr>
 *     <tr>
 *         <td>KR_TV_12</td>
 *         <td>May deemed inappropriate for those younger than 12, and parental discretion should be
 *         used</td>
 *     </tr>
 *     <tr>
 *         <td>KR_TV_15</td>
 *         <td>May be inappropriate for children under 15, and that parental discretion should be
 *         used</td>
 *     </tr>
 *     <tr>
 *         <td>KR_TV_19</td>
 *         <td>For adults only</td>
 *     </tr>
 *     <tr>
 *         <td valign="top" rowspan="6">SG_TV</td>
 *         <td>SG_TV_G</td>
 *         <td>Suitable for all ages</td>
 *     </tr>
 *     <tr>
 *         <td>SG_TV_PG</td>
 *         <td>Suitable for all but parents should guide their young</td>
 *     </tr>
 *     <tr>
 *         <td>SG_TV_PG13</td>
 *         <td>Suitable for persons aged 13 and above but parental guidance is advised for children
 *         below 13</td>
 *     </tr>
 *     <tr>
 *         <td>SG_TV_NC16</td>
 *         <td>Suitable for persons aged 16 and above</td>
 *     </tr>
 *     <tr>
 *         <td>SG_TV_M18</td>
 *         <td>Suitable for persons aged 18 and above</td>
 *     </tr>
 *     <tr>
 *         <td>SG_TV_R21</td>
 *         <td>Suitable for adults aged 21 and above</td>
 *     </tr>
 *     <tr>
 *         <td valign="top" rowspan="5">US_MV</td>
 *         <td>US_MV_G</td>
 *         <td>General audiences</td>
 *     </tr>
 *     <tr>
 *         <td>US_MV_PG</td>
 *         <td>Parental guidance suggested</td>
 *     </tr>
 *     <tr>
 *         <td>US_MV_PG13</td>
 *         <td>Parents strongly cautioned</td>
 *     </tr>
 *     <tr>
 *         <td>US_MV_R</td>
 *         <td>Restricted, under 17 requires accompanying parent or adult guardian</td>
 *     </tr>
 *     <tr>
 *         <td>US_MV_NC17</td>
 *         <td>No one 17 and under admitted</td>
 *     </tr>
 *     <tr>
 *         <td valign="top" rowspan="6">US_TV</td>
 *         <td>US_TV_Y</td>
 *         <td>This program is designed to be appropriate for all children</td>
 *     </tr>
 *     <tr>
 *         <td>US_TV_Y7</td>
 *         <td>This program is designed for children age 7 and above</td>
 *     </tr>
 *     <tr>
 *         <td>US_TV_G</td>
 *         <td>Most parents would find this program suitable for all ages</td>
 *     </tr>
 *     <tr>
 *         <td>US_TV_PG</td>
 *         <td>This program contains material that parents may find unsuitable for younger children
 *         </td>
 *     </tr>
 *     <tr>
 *         <td>US_TV_14</td>
 *         <td>This program contains some material that many parents would find unsuitable for
 *         children under 14 years of age</td>
 *     </tr>
 *     <tr>
 *         <td>US_TV_MA</td>
 *         <td>This program is specifically designed to be viewed by adults and therefore may be
 *         unsuitable for children under 17</td>
 *     </tr>
 * </table>
 *
 * <h4>System defined strings for sub-ratings</h4>
 * <table>
 *     <tr>
 *         <th>Rating System</th>
 *         <th>Constant Value</th>
 *         <th>Description</th>
 *     </tr>
 *     <tr>
 *         <td valign="top" rowspan="3">BR_TV</td>
 *         <td>BR_TV_D</td>
 *         <td>Drugs<br/>Applicable to BR_TV_L, BR_TV_10, BR_TV_12, BR_TV_14, BR_TV_16, and BR_TV_18
 *         </td>
 *     </tr>
 *     <tr>
 *         <td>BR_TV_S</td>
 *         <td>Sex<br/>Applicable to BR_TV_L, BR_TV_10, BR_TV_12, BR_TV_14, BR_TV_16, and BR_TV_18
 *         </td>
 *     </tr>
 *     <tr>
 *         <td>BR_TV_V</td>
 *         <td>Violence<br/>Applicable to BR_TV_L, BR_TV_10, BR_TV_12, BR_TV_14, BR_TV_16, and
 *         BR_TV_18</td>
 *     </tr>
 *     <tr>
 *         <td valign="top" rowspan="5">US_TV</td>
 *         <td>US_TV_D</td>
 *         <td>Suggestive dialogue (Usually means talks about sex)<br/>Applicable to US_TV_PG, and
 *         US_TV_14</td>
 *     </tr>
 *     <tr>
 *         <td>US_TV_L</td>
 *         <td>Coarse language<br/>Applicable to US_TV_PG, US_TV_14, and US_TV_MA</td>
 *     </tr>
 *     <tr>
 *         <td>US_TV_S</td>
 *         <td>Sexual content<br/>Applicable to US_TV_PG, US_TV_14, and US_TV_MA</td>
 *     </tr>
 *     <tr>
 *         <td>US_TV_V</td>
 *         <td>Violence<br/>Applicable to US_TV_PG, US_TV_14, and US_TV_MA</td>
 *     </tr>
 *     <tr>
 *         <td>US_TV_FV</td>
 *         <td>Fantasy violence (Children's programming only)<br/>Applicable to US_TV_Y7</td>
 *     </tr>
 * </table>
 */
public final class TvContentRating {
    // TODO: Consider to use other DELIMITER. In some countries such as India may use this delimiter
    // in the main ratings.
    private static final String DELIMITER = "/";

    private final String mDomain;
    private final String mRatingSystem;
    private final String mRating;
    private final String[] mSubRatings;
    private final int mHashCode;

    /**
     * Rating constant denoting unrated content. Used to handle the case where the content rating
     * information is missing.
     *
     * <p>TV input services can call {@link TvInputManager#isRatingBlocked} with this constant to
     * determine whether they should block unrated content. The subsequent call to
     * {@link TvInputService.Session#notifyContentBlocked} with the same constant notifies
     * applications that the current program content is blocked by parental controls.
     */
    public static final TvContentRating UNRATED = new TvContentRating("null", "null", "null", null);

    /**
     * Creates a {@code TvContentRating} object with predefined content rating strings.
     *
     * @param domain The domain string. For example, "com.android.tv".
     * @param ratingSystem The rating system string. For example, "US_TV".
     * @param rating The content rating string. For example, "US_TV_PG".
     * @param subRatings The sub-rating strings. For example, "US_TV_D" and "US_TV_L".
     * @return A {@code TvContentRating} object.
     * @throws IllegalArgumentException If {@code domain}, {@code ratingSystem} or {@code rating} is
     *             {@code null}.
     */
    public static TvContentRating createRating(String domain, String ratingSystem,
            String rating, String... subRatings) {
        if (TextUtils.isEmpty(domain)) {
            throw new IllegalArgumentException("domain cannot be empty");
        }
        if (TextUtils.isEmpty(ratingSystem)) {
            throw new IllegalArgumentException("ratingSystem cannot be empty");
        }
        if (TextUtils.isEmpty(rating)) {
            throw new IllegalArgumentException("rating cannot be empty");
        }
        return new TvContentRating(domain, ratingSystem, rating, subRatings);
    }

    /**
     * Recovers a {@code TvContentRating} object from the string that was previously created from
     * {@link #flattenToString}.
     *
     * @param ratingString The string returned by {@link #flattenToString}.
     * @return the {@code TvContentRating} object containing the domain, rating system, rating and
     *         sub-ratings information encoded in {@code ratingString}.
     * @see #flattenToString
     */
    public static TvContentRating unflattenFromString(String ratingString) {
        if (TextUtils.isEmpty(ratingString)) {
            throw new IllegalArgumentException("ratingString cannot be empty");
        }
        String[] strs = ratingString.split(DELIMITER);
        if (strs.length < 3) {
            throw new IllegalArgumentException("Invalid rating string: " + ratingString);
        }
        if (strs.length > 3) {
            String[] subRatings = new String[strs.length - 3];
            System.arraycopy(strs, 3, subRatings, 0, subRatings.length);
            return new TvContentRating(strs[0], strs[1], strs[2], subRatings);
        }
        return new TvContentRating(strs[0], strs[1], strs[2], null);
    }

    /**
     * Constructs a TvContentRating object from a given rating and sub-rating constants.
     *
     * @param domain The string for domain of the content rating system such as "com.android.tv".
     * @param ratingSystem The rating system string such as "US_TV".
     * @param rating The content rating string such as "US_TV_PG".
     * @param subRatings The sub-rating strings such as "US_TV_D" and "US_TV_L".
     */
    private TvContentRating(
            String domain, String ratingSystem, String rating, String[] subRatings) {
        mDomain = domain;
        mRatingSystem = ratingSystem;
        mRating = rating;
        if (subRatings == null || subRatings.length == 0) {
            mSubRatings = null;
        } else {
            Arrays.sort(subRatings);
            mSubRatings = subRatings;
        }
        mHashCode = 31 * Objects.hash(mDomain, mRating) + Arrays.hashCode(mSubRatings);
    }

    /**
     * Returns the domain of this {@code TvContentRating} object.
     */
    public String getDomain() {
        return mDomain;
    }

    /**
     * Returns the rating system of this {@code TvContentRating} object.
     */
    public String getRatingSystem() {
        return mRatingSystem;
    }

    /**
     * Returns the main rating of this {@code TvContentRating} object.
     */
    public String getMainRating() {
        return mRating;
    }

    /**
     * Returns the unmodifiable sub-rating string {@link List} of this {@code TvContentRating}
     * object.
     */
    public List<String> getSubRatings() {
        if (mSubRatings == null) {
            return null;
        }
        return Collections.unmodifiableList(Arrays.asList(mSubRatings));
    }

    /**
     * Returns a string that unambiguously describes the rating information contained in a
     * {@code TvContentRating} object. One can later recover the object from this string through
     * {@link #unflattenFromString}.
     *
     * @return a string containing the rating information, which can later be stored in the
     *         database.
     * @see #unflattenFromString
     */
    public String flattenToString() {
        StringBuilder builder = new StringBuilder();
        builder.append(mDomain);
        builder.append(DELIMITER);
        builder.append(mRatingSystem);
        builder.append(DELIMITER);
        builder.append(mRating);
        if (mSubRatings != null) {
            for (String subRating : mSubRatings) {
                builder.append(DELIMITER);
                builder.append(subRating);
            }
        }
        return builder.toString();
    }

    /**
     * Returns {@code true} if this rating has the same main rating as the specified rating and when
     * this rating's sub-ratings contain the other's.
     *
     * <p>For example, a {@code TvContentRating} object that represents TV-PG with
     * S(Sexual content) and V(Violence) contains TV-PG, TV-PG/S, TV-PG/V and itself.
     *
     * @param rating The {@link TvContentRating} to check.
     * @return {@code true} if this object contains {@code rating}, {@code false} otherwise.
     * @hide
     */
    @SystemApi
    public final boolean contains(@NonNull TvContentRating rating) {
        Preconditions.checkNotNull(rating);
        if (!rating.getMainRating().equals(mRating)) {
            return false;
        }
        if (!rating.getDomain().equals(mDomain) ||
                !rating.getRatingSystem().equals(mRatingSystem) ||
                !rating.getMainRating().equals(mRating)) {
            return false;
        }
        List<String> subRatings = getSubRatings();
        List<String> subRatingsOther = rating.getSubRatings();
        if (subRatings == null && subRatingsOther == null) {
            return true;
        } else if (subRatings == null && subRatingsOther != null) {
            return false;
        } else if (subRatings != null && subRatingsOther == null) {
            return true;
        } else {
            return subRatings.containsAll(subRatingsOther);
        }
    }

    @Override
    public boolean equals(Object obj) {
        if (!(obj instanceof TvContentRating)) {
            return false;
        }
        TvContentRating other = (TvContentRating) obj;
        if (mHashCode != other.mHashCode) {
            return false;
        }
        if (!TextUtils.equals(mDomain, other.mDomain)) {
            return false;
        }
        if (!TextUtils.equals(mRatingSystem, other.mRatingSystem)) {
            return false;
        }
        if (!TextUtils.equals(mRating, other.mRating)) {
            return false;
        }
        return Arrays.equals(mSubRatings, other.mSubRatings);
    }

    @Override
    public int hashCode() {
        return mHashCode;
    }
}