Java methods and XML elements

An intent’s Java methods include the following:

• setAction: Sets the intent’s action.
• addCategory: Adds a category to the intent.
• setData: Sets the intent’s URI and removes the intent’s MIME type (if the intent has a MIME type).
• setType: Sets the intent’s MIME type and removes the intent’s URI (if the intent has a URI).
• setDataAndType: Sets both the intent’s URI and the intent’s MIME type. According to the docs, “This method should very rarely be used.”

You can describe an intent filter in an AndroidManifest.xml document or in Java code. In an AndroidManifest.xml document, the <intent-filter> element has <action>, <category>, and <data> subelements.

<action android:name="string" />

<category android:name="string" />

<data android:scheme="string"

      android:host="string"

      android:port="string"

      android:path="string"

      android:pathPattern="string"

      android:pathPrefix="string"

      android:mimeType="string" />

The intent methods and the data element’s attributes aren’t parallel. For example, with an intent’s setAction method, you set an intent’s one and only action (if you want the intent to have an action). But with a filter’s <action> element, you add one of possibly many actions to the filter. With an intent’s setData method, you set an intent’s one and only URI (if you want the intent to have a URI). But with a filter’s <data> elements, you add individual pieces of a URI.

You typically set a filter’s values in the AndroidManifest.xml file. But in Java code, the android.content.IntentFilter class has lots of useful methods. I list a few here:

• addAction: Adds an action to the filter.
• addCategory: Adds a category to the filter.
• addDataScheme: Adds a scheme to the filter.
• addDataAuthority: Adds an authority to the filter.
• addDataPath: Adds a path to the filter.
• addDataType: Adds a MIME type to the filter.

As was the case with the intent methods and the data element’s attributes, the intent methods and the filter methods aren’t parallel. An intent’s setAction method does the obvious — it sets an intent’s action (if you want the intent to have an action). A filter’s addAction method, however, lets you add one of possibly many actions to the filter. An intent’s setData method sets an intent’s URI (if you want the intent to have a URI). A filter’s addDataScheme, addDataAuthority, and addDataPath methods, on the other hand, let you separately add pieces of a URI.

Matching actions

According to Figure 2-5, an intent’s action must be matched with one of the filter’s actions. That makes sense because an intent’s action says, “I want a component that can do such-and-such.” And the filter’s action says, “I can do such-and-such.” The filter might have other actions (be able to do other things), but having additional filter actions doesn’t prevent an intent from matching with a filter.

Exactly what is an action? The simplest answer is that an action is a string. You can create your own action string "thisismyaction" or "allmycode.intent.action.DO_THIS" — Android’s docs recommend the latter form. But Android also has a bunch of standard actions — actions reserved for certain kinds of work. For example, when a developer creates an activity that can display something (a document, a web page, an image, or whatever), the developer includes "android.intent.action.VIEW" in the activity’s filter. Then, when you want someone else’s activity to display something, you put the string "android.intent.action.VIEW" (or the constant android.content.Intent.ACTION_VIEW, whose value is the string "android.intent.action.VIEW") in your intent.

Table 2-1 lists some of my favorite standard actions.

For a complete list of Android’s standard actions, visit http://developer.android.com/reference/android/content/Intent.html.

Here’s a useful experiment:

1. Create a new Android project with two activities — the main activity and a second OtherActivity.java activity.

   For help creating an app’s second activity, see Book 1, Chapter 6.

2. Modify the second activity element in the project’s AndroidManifest.xml file so that it reads as follows:

   <activity android:name=".OtherActivity">

     <intent-filter>

       <action

         android:name="com.allmycode.action.MY_ACTION" />

       <category

         android:name="android.intent.category.DEFAULT" />

     </intent-filter>

   </activity>

3. In the main activity, add the following code:

   final String THE_ACTION =

       "com.allmycode.action.MY_ACTION";

   Intent = new Intent();

   intent.setAction(THE_ACTION);

   startActivity(intent);

    

   Add this code after the call to setContentView in the activity’s onCreate method.

4. Using Android Studio’s Designer tool, change the layout of the other activity.

   Any change is okay. The only reason for changing the other activity’s layout is to help you recognize which of the two activities (the main activity or the other activity) is on the emulator’s screen.

5. Run the project.

   As soon as your emulator executes the code in Step 3, Android launches the other activity. The intent’s "com.allmycode.action.MY_ACTION" matches the filter’s "com.allmycode.action.MY_ACTION", so the other activity starts running.

   Real Android developers use a standard action (such as the actions in Table 2-1), or they make up dotted action names, such as "com.allmycode.action.MY_ACTION". Real developers type that "com.allmycode.action.MY_ACTION" string in the AndroidManifest.xml file (because they must). But in the Java code, real developers create a constant value to represent the string (because it’s good programming practice).

   The category element in Step 2 of this section’s instructions is an anomaly that I cover in the later section “The fine print.” If you don’t want to skip to that section, simply add the category "android.intent.category.DEFAULT" to each filter in your AndroidManifest.xml file.

   Continuing the experiment …

6. Comment out (or delete) the following element from your project’s AndroidManifest.xml file:

   <action

     android:name="com.allmycode.action.MY_ACTION" />

7. Run your project again.

   When your emulator executes the Java code in Step 3, your app crashes. The filter has no action matching your intent’s "com.allmycode.action.MY_ACTION", and (in all likelihood) no other activity on your emulator has a filter containing "com.allmycode.action.MY_ACTION".

   In Step 7, your app intentionally crashes. Crashes make good learning experiences, but users tend not to appreciate such learning experiences. To avoid the kind of disaster you see in Step 7, call the PackageManager class’s queryIntentActivities method before attempting to call startActivity. Alternatively, you can put your startActivity call in a try/catch block with the ActivityNotFoundException:

   try {

     startActivity(intent);

   } catch (ActivityNotFoundException e) {

     e.printStackTrace();

   }

    

   Working through these particular lines of code, note that they start out by telling Java to try startActivity — to call it, in other words. If Android can’t start an activity (that is, if Android can’t find an activity to match the intent), Java jumps to the statement e.printStackTrace(), which displays error information in Android Studio’s Logcat panel. After displaying the information, Java marches on to execute whatever code comes after the attempt to call startActivity. Therefore, the app doesn’t crash — the error has been caught.

   For more on try/catch blocks, see Book II, Chapter 3.

8. Uncomment the element that you commented out in Step 6.
9. Modify the other activity’s element in the AndroidManifest.xml file as follows:

   <activity android:name=".OtherActivity">

     <intent-filter>

       <action

         android:name="com.allmycode.action.MY_ACTION" />

       <action

         android:name="com.allmycode.action.X_ACTION" />

       <category

         android:name="android.intent.category.DEFAULT" />

     </intent-filter>

   </activity>

10. Run the project again.

    When your emulator executes the Java code in Step 3, Android launches the other activity. The intent’s "com.allmycode.action.MY_ACTION" matches the filter’s "com.allmycode.action.MY_ACTION", and the filter’s additional "com.allmycode.action.X_ACTION" doesn’t require a match.

Following this example’s steps for each intent and filter that you want to test can become very tedious. So to help you test matches, I’ve created a special Android app. For details, see the “Practice, Practice, Practice” section, later in this chapter.

Matching categories

According to Figure 2-5, each of an intent’s categories must be matched with one of the filter’s categories. That makes sense because an intent’s category says, “I want a component of such-and-such kind.” And the filter’s category says, “I’m a such-and-such kind of component.” The filter might have other categories, but having additional filter categories doesn’t prevent an intent from matching with a filter.

Exactly what is a category? Like an action, a category is a string. You can create your own category string "thisismycategory" or "allmycode.intent.category.THIS_KIND"; Android’s docs recommend the latter form. But Android also has a bunch of standard categories — categories reserved for certain kinds of components. Table 2-2 lists some of my favorites.

Consider the kitty-cat intent created with the following Java code:

final String THE_ACTION =

        "com.allmycode.action.MY_ACTION";

final String THE_CATEGORY =

        "com.allmycode.category.KITTY";

Intent intent = new Intent();

intent.setAction(THE_ACTION);

intent.addCategory(THE_CATEGORY);

startActivity(intent);

This kitty-cat intent matches a filter with the following XML code:

<activity android:name=".OtherActivity">

  <intent-filter>

    <action

      android:name="com.allmycode.action.MY_ACTION" />

    <category

      android:name="com.allmycode.category.KITTY" />

    <category

      android:name="android.intent.category.DEFAULT" />

  </intent-filter>

</activity>

The kitty-cat intent also matches the following intent because (in the language of speed dating) filter categories aren’t needy.

<activity android:name=".OtherActivity">

  <intent-filter>

    <action

      android:name="com.allmycode.action.MY_ACTION" />

    <category

      android:name="com.allmycode.category.KITTY" />

    <category

      android:name="Otto.Schmidlap" />

    <category

      android:name="android.intent.category.DEFAULT" />

  </intent-filter>

</activity>

The kitty-cat intent does not match the following intent because an intent’s categories are needy:

<activity android:name=".OtherActivity">

  <intent-filter>

    <action

      android:name="com.allmycode.action.MY_ACTION" />

    <category

      android:name="Otto.Schmidlap" />

    <category

      android:name="android.intent.category.DEFAULT" />

  </intent-filter>

Matching data

Figure 2-5 illustrates an interesting relationship between an intent’s data and a filter’s data:

• If an intent has a URI or if a filter has a URI, one of the filter’s URIs must match the intent’s URI.
• If an intent has a MIME type or if a filter has a MIME type, one of the filter’s MIME types must match the intent’s MIME type.

These rules have some corollaries:

• An intent without a URI cannot match a filter with a URI. A filter without a URI cannot match an intent with a URI.
• An intent without a MIME type cannot match a filter with a MIME type. A filter without a MIME type cannot match an intent with a MIME type.

How does all this stuff about URIs and MIME types make sense? The deal is, data doesn’t perform the same role as an action or a category in matching a filter with an intent. Imagine that an intent announces, “I want a component to perform android.intent.action.VIEW”, and a certain activity’s filter announces, “I can perform android.intent.action.VIEW”. The intent doesn’t care if the filter announces that it can perform other actions.

But what if an intent announces, “I want a component to handle the URI tel:6502530000"? (The URI tel:6502530000 places a call to Google’s corporate headquarters in Mountain View, California.) An appropriate filter contains the tel scheme. (See Figure 2-6.) Now, imagine another intent with no tel: URI and a filter whose only scheme is the tel scheme. (Again, see Figure 2-6.) In this case, the filter says, “I can do something useful with a telephone number, and when I’m invoked, I expect to receive a telephone number.” If the intent has no tel: URI, a match isn’t appropriate.

So the coupling between an intent’s and a filter’s data is stronger than the coupling between actions or the coupling between categories. With the URI part of the data, both the intent and the filter are needy. The same is true of the data’s MIME types.

The following intent and filter form a match:

final String THE_ACTION =

        "com.allmycode.action.MY_ACTION";

Intent intent = new Intent();

intent.setAction(THE_ACTION);

intent.setData(Uri.parse("http:"));

startActivity(intent);

<intent-filter>

  <action

    android:name="com.allmycode.action.MY_ACTION" />

  <category

    android:name="android.intent.category.DEFAULT" />

  <data android:scheme="http" />

  <data android:scheme="mymadeupscheme" />

</intent-filter>

The same intent with a slightly modified filter does not form a match because the set of MIME types in a filter is needy:

<intent-filter>

  <action

    android:name="com.allmycode.action.MY_ACTION" />

  <category

    android:name="android.intent.category.DEFAULT" />

  <data android:scheme="http" />

  <data android:scheme="mymadeupscheme" />

  <data android:mimeType="text/html" />

</intent-filter>

To match this modified filter, you need either of the following intents:

final String THE_ACTION =

        "com.allmycode.action.MY_ACTION";

Intent intent = new Intent();

intent.setAction(THE_ACTION);

intent.setDataAndType(Uri.parse("http:"), "text/html");

startActivity(intent);

final String THE_ACTION =

        "com.allmycode.action.MY_ACTION";

Intent intent = new Intent();

intent.setAction(THE_ACTION);

intent.setDataAndType

    (Uri.parse("mymadeupscheme:"), "text/html");

startActivity(intent);

Finally, the following intent and filter form a match because the MIME type in the intent matches one of the MIME types in the filter:

final String THE_ACTION =

        "com.allmycode.action.MY_ACTION";

Intent intent = new Intent();

intent.setAction(THE_ACTION);

intent.setType("text/html");

startActivity(intent);

<intent-filter>

  <action

    android:name="com.allmycode.action.MY_ACTION" />

  <category

    android:name="android.intent.category.DEFAULT" />

  <data android:mimeType="abc/xyz" />

  <data android:mimeType="text/html" />

</intent-filter>

Matching parts of the data

The section “Java methods and XML elements,” earlier in this chapter, lists methods and XML elements. With an intent’s setData method, you set an intent’s URI (if you want the intent to have a URI). With a filter’s <data> elements, you add individual pieces of a URI. The filter’s pieces don’t have to fit together. For example, the following intent and filter form a match:

final String THE_ACTION =

        "com.allmycode.action.MY_ACTION";

Intent intent = new Intent();

intent.setAction(THE_ACTION);

intent.setData(Uri.parse("abc://example.com:2222"));

startActivity(intent);

<intent-filter>

  <data android:scheme="xyz" android:host="example.com" />

  <data android:port="2222" />

  <action

    android:name="com.allmycode.action.MY_ACTION" />

  <category

    android:name="android.intent.category.DEFAULT" />

  <data android:scheme="abc" />

</intent-filter>

A filter can have schemes "abc" and "xyz", and authority "example.com". Then the filter’s data matches both intent data "abc://example.com" and intent data "xyz://example.com". This works even if you lump "xyz" and "example.com" in the same <data> element.

With a filter’s addDataScheme, addDataAuthority, and addDataPath methods, you separately add pieces of a URI. For example, the following intent and filter form a match:

final String THE_ACTION =

        "com.allmycode.action.MY_ACTION";

Intent intent = new Intent();

intent.setAction(THE_ACTION);

intent.setData(Uri.parse("abc://example.com:2222"));

final IntentFilter filter = new IntentFilter();

filter.addAction(THE_ACTION);

// Constant com.content.Intent.CATEGORY_DEFAULT has

//   value "android.intent.category.DEFAULT"

filter.addCategory(Intent.CATEGORY_DEFAULT);

filter.addDataScheme("abc");

filter.addDataScheme("xyz");

filter.addDataAuthority("example.com", "2222");

At this point, a few observations are in order:

• An intent has three similar methods @@ setData, setDataAndType, and setType. You call setData for an intent with a URI but no MIME type. You call setType for an intent with a MIME type but no URI. You call setDataAndType only for an intent with both a URI and a MIME type.
• You don’t pass a string to the setData method or to the first parameter of the setDataAndType method. Instead, you pass an instance of the android.net.Uri class. You do this by applying the method Uri.parse to a string of characters.
• Here’s a silly but important detail: A call to intent.setData(Uri.parse("http:")) with a colon after http matches the filter element <data android:scheme="http" /> without a colon after the http. Other combinations of colon/no-colon for a URI scheme fail to make a match.

Matching URIs

Figure 2-5 illustrates an imaginary speed-dating event for the parts of an intent and an intent filter. The figure doesn’t address the matching of one URI with another. So imagine that the URIs in Figure 2-5 bring their darling little children (their schemes, authorities, and paths) to the speed-dating event. As the evening begins, the kids go off to a separate room for a speed-dating event of their own. (Sure, they’re too young to date. But it’s good practice for adolescence.) Figure 2-7 illustrates the neediness situation in the kids' event.

The situation with the URI’s kids is similar to the situation with all data. Everybody’s happy as long as each thing on the intent side matches something on the filter side. For example, the following intent and filter form a match:

final String THE_ACTION =

        "com.allmycode.action.MY_ACTION";

Intent intent = new Intent();

intent.setAction(THE_ACTION);

intent.setData(Uri.parse("abc://example.com:2222"));

startActivity(intent);

<intent-filter>

  <action

    android:name="com.allmycode.action.MY_ACTION" />

  <category

    android:name="android.intent.category.DEFAULT" />

  <data android:scheme="abc" />

</intent-filter>

But with the same intent, the following filter isn’t a match:

<intent-filter>

  <action

    android:name="com.allmycode.action.MY_ACTION" />

  <category

    android:name="android.intent.category.DEFAULT" />

  <data android:scheme="abc" />

  <data android:host="example.com" />

  <data android:port="2222" />

  <data android:path="/some/stuff" />

</intent-filter>

The fine print

With all the fuss about filter matching in the previous sections, you’d think the issue was covered and done with. But the work is never done. Here’s a list of filter matching’s most important gotchas and exceptions:

• Android treats activities differently from other components (such as services and broadcast receivers).

  You can create an implicit intent with no actions. If you do, a call to startActivity(intent) doesn’t find a match among any activity filters. However, calls to sendBroadcast(intent) or to bindService(intent,…) may find matches.

• With respect to categories, Android treats activities differently from other components.

  When you try to start an activity, Android behaves as if the intent contains the "android.intent.category.DEFAULT" category. (Android does this even if you don’t execute code to add that category to the intent.) Because of this, an activity filter without the "android.intent.category.DEFAULT" category never matches an intent. Broadcast receivers and services don’t suffer from this anomaly.

  The activity that starts when the user first presses an app’s icon is the app’s main activity. A main activity’s filter normally contains the action "android.intent.action.MAIN" and the category "android.intent.category.LAUNCHER". If you want an activity to function only as a main activity (and never be started by an app’s call to startActivity), you can safely omit "android.intent.category.DEFAULT" from the activity’s filter.

• Flip back to Figure 2-3 to see the kinds of URIs you can create. A URI with an authority must have a scheme, and a URI with a path must have an authority and a scheme. Also, a port without a host is ignored. So the following strings are not valid URIs:

  • example.com: Has an authority but no scheme.
  • http:///folder/subfolder: Has a path but no authority.

  The official Android docs provide the following loophole: “ … if a host is not specified, the port is ignored.” So a URI like http://:2000/folder is strange but valid. I’ve created such URIs in captivity, but I’ve never encountered one in the wild.

• A filter URI with nothing but a scheme matches any intent URI with the same scheme. Take, for example, the intent URI to call Google’s corporate headquarters, tel:6502530000. An appropriate filter probably contains the tel scheme but not the number 6502530000. (A filter whose sole URI is tel:6502530000 can call only Google’s corporate headquarters. The filter would be useful only for an Unsatisfied Google Customer app.)

  In the same way, a filter URI with a scheme, an authority, and no path matches any intent filter with the same scheme and the same authority.

• The schemes content and file get special treatment. If the intent’s URI has scheme content or scheme file, and the intent has a MIME type, you can omit the scheme from the filter. (You must still have a match between the intent’s MIME type and one of the filter’s MIME types.) Someday this rule will make sense to me.
• Certain parts of the data may contain wildcards or simplified regular expressions. Here are a few examples:
  • The type text/* matches text/plain. The type text/* also matches text/html and text/whatever. The type text/* matches text/ (with a slash and no subtype) but does not match text (with no slash and no subtype).
  • The type */* matches text/plain. The type */* also matches image/jpeg, and so on.
  • The type * (one wildcard with no slash) and */html don’t seem to match anything.
  • The type text/ht* doesn’t match text/html. (With a top-level type or a subtype, the wildcard must be “all or nothing.”)

  • Paths use a simplified regular expression form. (In other words, paths can include wildcards and other funky symbols.) For example, the intent URI http://example.com/folder matches the filter URI with scheme http, authority example.com, and path pattern /fol.*. In the AndroidManifest.xml file, the data element’s android:path, android:pathPrefix, and android:pathPattern attributes distinguish among the various possibilities.

    For more information about path expressions, visit http://developer.android.com/guide/topics/manifest/data-element.html.

  • With the exception of the host name, the strings in an intent and its filter are case-sensitive. So text/html doesn’t match TEXT/HTML, and HTTP doesn’t match http. But http://example.com matches http://EXAMPLE.com. Android’s docs recommend using mostly lowercase letters.