« Hey, I wrote that | Main | Sealing deals faster... »

How Rome works.

I spent some time exploring the new Rome feed parser for Java and trying to understand how it works. Along the way, I put together the following class diagram and notes on the parsing process. I provide some pointers into the Rome 0.3 Javadocs, but, because this summary is based on the latest Rome codebase from CVS you will notice that some class and interface names have changed.

You don't need to know this stuff to use Rome, but it you are interested in internals you might find it interesting.

Notes on the Rome parsing process

Rome is based around an idealized and abstract model of a Newsfeed or "Syndication Feed." Rome can parse any format of Newsfeed, including RSS variants and Atom, into this model. Rome can convert from model representation to any of the same Newfeed output formats.

Internally, Rome defines intermediate object models for specific Newsfeed formats, or "Wire Feed" formats, including both Atom and all RSS variants. For each format, there is a separate JDOM based parser class that parses XML into an intermediate model. Rome provides "converters" to convert between the intermediate Wire Feed models and the idealized Syndication Feed model.

Rome makes no attempt at Pilgrim-style liberal XML parsing. If a Newsfeed is not valid XML, then Rome will fail. Perhaps, as Kevin Burton suggests, parsing errors in Newsfeeds can and should be corrected. Kevin suggests that, when the parse fails, you can correct the problem and parse again. (BTW, I have some sample code that shows how to do this, but it only works with Xerces - Crimsom's SAXParserException does not have reliable error line and column numbers.)

Here is what happens during Rome Newsfeed parsing:

<img src="http://rollerweblogger.org/resources/roller/HowRomeWorks.png" alt="diagram of Rome classes and the parsing process." style="align:center" />
  1. Your code calls SyndFeedInput to parse a Newsfeed, for example (see also Using Rome to read a syndication feed):
  2. URL feedUrl = new URL("file:blogging-roller.rss");
    SyndFeedInput input = new SyndFeedInput();
    SyndFeed feed = input.build(new InputStreamReader(feedUrl.openStream()));
    
  3. SyndFeedInput delegates to WireFeedInput to do the actual parsing.
  4. WireFeedInput uses a PluginManager of class FeedParsers to pick the right parser to use to parse the feed and then calls that parser to parse the Newsfeed.
  5. The appropriate parser parses the Newsfeed parses the feed, using JDom, into a WireFeed. If the Newsfeed is in an RSS format, the the WireFeed is of class Channel and contains Items, Clouds, and other RSS things from the com.sun.syndication.feed.rss package. Or, on the other hand, if the Newsfeed is in Atom format, then the WireFeed is of class Feed from the com.sun.syndication.atom package. In the end, WireFeedInput returns a WireFeed.
  6. SyndFeedInput uses the returned WireFeedInput to create a SyndFeedImpl. Which implements SyndFeed. SyndFeed is an interface, the root of an abstraction that represents a format independent Newsfeed.
  7. SyndFeedImpl uses a Converter to convert between the format specific WireFeed representation and a format-independent SyndFeed.
  8. SyndFeedInput returns to you a SyndFeed containing the parsed Newsfeed.
Other Rome features

Rome supports Newsfeed extension modules for all formats that also support modules: RSS 1.0, RSS 2.0, and Atom. Standard modules such as Dublic Core and Syndication are supported and you can define your own custom modules too.

Rome also supports Newsfeed output and for each Newsfeed format provides a "generator" class that can take a Syndication Feed model and produce from it Newsfeed XML.

Learning more

I've linked to a number of the Rome 0.3 Tutorials, here is the full list from the Rome Wiki:

  1. Using Rome to read a syndication feed
  2. Using Rome to convert a syndication feed from one type to another
  3. Using Rome to aggregate many syndication feeds into a single one
  4. Using Rome to create and write a feed
  5. Defining a Custom Module bean, parser and generator
Conclusion

Overall, Rome looks really good. It is obvious that a lot of thought has gone into design and a lot of work has been done on implementation (and docs). Rome is well on the way to "ending syndication feed confusion by supporting all of 'em" for us Java heads.

Please leave a comment if I have gotten something wrong.

Comments:

One other advantage of Pilgrim's Universal Feed Parser is that it doesn't have one parser per feed format, it has a single parser that understands every format at once: so it catches the (apparently quite common) cases where a feed is declared as one format, but contains elements from another. I'm tempted to see if Javablogs would benefit from using Rome, though. Maybe after we get the next Confluence point release out, I'll have enough time to play with it properly.

Posted by Charles Miller on August 09, 2004 at 10:10 AM EDT #

Dave, since you've begun working on Atom4J do you see any advantage to replacing Atom4J's parsing with Rome? They focus on two seperate parts of Atom (API vs Syndication) but Atom4J has to support input & output of the same elements... Just a thought.

Posted by Lance Lavandowska on August 09, 2004 at 12:33 PM EDT #

Rome also has a Fetcher subproject, that support conditional get, etc. See http://wiki.java.net/bin/view/Javawsxml/RomeFetcherTutorial

Posted by Nick Lothian on August 09, 2004 at 01:56 PM EDT #

What tool did you use to create your class diagram?

Posted by Paul Kilroy on August 09, 2004 at 05:02 PM EDT #

Paul, I think DJ used OmniGraffe that comes with Mac OS X. Makes diagrams like this very simple.

Posted by 216.54.164.11 on August 10, 2004 at 04:47 PM EDT #

Yes that is correct, I used OmniGraffle.

Posted by Dave Johnson on August 10, 2004 at 05:24 PM EDT #

Post a Comment:
  • HTML Syntax: NOT allowed

« Hey, I wrote that | Main | Sealing deals faster... »

Welcome

This is just one entry in the weblog Blogging Roller. You may want to visit the main page of the weblog

Related entries

Below are the most recent entries in the category Blogging, some may be related to this entry.