This article will examine how the Android operating system takes this combination of VIEW action and content: URI and finds the correct activity to fire in order to do something with the data. It will also explain how the other default links created by Linkify, like web URLs and telephone numbers, also result in the correct activity to handle that data type being fired. Finally, this article will start to examine the custom ContentProvider that has been created to handle WikiNotes data. The full description of the ContentProvider and what it does will span a couple more articles as well, because there is a lot to cover.

The Linkify-calls-intent Workflow

At a high level, the steps for Linkify to invoke an intent and for the resulting activity (if any) to handle it looks like this:

1. Linkify is invoked on a TextView to turn matching text patterns into Intent links.
2. Linkify takes over monitoring for those Intent links being selected by the user.
3. When the user selects a link, Linkify calls the VIEW action using the content: URI associated with the link.
4. Android takes the content: URI that represents the data, and looks for a ContentProvider registered in the system that matches the URI.
5. If a match is found, Android queries the ContentProvider using the URI, and asks what MIME type the data that will be returned from the URI is.
6. Android then looks for an activity registered in the system with an intent-filter that matches both the VIEW action, and the MIME type for the data represented by the content: URI.
7. Assuming a match is found, Linkify then invokes the intent for the URI, at which point the activity takes over, and is handed the content: URI.
8. The activity can then use the URI to retrieve the data and act on it.

If this sounds complicated, it really is a simpler process than it sounds, and it is quite lightweight as well. Perhaps a more understandable statement about how it works might be:

Linkify is used to turn matching text into hot-links. When the user selects a hot-link, Android takes the data locator represented by the hot-link and looks for a data handler for that data locator. If it finds one, it asks for what type of data is returned for that locator. It then looks for something registered with the system that handles that type of data for the VIEW action, and starts it, including the data locator in the request.

The real key here is the MIME type. MIME stands for Multipurpose Internet Mail Extensions - a standard for sending attachments over email. The MIME type (which is the part Android uses) is a way of describing certain kinds of data. That type is then used to look for an Activity that can do something with that data type. In this way, ContentProviders and Activities (or other IntentReceivers) are decoupled, meaning that a given Content URI might have a different ContentProvider to handle it, but could still use the same MIME type meaning that the same activity could be called upon to handle the resulting data.

Linkify on a Wiki Word

Using the above workflow, let's take a look at exactly how the process works in WikiNotes for Android:

First, Linkify is used to turn text matching the wiki word regular expression into a link that provides a Content URI for that wiki word, for example content://com.google.android.wikinotes.db.wikinotes/wikinotes/ToDoList.

When the user clicks on the wiki word link, Linkify invokes the VIEW action on the Content URI. At this point, the Android system takes over getting the Intent request to the correct activity.

Next, Android looks for a ContentProvider that has been registered with the system to handle URIs matching our Content URI format.

In our case, we have a definition inside our application in the AndroidManifest.xml file that reads:

<provider name="com.google.android.wikinotes.db.WikiNotesProvider" 
    android:authorities="com.google.android.wikinotes.db.wikinotes" />

This establishes that we have a ContentProvider defined in our application that provides the "root authority": com.google.android.wikinotes.db.wikinotes. This is the first part of the Content URI that we create for a wiki word link. Root Authority is just another way of thinking about a descriptor that is registered with Android to allow requests for certain URLs to be routed to the correct class.

So, the whole definition is that a class called com.google.android.wikinotes.db.WikiNotesProvider is registered with the system as able to handle the com.google.android.wikinotes.db.wikinotes root authority (i.e. URIs starting with that identifier).

From here, Android takes the rest of the URI and present it to that ContentProvider. If you look at the WikiNotesProvider class and scroll to the very bottom - the static block there, you can see the pattern definitions to match the rest of the URL.

In particular, take a look at the two lines:

URI_MATCHER.addURI(WikiNote.WIKINOTES_AUTHORITY, "wikinotes", NOTES);
URI_MATCHER.addURI(WikiNote.WIKINOTES_AUTHORITY, "wikinotes/*", NOTE_NAME);

These are the definitions of URIs that our ContentProvider recognizes and can handle. The first recognizes a full URI of content://com.google.android.wikinotes.db.wikinotes/wikinotes and associates that with a constant called NOTES. This is used elsewhere in the ContentProvider to provide a list of all of the wiki notes in the database when the URI is requested.

The second line uses a wildcard - '*' - to match a request of the form that Linkify will create, e.g. content://com.google.android.wikinotes.db.wikinotes/wikinotes/ToDoList. In this example, the * matches the ToDoList part of the URI and is available to the handler of the request, so that it can fish out the matching note for ToDoList and return it as the data. This also associates that match with a constant called NOTE_NAME, which again is used as an identifier elsewhere in the ContentProvider.

The other matches in this static block are related to forms of searching that have been implemented in the WikiNotes for Android application, and will be covered in later articles. Likewise, how the data is obtained from this matching pattern will be the subject of the next article.

For right now we are concerned with the MIME type for the URI. This is defined in the getType() method also in the WikiNotesProvider class (about half way through the file). Take a quick look at this. The key parts for now are:

case NOTES:
    return "vnd.android.cursor.dir/vnd.google.wikinote";

case NOTE_NAME:
    return "vnd.android.cursor.item/vnd.google.wikinote";

These are the same constant names we defined in our pattern matchers. In the first case, that of the all notes URI, the MIME type returned is vnd.android.cursor.dir/vnd.google.wikinote which is like saying an Android list (dir) of Google wiki notes (the vnd bit is MIME speak for "vendor specific definition"). Likewise, in the case of a NOTE_NAME match, the MIME type returned is vnd.android.cursor.item/vnd.google.wikinote which is like saying an Android item of Google wiki notes.

Note that if you define your own MIME data types like this, the vnd.android.cursor.dir and vnd.android.cursor.item categories should be retained, since they have meaning to the Android system, but the actual item types should be changed to reflect your particular data type.

So far Android has been able to find a ContentProvider that handles the Content URI supplied by the Linkify Intent call, and has queried the ContentProvider to find out the MIME types for that URI. The final step is to find an activity that can handle the VIEW action for that MIME type. Take a look in the the AndroidManifest.xml file again. Inside the WikiNotes activity definition, you will see:

<intent-filter>
    <action name="android.intent.action.VIEW"/>
    <category name="android.intent.category.DEFAULT"/>
    <category name="android.intent.category.BROWSABLE"/>
    <data mimetype="vnd.android.cursor.item/vnd.google.wikinote"/>
</intent-filter>

This is the correct combination of matches for the VIEW action on a WikiNote type that is requested from the LINKIFY class. The DEFAULT category indicates that the WikiNotes activity should be treated as a default handler (a primary choice) for this kind of data, and the BROWSABLE category means it can be invoked from a "browser", in this case the marked-up Linkified text.

Using this information, Android can match up the VIEW action request for the WikiNotes data type with the WikiNotes activity, and can then use the WikiNotes activity to handle the request.

Why do it like this?

It's quite a trip through the system, and there is a lot to absorb here, but this is one of the main reasons I wanted to write WikiNotes in the first place. If you follow and understand the steps here, you'll have a good grasp of the whole Intents mechanism in Android, and how it helps loosely coupled activities cooperate to get things done.

In this case, we could have found another way to detect wiki words based on a regular expression, and maybe written our own handler to intercept clicks within the TextView and dig out the right data and display it. This would seem to accomplish the same functionality just as easily as using intents, so what is the advantage to using the full Intents mechanism?

In fact there are several advantages:

The most obvious is that because we are using the standard Intent based approach, we are not limited to just linking and navigating to other wiki notes. We get similar behavior to a number of other data types as well. For example, a telephone number or web URL in a wiki note will be marked up by Linkify, and using this same mechanism (VIEW action on the linked data type) the browser or dialer activities will be automatically fired.

It also means that each operation on a wiki note can be treated as a separate life cycle by our activity. We are not dealing with swapping data in and out of an existing activity - each activity works on a particular wiki note and that's all you have to worry about.

Another advantage is that we now have a public activity to handle VIEW actions in WikiNotes no matter where the request comes from. Another application could request to view a wiki note (perhaps without even knowing what kind of data it is) and our activity could start up and handle it.

The backstack is automatically maintained for you too. As you forward navigate through WikiNotes, Android maintains the history of notes visited, and so when you hit the back button you go back to the last note you were on. All this is free because we rely on the Android intents mechanism.

Finally, if you run WikiNotes for Android and then start DDMS to take a look at the Activity threads in the WikiNotes application while it is running, you can see that despite what you might think, letting Android manage the navigation is very efficient. Create a few linked notes, as many links deep as you like, and then follow them. If you follow links hundreds of notes deep, you will still only see a handful of WikiNotes activities. Android is managing the activities, closing the older ones as necessary and using the life cycle to swap data in and out.

Next Time

This was a long article, but necessarily so. It demonstrates the importance of the Intents mechanism and to reinforce the notion that it should be used whenever possible for forward navigation, even within a single application. Illustrating this is one of the primary reasons I wrote WikiNotes for Android in the first place.

In the next article we will look deeper into the ContentProvider and examine how it turns a Content URI into a row (or several rows) of data that can be used by an activity.

This is the first in a series of technical articles about WikiNotes for Android, part of the Apps for Android project.

This article covers the use of Linkify to turn ordinary text views into richer link-oriented content that causes Android intents to fire when a link is selected.

Linkify: The Linkify class in the SDK is perfect for creating a wiki note pad. This class lets you specify a regular expression to match, and a scheme to prepend. The scheme is a string that, when the matched text is added, forms a Content URI to allow the correct data to be looked up.

For example, in our case we want to look for a regular expression match for a WikiWord (that is, a word with camel case and no spaces). Linkify can then turn this into a Content URI - something like >content://com.google.android.wikinotes.db.wikinotes/wikinotes/WikiWord which can then be used to locate the correct wiki page from a content provider.

As a bonus, the Linkify class also defines several default matches, in particular it is able to turn web URLs, email addresses and telephone numbers into active links which fire Android intents automatically.

Linkify can be passed any TextView in your application, and will take care of creating the links and enabling their "clickability" for you.

Default Linkify: Using the set of default active link options is very straightforward - simply pass it a handle to a TextView with content in it, and the Linkify.ALL flag:

TextView noteView = (TextView) findViewById(R.id.noteview);
noteView.setText(someContent);
Linkify.addLinks(noteView, Linkify.ALL);

and that's it. The Linkify.ALL flag applies all of the predefined link actions, and the TextView will be immediately updated with a set of active links which, if you select them, fire default intents for the actions (e.g. a web URL will start the browser with that URL, a telephone number will bring up the phone dialer with that number ready to call, etc.).

Custom Linkify: So what about our WikiWord? There is no pre-defined action for that, so it needs to be defined and associated with a scheme.

The first task is to defined a regular expression that matches the kind of WikiWords we want to find. The regex in this case is:

\b[A-Z]+[a-z0-9]+[A-Z][A-Za-z0-9]+\b

Obvious no? Well actually this is equivalent to the following description: "Starting with a word boundary (the \b) find at least one upper case letter, followed by at least one lower case letter or a numeric digit, followed by another upper case letter, and then any mix of upper case, lower case or numeric until the next word boundary (the final \b)". Regular expressions are not very pretty, but they are an extremely concise and accurate way of specifying a search pattern.

We also need to tell Linkify what to do with a match to the WikiWord. Linkify will automatically append whatever is matched to a scheme that is supplied to it, so for the sake of argument let's assume we have a ContentProvider that matches the following content URI:

content://com.google.android.wikinotes.db.wikinotes/wikinotes/WikiWord

The WikiWord part will be appended by Linkify when it finds a match, so we just need the part before that as our scheme.

Now that we have these two things, we use Linkify to connect them up:

Pattern wikiWordMatcher = Pattern.compile("\\b[A-Z]+[a-z0-9]+[A-Z][A-Za-z0-9]+\\b");
String wikiViewURL =    "content://com.google.android.wikinotes.db.wikinotes/wikinotes/";
Linkify.addLinks(noteView, wikiWordMatcher, wikiViewURL);

Note that the \b's had to be escaped with double backslashes for the Java Pattern.compile line.

Linkify can be used multiple times on the same view to add more links, so using this after the Default Linkify call means that the existing active links will be maintained and the new WikiWords will be added. You could define more Linkify actions and keep applying them to the same TextView if you wanted to.

Now, if we have a WikiWord in the TextView, let's say MyToDoList, Linkify will turn it into an active link with the content URI:

content://com.google.android.wikinotes.db.wikinotes/wikinotes/MyToDoList

and if you click on it, Android will fire the default intent for that content URI.

For this to all work, you will need a ContentProvider that understands that Content URI, and you will need a default activity capable of doing something with the resulting data. I plan to cover these in future blog entries (and soon). In fact, the whole Wiki Note Pad application is currently undergoing some clean up and review, and will then hopefully be released as a sample application.

The first application to be included in the new project is called WikiNotes for Android.

For anyone not familiar with the concept of a wiki, it is a simple way to link up pages of information using WikiWords (words that use CamelCase). For example, in the previous sentence, both WikiWords and CamelCase would become live links in a Wiki, and would take you to pages of information.

WikiNotes for Android is a form of wiki known as a personal wiki. These run on desktops or (in this case) mobile computing devices, and many people like them. They bring a bit more structure to your notes than just a list of subjects. You can choose to link notes or pages up in any manner you like.

This particular implementation uses a regular expression to match WikiWords and turn them into links that fire Intents to go to other notes. Because of the way the links are implemented, the application will also create links out of telephone numbers that take you to the dialer and URLs that start up the browser.

Search by title and content is also implemented, so even if you forget the structure, you can still find that all-important note about where you left your car in the airport car park.

This wiki has a view mode and an edit mode. In view mode, the links become active and allow you to navigate to other notes, or to other activities like dialer and web browser. In edit mode, you see a plain text view that you can edit, and when you confirm the changes it goes back to view mode. There is both a menu entry and keyboard shortcut to switch to edit view, so that you can very quickly make changes. And, if you get lost in the note structure, there is also an option to take you back to the start page.

WikiNotes for Android was written to demonstrate a number of core concepts in Android, including:

• Multiple Activities in an Application (View, Edit, Search, etc.)
• Default intent filters for View/Edit/Search based on MIME types
• Life cycle of Activities
• Message passing via Bundles in Intents
• Use of Linkify to add Intent-firing links to text data
• Using Intents within an application
• Using Intents to use an Activity within another application
• Writing a custom ContentProvider that implements search by note title
• Registration of ReST-like URIs to match titles, and do contents searches
• SQLite implementations for insert, retrieve, update, delete and search
• UI layout and creation for multiple activities
• Menus and keyboard shortcuts

The application remains small in size and features to make it easy to understand. In time, more features will be added to the application to make it more useful, but a sample version with the minimal functionality will always be available for developers new to the Android platform.

If you believe that firing an Intent for every link that is clicked is sub-optimal and will waste resources, please take a look at the running application using DDMS. You will see how efficiently Android re-uses the running Activities and indeed, this is one of the main reasons WikiNotes for Android was written. It demonstrates that using the Android Activities and Intents infrastructure not only makes construction of component-based applications easy, but efficient as well.

There will also be a series of technical articles about the application right here on the Android Developer blog.

And please, keep an eye on the apps-for-android project, as more sample applications will be added to it soon.

Happy wiki-ing.

It has been really valuable spending enough time with a group of motivated developers to move beyond the first steps and into real development work. A couple of my temporary office mates here are already well on their way to implementing a general puzzle application for Android. It will enable you to choose your favorite puzzle engines to install and then play a selection of puzzles downloaded on demand from a server – quite an ambitious project for a first try, but these guys are pretty determined and hope to have a prototype of the first puzzle (battleships) working before I hit the road again on Friday. They are also treating the implementation as a chance to learn the architecture: learning the right way to use the architectural pieces in Android rather than opting for the quick and easy shortcuts, which is the best way to really learn a new platform in my experience (don't compromise, be true to your vision).

The week is far from over yet, with another internal and external hackathon planned, and as many more ideas sessions as we can cram in.

As for the London offices – well they are fantastic. Right in the middle of everything, Jaffa Cakes in the kitchens (if you don't know what a Jaffa Cake is, or how to eat one in particular, check out this informative video on the subject). There are also a wealth of pubs within easy walking of the offices, a welcome feature for an ex-pat like me.

With the holidays getting close, don't forget that a new SDK version was announced last week with several improvements. It might be worth grabbing that before taking off for the holidays, just in case you get the urge to do some Android coding while trying to work out if you ate just a bit too much for dinner.

Happy Holidays...

Dianne Hackborn and Jason Parks are two of the architects on the Android engineering team, and in this podcast they talk to us about the Android platform from a technical perspective.

Dianne and Jason share a background at both Be and PalmSource, and talk about how that experience has been applied to Android. Other topics covered include:

• Some history behind the project
• The high level architecture of Android. For example, how Linux processes handle the VM and manage security (the VM doesn't handle it)
• Details on the Dalvik VM and how it is optimized for small devices
• The architecture: From Intents to Views to Permissions and more
• How XML is slow, but the tools convert the XML to a nicer format for you
• The tooling and steps for building an application on Android
• How so many objects have a URL, and how the environment is like a mini-SOA (Services across processes instead of across the network)
• Thoughts on how you program for small devices, and things to watch out for if you move from the desktop
• The control, or lack of control that you have over the application lifecycle
• "Everything you do drains the battery"
• The thread story: they exist, you don't have to deal with them if you don't want to, and the UI
• Using XMPP for messaging

You can download the episode directly, or subscribe to the show (click here for iTunes one-click subscribe).

The end of last week was Thanksgiving in the US, the tradition is to be with family, eat too much food and watch football (not necessarily in that order).

Apparently some folks took the chance to work on Android projects too. We are highlighting a few of the projects that caught our eye.

One of the coming of age rituals of any new platform is the porting of the Z-machine – the interpreter used in the Zork series of games from Infocom. Now Android has the Z-machine thanks to sussman and mariusm. The project, called Twisty, is available on Google code hosting. Thanks for the lost productivity you guys.

Testing is also a hot topic on our Google groups. While JUnit is bundled with the Android SDK to make it possible to do unit testing, there are many other kinds of testing, like automated acceptance testing. Positron builds on the Android instrumentation features from the SDK to make automated acceptance testing of Android applications possible. The author, phil.h.smith, has a pretty good introduction on how to use Positron as well.

Plugins for other IDEs are another favorite on the Android Google groups. While there are only rumblings about a NetBeans plugin at present, the idea-android project already has an early release for IntelliJ IDEA thanks to aefimov.box and intelliyole.

Dion Almaer also picked up on a crossover GWT/Android project which looks pretty amazing too. Chronoscope is an open source charting and visualization library written in GWT. The team were able to take the library, and with 8 hours of playing with Android, had a port to the Android platform.

Of course, there are many more Android projects springing up all the time, as a search of the android label on Google code hosting will demonstrate. It's great to see all this activity just a couple of weeks after the SDK was released.

Background: While developing my first useful (though small) application for Android, which was a port of an existing utility I use when podcasting, I needed a way of updating a clock displayed on the UI at regular intervals, but in a lightweight and CPU efficient way.

Problem: In the original application I used java.util.Timer to update the clock, but that class is not such a good choice on Android. Using a Timer introduces a new thread into the application for a relatively minor reason. Thinking in terms of mobile applications often means re-considering choices that you might make differently for a desktop application with relatively richer resources at its disposal. We would like to find a more efficient way of updating that clock.

The Application: The rest of the story of porting the application will be detailed in future blog entries, but if you are interested in the application in question and the construction of it, you can read about it in a not-so-recent Developer.com article about using Matisse (a GUI builder for Swing). The original application is a Java Swing and SE application. It is like a stopwatch with a lap timer that we use when recording podcasts; when you start the recording, you start the stopwatch. Then for every mistake that someone makes, you hit the flub button. At the end you can save out the bookmarked mistakes which can be loaded into the wonderful Audacity audio editor as a labels track. You can then see where all of the mistakes are in the recording and edit them out.

The article describing it is: http://www.developer.com/java/ent/print.php/3589961

In the original version, the timer code looked like this:

class UpdateTimeTask extends TimerTask {
   public void run() {
       long millis = System.currentTimeMillis() - startTime;
       int seconds = (int) (millis / 1000);
       int minutes = seconds / 60;
       seconds     = seconds % 60;

       timeLabel.setText(String.format("%d:%02d", minutes, seconds));
   }
}

And in the event listener to start this update, the following Timer() instance is used:

if(startTime == 0L) {
   startTime = evt.getWhen();
   timer = new Timer();
   timer.schedule(new UpdateTimeTask(), 100, 200);
}

In particular, note the 100, 200 parameters. The first parameter means wait 100 ms before running the clock update task the first time. The second means repeat every 200ms after that, until stopped. 200 ms should not be too noticeable if the second resolution happens to fall close to or on the update. If the resolution was a second, you could find the clock sometimes not updating for close to 2 seconds, or possibly skipping a second in the counting, it would look odd).

When I ported the application to use the Android SDKs, this code actually compiled in Eclipse, but failed with a runtime error because the Timer() class was not available at runtime (fortunately, this was easy to figure out from the error messages). On a related note, the String.format method was also not available, so the eventual solution uses a quick hack to format the seconds nicely as you will see.

Fortunately, the role of Timer can be replaced by the android.os.Handler class, with a few tweaks. To set it up from an event listener:

private Handler mHandler = new Handler();

...

OnClickListener mStartListener = new OnClickListener() {
   public void onClick(View v) {
       if (mStartTime == 0L) {
            mStartTime = System.currentTimeMillis();
            mHandler.removeCallbacks(mUpdateTimeTask);
            mHandler.postDelayed(mUpdateTimeTask, 100);
       }
   }
};

A couple of things to take note of here. First, the event doesn't have a .getWhen() method on it, which we handily used to set the start time for the timer. Instead, we grab the System.currentTimeMillis(). Also, the Handler.postDelayed() method only takes one time parameter, it doesn't have a "repeating" field. In this case we are saying to the Handler "call mUpdateTimeTask() after 100ms", a sort of fire and forget one time shot. We also remove any existing callbacks to the handler before adding the new handler, to make absolutely sure we don't get more callback events than we want.

But we want it to repeat, until we tell it to stop. To do this, just put another postDelayed at the tail of the mUpdateTimeTask run() method. Note also that Handler requires an implementation of Runnable, so we change mUpdateTimeTask to implement that rather than extending TimerTask. The new clock updater, with all these changes, looks like this:

private Runnable mUpdateTimeTask = new Runnable() {
   public void run() {
       final long start = mStartTime;
       long millis = SystemClock.uptimeMillis() - start;
       int seconds = (int) (millis / 1000);
       int minutes = seconds / 60;
       seconds     = seconds % 60;

       if (seconds < 10) {
           mTimeLabel.setText("" + minutes + ":0" + seconds);
       } else {
           mTimeLabel.setText("" + minutes + ":" + seconds);            
       }
     
       mHandler.postAtTime(this,
               start + (((minutes * 60) + seconds + 1) * 1000));
   }
};

and can be defined as a class member field.

The if statement is just a way to make sure the label is set to 10:06 instead of 10:6 when the seconds modulo 60 are less than 10 (hopefully String.format() will eventually be available). At the end of the clock update, the task sets up another call to itself from the Handler, but instead of a hand-wavy 200ms before the update, we can schedule it to happen at a particular wall-clock time — the line: start + (((minutes * 60) + seconds + 1) * 1000) does this.

All we need now is a way to stop the timer when the stop button is pressed. Another button listener defined like this:

OnClickListener mStopListener = new OnClickListener() {
   public void onClick(View v) {
       mHandler.removeCallbacks(mUpdateTimeTask);
   }
};

will make sure that the next callback is removed when the stop button is pressed, thus interrupting the tail iteration.

Handler is actually a better choice than Timer for another reason too. The Handler runs the update code as a part of your main thread, avoiding the overhead of a second thread and also making for easy access to the View hierarchy used for the user interface. Just remember to keep such tasks small and light to avoid slowing down the user experience.

So that's it for the first of what will be a series of Android tips. Hopefully this will save you a little head scratching on what will probably be a fairly common thing to want to do (i.e. make something happen or update at regular intervals in a lightweight way in your application). There is plenty of more material from my experience of porting this very simple application which will be covered in some of the future "tips" articles. There are some other great tips being discussed as well as an opportunity ask questions at the Android Developers Discussion Group.