Merge branch 'readonly-p4-donut' into donut

3 files changed, 104 insertions, 7 deletions

diff --git a/core/java/android/content/Intent.java b/core/java/android/content/Intent.java
index 605e223c52fd..e82a86cd4a3e 100644
--- a/core/java/android/content/Intent.java
+++ b/core/java/android/content/Intent.java
@@ -2079,6 +2079,12 @@ public class Intent implements Parcelable {
      * android.intent.action.VIEW; an application's custom action would be
      * something like com.google.app.myapp.CUSTOM_ACTION.
      *
+     * <p><em>Note: scheme and host name matching in the Android framework is
+     * case-sensitive, unlike the formal RFC.  As a result,
+     * you should always ensure that you write your Uri with these elements
+     * using lower case letters, and normalize any Uris you receive from
+     * outside of Android to ensure the scheme and host is lower case.</em></p>
+     *
      * @param action The Intent action, such as ACTION_VIEW.
      * @param uri The Intent data URI.
      */
@@ -2113,6 +2119,12 @@ public class Intent implements Parcelable {
      * construct the Intent and then calling {@link #setClass} to set its
      * class.
      *
+     * <p><em>Note: scheme and host name matching in the Android framework is
+     * case-sensitive, unlike the formal RFC.  As a result,
+     * you should always ensure that you write your Uri with these elements
+     * using lower case letters, and normalize any Uris you receive from
+     * outside of Android to ensure the scheme and host is lower case.</em></p>
+     *
      * @param action The Intent action, such as ACTION_VIEW.
      * @param uri The Intent data URI.
      * @param packageContext A Context of the application package implementing
@@ -3162,6 +3174,12 @@ public class Intent implements Parcelable {
      * Set the data this intent is operating on.  This method automatically
      * clears any type that was previously set by {@link #setType}.
      *
+     * <p><em>Note: scheme and host name matching in the Android framework is
+     * case-sensitive, unlike the formal RFC.  As a result,
+     * you should always ensure that you write your Uri with these elements
+     * using lower case letters, and normalize any Uris you receive from
+     * outside of Android to ensure the scheme and host is lower case.</em></p>
+     *
      * @param data The URI of the data this intent is now targeting.
      *
      * @return Returns the same Intent object, for chaining multiple calls
@@ -3182,6 +3200,12 @@ public class Intent implements Parcelable {
      * only specify a type and not data, for example to indicate the type of
      * data to return.  This method automatically clears any data that was
      * previously set by {@link #setData}.
+     * 
+     * <p><em>Note: MIME type matching in the Android framework is
+     * case-sensitive, unlike formal RFC MIME types.  As a result,
+     * you should always write your MIME types with lower case letters,
+     * and any MIME types you receive from outside of Android should be
+     * converted to lower case before supplying them here.</em></p>
      *
      * @param type The MIME type of the data being handled by this intent.
      *
@@ -3204,6 +3228,13 @@ public class Intent implements Parcelable {
      * to override the MIME type that would ordinarily be inferred from the
      * data with your own type given here.
      *
+     * <p><em>Note: MIME type, Uri scheme, and host name matching in the
+     * Android framework is case-sensitive, unlike the formal RFC definitions.
+     * As a result, you should always write these elements with lower case letters,
+     * and normalize any MIME types or Uris you receive from
+     * outside of Android to ensure these elements are lower case before
+     * supplying them here.</em></p>
+     *
      * @param data The URI of the data this intent is now targeting.
      * @param type The MIME type of the data being handled by this intent.
      *
diff --git a/core/java/android/content/IntentFilter.java b/core/java/android/content/IntentFilter.java
index e81bc86326ee..9b190df84cd4 100644
--- a/core/java/android/content/IntentFilter.java
+++ b/core/java/android/content/IntentFilter.java
@@ -86,18 +86,27 @@ import com.android.internal.util.XmlUtils;
  * type is determined by calling {@link Intent#resolveType}.  A wildcard can be
  * used for the MIME sub-type, in both the Intent and IntentFilter, so that the
  * type "audio/*" will match "audio/mpeg", "audio/aiff", "audio/*", etc.
+ * <em>Note that MIME type matching here is <b>case sensitive</b>, unlike
+ * formal RFC MIME types!</em>  You should thus always use lower case letters
+ * for your MIME types.
  *
  * <p><strong>Data Scheme</strong> matches if any of the given values match the
  * Intent data's scheme.
  * The Intent scheme is determined by calling {@link Intent#getData}
  * and {@link android.net.Uri#getScheme} on that URI.
+ * <em>Note that scheme matching here is <b>case sensitive</b>, unlike
+ * formal RFC schemes!</em>  You should thus always use lower case letters
+ * for your schemes.
  *
  * <p><strong>Data Authority</strong> matches if any of the given values match
  * the Intent's data authority <em>and</em> one of the data scheme's in the filter
  * has matched the Intent, <em>or</em> no authories were supplied in the filter.
  * The Intent authority is determined by calling
  * {@link Intent#getData} and {@link android.net.Uri#getAuthority} on that URI.
- *
+ * <em>Note that authority matching here is <b>case sensitive</b>, unlike
+ * formal RFC host names!</em>  You should thus always use lower case letters
+ * for your authority.
+ * 
  * <p><strong>Data Path</strong> matches if any of the given values match the
  * Intent's data path <em>and</em> both a scheme and authority in the filter
  * has matched against the Intent, <em>or</em> no paths were supplied in the
@@ -340,6 +349,12 @@ public class IntentFilter implements Parcelable {
     /**
      * New IntentFilter that matches a single action and data type.
      *
+     * <p><em>Note: MIME type matching in the Android framework is
+     * case-sensitive, unlike formal RFC MIME types.  As a result,
+     * you should always write your MIME types with lower case letters,
+     * and any MIME types you receive from outside of Android should be
+     * converted to lower case before supplying them here.</em></p>
+     *
      * <p>Throws {@link MalformedMimeTypeException} if the given MIME type is
      * not syntactically correct.
      *
@@ -477,6 +492,12 @@ public class IntentFilter implements Parcelable {
      * one of these types <em>or</em> a matching scheme.  If no data types
      * are included, then an Intent will only match if it specifies no data.
      *
+     * <p><em>Note: MIME type matching in the Android framework is
+     * case-sensitive, unlike formal RFC MIME types.  As a result,
+     * you should always write your MIME types with lower case letters,
+     * and any MIME types you receive from outside of Android should be
+     * converted to lower case before supplying them here.</em></p>
+     *
      * <p>Throws {@link MalformedMimeTypeException} if the given MIME type is
      * not syntactically correct.
      *
@@ -546,6 +567,12 @@ public class IntentFilter implements Parcelable {
      * one of these schemes <em>or</em> a matching data type.  If no schemes
      * are included, then an Intent will match only if it includes no data.
      *
+     * <p><em>Note: scheme matching in the Android framework is
+     * case-sensitive, unlike formal RFC schemes.  As a result,
+     * you should always write your schemes with lower case letters,
+     * and any schemes you receive from outside of Android should be
+     * converted to lower case before supplying them here.</em></p>
+     *
      * @param scheme Name of the scheme to match, i.e. "http".
      *
      * @see #matchData
@@ -630,6 +657,16 @@ public class IntentFilter implements Parcelable {
             return mPort;
         }
 
+        /**
+         * Determine whether this AuthorityEntry matches the given data Uri.
+         * <em>Note that this comparison is case-sensitive, unlike formal
+         * RFC host names.  You thus should always normalize to lower-case.</em>
+         * 
+         * @param data The Uri to match.
+         * @return Returns either {@link IntentFilter#NO_MATCH_DATA},
+         * {@link IntentFilter#MATCH_CATEGORY_PORT}, or
+         * {@link IntentFilter#MATCH_CATEGORY_HOST}.
+         */
         public int match(Uri data) {
             String host = data.getHost();
             if (host == null) {
@@ -663,6 +700,12 @@ public class IntentFilter implements Parcelable {
      * included in the filter, then an Intent's data must match one of
      * them.  If no authorities are included, then only the scheme must match.
      *
+     * <p><em>Note: host name in the Android framework is
+     * case-sensitive, unlike formal RFC host names.  As a result,
+     * you should always write your host names with lower case letters,
+     * and any host names you receive from outside of Android should be
+     * converted to lower case before supplying them here.</em></p>
+     *
      * @param host The host part of the authority to match.  May start with a
      *             single '*' to wildcard the front of the host name.
      * @param port Optional port part of the authority to match.  If null, any
@@ -821,13 +864,20 @@ public class IntentFilter implements Parcelable {
      * schemes/paths, the match will only succeed if the intent does not
      * also specify a type or data.
      *
-     * <p>Note that to match against an authority, you must also specify a base
+     * <p>Be aware that to match against an authority, you must also specify a base
      * scheme the authority is in.  To match against a data path, both a scheme
      * and authority must be specified.  If the filter does not specify any
      * types or schemes that it matches against, it is considered to be empty
      * (any authority or data path given is ignored, as if it were empty as
      * well).
      *
+     * <p><em>Note: MIME type, Uri scheme, and host name matching in the
+     * Android framework is case-sensitive, unlike the formal RFC definitions.
+     * As a result, you should always write these elements with lower case letters,
+     * and normalize any MIME types or Uris you receive from
+     * outside of Android to ensure these elements are lower case before
+     * supplying them here.</em></p>
+     *
      * @param type The desired data type to look for, as returned by
      *             Intent.resolveType().
      * @param scheme The desired data scheme to look for, as returned by
diff --git a/core/res/res/values/attrs_manifest.xml b/core/res/res/values/attrs_manifest.xml
index 2ff096250015..093ddd33f3d6 100644
--- a/core/res/res/values/attrs_manifest.xml
+++ b/core/res/res/values/attrs_manifest.xml
@@ -1062,15 +1062,24 @@
     <declare-styleable name="AndroidManifestData" parent="AndroidManifestIntentFilter">
         <!-- Specify a MIME type that is handled, as per
              {@link android.content.IntentFilter#addDataType
-             IntentFilter.addDataType()}. -->
+             IntentFilter.addDataType()}.
+             <p><em>Note: MIME type matching in the Android framework is
+             case-sensitive, unlike formal RFC MIME types.  As a result,
+             MIME types here should always use lower case letters.</em></p> -->
         <attr name="mimeType" format="string" />
         <!-- Specify a URI scheme that is handled, as per
              {@link android.content.IntentFilter#addDataScheme
-             IntentFilter.addDataScheme()}. -->
+             IntentFilter.addDataScheme()}.
+             <p><em>Note: scheme matching in the Android framework is
+             case-sensitive, unlike the formal RFC.  As a result,
+             schemes here should always use lower case letters.</em></p> -->
         <attr name="scheme" format="string" />
         <!-- Specify a URI authority host that is handled, as per
              {@link android.content.IntentFilter#addDataAuthority
-             IntentFilter.addDataAuthority()}. -->
+             IntentFilter.addDataAuthority()}.
+             <p><em>Note: host name matching in the Android framework is
+             case-sensitive, unlike the formal RFC.  As a result,
+             host names here should always use lower case letters.</em></p> -->
         <attr name="host" format="string" />
         <!-- Specify a URI authority port that is handled, as per
              {@link android.content.IntentFilter#addDataAuthority
@@ -1140,10 +1149,17 @@
             {@link android.content.Intent#setAction Intent.setAction()}. -->
         <attr name="action" format="string" />
         <!-- The data URI to assign to the Intent, as per
-            {@link android.content.Intent#setData Intent.setData()}. -->
+            {@link android.content.Intent#setData Intent.setData()}.
+            <p><em>Note: scheme and host name matching in the Android framework is
+            case-sensitive, unlike the formal RFC.  As a result,
+            Uris here should always be normalized to use lower case letters
+            for these elements (as well as other proper Uri normalization).</em></p> -->
         <attr name="data" format="string" />
         <!-- The MIME type name to assign to the Intent, as per
-            {@link android.content.Intent#setType Intent.setType()}. -->
+            {@link android.content.Intent#setType Intent.setType()}.
+            <p><em>Note: MIME type matching in the Android framework is
+            case-sensitive, unlike formal RFC MIME types.  As a result,
+            MIME types here should always use lower case letters.</em></p> -->
         <attr name="mimeType" />
         <!-- The package part of the ComponentName to assign to the Intent, as per
             {@link android.content.Intent#setComponent Intent.setComponent()}. -->