Introduction
Welcome to our first tutorial! This tutorial assumes that you are familiar with the official tutorial supplied by Google. If you have not run through that I would highly recommend it!

The syntax highlighting in these tutorials will create hyperlinks to the documentation out of general Java and Android specific classes. So when you see a class like "Activity" in the code you can click on it and be taken to the documentation for that class. Also, the line numbers next to the code correspond to the line numbers in the java files.

In this tutorial we will build a simple RSS reader called "NewsDroid" so that you can get all the headlines without having to hit all your favorite sites in that little browser. The application will open with a list of all of the RSS feeds that you have added, and when a user clicks on a feed then it will display a list of the headlines for that feed. When a user then selects a headline they will be taken directly to that story in the web browser.

This application consists of 7 classes:

• Simple storage classes:
  • Article - Simple class to hold the values of an article, ie the the title and url
  • Feed - Simple class to hold the values of a feed, ie the title of the feed and url to the XML file
• Backend Classes:
  • NewsDroidDB - Handles all the SQL Lite database work
  • RSSHandler - Parses RSS feed and saves what we need from them
• Frontend Classes:
  • ArticlesList - ListActivity that displays the Articles
  • FeedsList - ListActivity that displays the Feeds
  • URLEditor - Activity that allows the user to enter the URL for the feed

You may want to download the complete source for reference as you view this tutorial.

On page 2 we discuss the database backend components.
On page 3 we discuss the RSS Parsing using a SAX object.
On page 4 we put it all together with a couple ListActivities and a URL Entry Box

NewsDroid Backend

Our first task will be to create the NewsDroidDB class. This class will be responsible for creating the database and inserting or deleting records. Before we create the NewsDroidDB we need to design the layout of the database:

For each RSS Feed we need the the title of the feed and the URL for the xml file so that we can fetch the articles. In addition we will want a unique id for each feed so that we can have an articles table that relates to the feeds table. So to create our table "feeds" we will run a create statement as follows:

create table feeds (feed_id integer primary key autoincrement, title text not null, url text not null);

And for the articles we need to store the feed_id so that we know what feed the article is for. We also need the title of the article and the url to the article:

create table articles (article_id integer primary key autoincrement, feed_id int not null, title text not null, url text not null);

Now that we know the layout of our tables we can start working on our NewsDroidDB class. Here are the list of things this class will need to accomplish:

• Create Tables - We will need to be able to create tables for the feeds and articles if they don't exist, this will be handled in the constructor.
• Insert Data - Will need to be able to insert a feed or an article.
• Delete Data - If we can insert we need to be able to delete right?
• Get Data - We need to be able to pull the data to display in our ListActivities

We'll tackle these tasks in order. Here is the NewsDroidDB class declaration and the constructor:

Here we declare the class and some of the variables that we will be using for database access, including the create statements, table names, database name, and database version. The constructor takes the context as the argument so that it can initialize the SQLiteDatabase object "db".

On line 33 it will attempt to connect to the database, if the database does not exists it will throw the FileNotFoundException and we will create the database and the tables in the database on lines 36-39.

Now we need functions for inserting feeds and deleting feeds:

Both of these functions are boolean and return true if the task was sucessful. As you can see using a ContentValues object and a SQLiteDatabase object it is very easy to do these basic operations.

Here are 2 very similar functions for dealing with articles:

Now we must create functions to return the data, and to help us do this we will create 2 classes mentioned in the introduction Articles and Feeds. These just objects that store all of our values and will be very similar to the layout of the tables. Here are their declarations:

Now that we have these storage objects we can create a function that will return a List object for each of these. First we will look at the getFeeds() function:

This function returns a List of Feed objects. This list will be used to populate the FeedsList ListActivity, as we will see later. The first step is to query the table using the SQLiteDatabase.query function. Because we just want all of the records from the feeds table this is easy. The query will return a Cursor object which we can loop through and create a new Feed object. As we loop through we add each new feed to the ArrayList feeds via the feeds.add(feed) on line 82.

Here is the function to get the list of articles for a specific feed:

As you can see this function is almost identical to to the getFeeds function except that it takes in an argument "feedId" and uses this argument in the query function on line 96. The 3rd argument in the db.query function is the "WHERE" argument (minus the "WHERE"), and here we specify "feed_id=X", where X is the feedId passed into the function.

This is all we need for the NewDroidDB class. We can now move on to parsing the RSS document and getting the data into the database...

NewsDroid RSS Parsing

Now it is our goal to download an RSS xml file and get what we need out of it. To do this we will use "Simple API for XML", or SAX. This library is included in the Android SDK and is great for parsing XML data. Before we get started figuring out a parser, lets take a look at the format of an RSS feed:

Seems pretty simple right? It better, considering it's really simple syndication! So, lets figure out what we want to pull out of this, and when. If the user is adding a new feed, he or she will supply the URL and then we need to go out and figure out the title of this feed before we can add it to the database. That would be found in the "title" element on line 4, in this case "Hello Android - Android OS news, tutorials, downloads". So once a feed is added and the users selects a feed on the feeds list we need to grab all of the headlines for the articles table, and the url direct link to the article. This is the "title" element and "link" element found in each "item" element. In this example it is lines 9 and 10.

So, to do this we will now create a class "RSSHandler" and extend org.xml.sax.helpers.DefaultHandler. For this class I'm just going to show you the complete class and will explain what's happening below:

So what is going on here you ask?? Lets look the body of the createFeed() function:

First we set the targetFlag so that the rest of the functions know what our target is from the XML file, we are looking specifically for a feed. Next we initialize our droidDB object so that once we get everything we need from the XML we can stick it in the database. After that we set what we know in our currentFeed object (the url the user input). We will update the currentFeed object or currentArticle object as we find out more from the XML file. For the feed object we just need to find its title. For the articles we need the title and the url from the XML.

Now things get SAX specific. We create a SAXParserFactory so we can create a SAXParser so we can create a XMLReader! Anyways, lines 120 and 121 are where we kick this off. We set this class as our ContentHandler and we pass in the xml stream to the XMLReader using the supplied url. At this point the parsing begins.

Now we have 3 functions working to parse this document, it starts at the beginning of the document and calls each of these 3 functions as it moves through the document:

• startElement - This function is called when the parser reaches an element
• endElement - This function is called when the parser reaches the end of an element
• characters - This is called when we are between the start and end

To illustrate this using a simple xml tag: <ele>chars</ele>

All 3 funtions would be called to parse this string. First startElement() would be called passing in "ele" for the second argument. Then characters() would be called passing in an array of characters "chars". Then endElement() would be called passing in "ele" for the second argument.

So what we can do to parse this XML file is to setup 3 boolean variables starting at line 23. These variables are inItem, inTitle, and inLink. Now, when startElement() is called we can set these values to true if we are entering into one of the 3 elements "item", "title" or "link". We also set these to false when leaving these elements in endElement(). So now when characters() is called we know where we are at and can update the values in currentArticle and currentFeed, you can see this happening at line 96.

Eventually all the fields of currentArticle or currentFeed will be set and it will be time to insert it into the database. We can check this in endElement(), and that can be seen on line 66 and line 75. After we insert a feed we can throw a SAXException to stop parsing, or after we collect enough articles we can stop parsing.

Now we can parse the XML files, handle the database stuff so lets show it to the user now! We'll build the UI on the next page...

User Interface

The user interface for this application is made up of 3 different Activities. The first activity the user comes to, FeedsList, is a simple list activity that displays all of the feeds the user has added, and gives the option to add more feeds or delete the selected feed. The layout of these Activities are very similar to that in Google's Notepad tutorial, so the complete code will not be included in this page. Instead we will highlight a couple of important points.

An important function to look at is the onListItemClick() function for this class:

This code is executed when the user clicks on a feed. The job of this function is to bring up the ArticleList Activity showing the headlines for the selected feed. The information is passed by adding all of the information to describe a feed to the Intent and then starting the Activity. If we look at the constructor for the ArticlesList Activity we can see how this is used:

When the ArticlesList Activity is created we need to define the values of the private feed object. There are 2 ways that this info could be coming in, either because the Activity was paused or even killed, or because it's being called for the first time via an Intent from FeedsList. When it's called for the first time then we will check the extras from the intent. This is what's happening starting at line 37. If it's being called for the first time we also need to delete all the articles currently in the database and update the table with the new articles from the XML file.

If it is being resumed then we will get the data from the icicle, and we will use the same data that was in there before. To make sure that information is in the icicle we must implement the onFreeze() function as follows:

When a user clicks on a headline we need to launch the browser, it is very simple to create an intent to launch a browser, and we will do this in OnListItemClick():

The final Activity is the URLEditor shown above, this is the screen where the user inputs the URL to the RSS feed. This is a simple activity, here is the source:

There are 2 buttons that must be handeld, and we do that with nested functions in the onCreate() function. When the "OK" button is clicked we call the okClicked() function. This function will create a feed by calling RSSHandler.createFeed() passing in the text from the input field. We also must handle the Activity lifecycle, and save whatever is in the text box so that if this activity is interupted the partial URL will remain in the box when it's resumed.

As you can see the UI is very basic, but could easily be extended to look much slicker. Hopefully you have enjoyed our first tutorial, and hopefully we will be able to get some more your way.