TIF: Rename R.attr.contentRatingSystemXml and fix documentation

- Rename contentRatingSystemXml to tvContentRatingDescription.
- Change docs to indicate this is a reference to an XML document that
  describes TV content rating, not a component name.
- Replace the DTD with an XML example.

Bug: 16960702
Change-Id: Iea985e9847ee5af0f745e896c498792234308b12

2 files changed, 85 insertions, 40 deletions

diff --git a/media/java/android/media/tv/TvContentRating.java b/media/java/android/media/tv/TvContentRating.java
index 015daee..405ef22 100644
--- a/media/java/android/media/tv/TvContentRating.java
+++ b/media/java/android/media/tv/TvContentRating.java
@@ -34,42 +34,87 @@ import java.util.Objects;
  * strings, or a TV input service defined strings.
  * TV input service defined strings are in an xml file defined in <code>&lt;{@link
  * android.R.styleable#TvInputService tv-input}&gt;</code> with the {@link
- * android.R.attr#contentRatingSystemXml contentRatingSystemXml} attribute by the TV input service.
+ * android.R.attr#tvContentRatingDescription tvContentRatingDescription} attribute by the TV input
+ * service.
  *
- * <h3> Content Rating System XML format </h3>
- * The XML file for publishing content rating system should follow the DTD bellow:
+ * <h3> Example: Rating system definition for the TV Parental Guidelines</h3>
+ * The following XML example shows how the TV Parental Guidelines in United States can be defined:
  * <p><pre class="prettyprint">
- * &lt;?xml version="1.0" encoding="UTF-8"?&gt;
- * &lt;!DOCTYPE rating-systems [
- *     &lt;!ELEMENT rating-system-definitions (rating-system-definition+)&gt;
- *     &lt;!ATTLIST rating-system-definitions
- *         version     CDATA #REQUIRED&gt;
- *     &lt;!ELEMENT rating-system-definition (
- *         (sub-rating-definition*, rating-definition, sub-rating-definition*)+, order*)&gt;
- *     &lt;!ATTLIST rating-system-definition
- *         id          ID    #REQUIRED
- *         displayName CDATA #IMPLIED
- *         description CDATA #IMPLIED
- *         country     CDATA #IMPLIED&gt;
- *     &lt;!ELEMENT sub-rating-definition EMPTY&gt;
- *     &lt;!ATTLIST sub-rating-definition
- *         id          ID    #REQUIRED
- *         displayName CDATA #IMPLIED
- *         icon        CDATA #IMPLIED
- *         description CDATA #IMPLIED&gt;
- *     &lt;!ELEMENT rating-definition (sub-rating*))&gt;
- *     &lt;!ATTLIST rating-definition
- *         id          ID    #REQUIRED
- *         displayName CDATA #IMPLIED
- *         icon        CDATA #IMPLIED
- *         description CDATA #IMPLIED&gt;
- *     &lt;!ELEMENT sub-rating EMPTY&gt;
- *     &lt;!ATTLIST sub-rating id IDREF #REQUIRED&gt;
- *     &lt;!ELEMENT order (rating, rating+)&gt;
- *     &lt;!ELEMENT rating EMPTY&gt;
- *     &lt;!ATTLIST rating id IDREF #REQUIRED&gt;
- * ]&gt;
- * </pre></p>
+ * {@literal
+ * <?xml version="1.0" encoding="UTF-8"?>
+ * <rating-system-definitions version="1.0">
+ *     <rating-system-definition id="US_TV"
+ *         displayName="US-TV"
+ *         description="The TV Parental Guidelines"
+ *         country="US">
+ *         <sub-rating-definition id="US_TV_D"
+ *             displayName="D"
+ *             description="Suggestive dialogue (Usually means talks about sex)" />
+ *         <sub-rating-definition id="US_TV_L"
+ *             displayName="L"
+ *             description="Coarse language" />
+ *         <sub-rating-definition id="US_TV_S"
+ *             displayName="S"
+ *             description="Sexual content" />
+ *         <sub-rating-definition id="US_TV_V"
+ *             displayName="V"
+ *             description="Violence" />
+ *         <sub-rating-definition id="US_TV_FV"
+ *             displayName="FV"
+ *             description="Fantasy violence (Children\'s programming only)" />
+ *
+ *         <rating-definition id="US_TV_Y"
+ *             displayName="TV-Y"
+ *             description="This program is designed to be appropriate for all children"
+ *             ageHint="0" />
+ *         <rating-definition id="US_TV_Y7"
+ *             displayName="TV-Y7"
+ *             description="This program is designed for children age 7 and above"
+ *             ageHint="7">
+ *             <sub-rating id="US_TV_FV" />
+ *         </rating-definition>
+ *         <rating-definition id="US_TV_G"
+ *             displayName="TV-G"
+ *             description="Most parents would find this program suitable for all ages"
+ *             ageHint="0" />
+ *         <rating-definition id="US_TV_PG"
+ *             displayName="TV-PG"
+ *             description="This program contains material that parents may find unsuitable for younger children"
+ *             ageHint="14">
+ *             <sub-rating id="US_TV_D" />
+ *             <sub-rating id="US_TV_L" />
+ *             <sub-rating id="US_TV_S" />
+ *             <sub-rating id="US_TV_V" />
+ *         </rating-definition>
+ *         <rating-definition id="US_TV_14"
+ *             displayName="TV-14"
+ *             description="This program contains some material that many parents would find unsuitable for children under 14 years of age"
+ *             ageHint="14">
+ *             <sub-rating id="US_TV_D" />
+ *             <sub-rating id="US_TV_L" />
+ *             <sub-rating id="US_TV_S" />
+ *             <sub-rating id="US_TV_V" />
+ *         </rating-definition>
+ *         <rating-definition id="US_TV_MA"
+ *             displayName="TV-MA"
+ *             description="This program is specifically designed to be viewed by adults and therefore may be unsuitable for children under 17"
+ *             ageHint="17">
+ *             <sub-rating id="US_TV_L" />
+ *             <sub-rating id="US_TV_S" />
+ *             <sub-rating id="US_TV_V" />
+ *         </rating-definition>
+ *         <order>
+ *             <rating id="US_TV_Y" />
+ *             <rating id="US_TV_Y7" />
+ *         </order>
+ *         <order>
+ *             <rating id="US_TV_G" />
+ *             <rating id="US_TV_PG" />
+ *             <rating id="US_TV_14" />
+ *             <rating id="US_TV_MA" />
+ *         </order>
+ *     </rating-system-definition>
+ * </rating-system-definitions>}</pre></p>
  *
  * <h3>System defined rating strings</h3>
  *
diff --git a/media/java/android/media/tv/TvInputInfo.java b/media/java/android/media/tv/TvInputInfo.java
index a1ca871..6ed7580 100644
--- a/media/java/android/media/tv/TvInputInfo.java
+++ b/media/java/android/media/tv/TvInputInfo.java
@@ -246,17 +246,17 @@ public final class TvInputInfo implements Parcelable {
                 Log.d(TAG, "Settings activity loaded. [" + input.mSettingsActivity + "] for "
                         + si.name);
             }
-            int contentRatingSystemXml = sa.getResourceId(
-                    com.android.internal.R.styleable.TvInputService_contentRatingSystemXml, -1);
-            if (contentRatingSystemXml != -1) {
+            int tvContentRatingDescription = sa.getResourceId(
+                    com.android.internal.R.styleable.TvInputService_tvContentRatingDescription, -1);
+            if (tvContentRatingDescription != -1) {
                 input.mRatingSystemXmlUri = new Uri.Builder()
                         .scheme(ContentResolver.SCHEME_ANDROID_RESOURCE)
                         .authority(si.packageName)
-                        .appendPath(Integer.toString(contentRatingSystemXml))
+                        .appendPath(Integer.toString(tvContentRatingDescription))
                         .build();
                 if (DEBUG) {
-                    Log.d(TAG, "Content rating xml loaded. [" + contentRatingSystemXml + "] for "
-                            + si.name);
+                    Log.d(TAG, "Content rating xml loaded. [" + tvContentRatingDescription
+                            + "] for " + si.name);
                 }
             }
             sa.recycle();