Custom Modules with ROME

I have been looking at ROME lately. ROME is a very popular open-source Java based RSS/Atom Feed parsing and generation library, originally developed by a group of Sun developers. I originally looked at ROME as a way to parse external feeds. Although the feeds were either in RSS or Atom, there are various versions of both RSS and Atom, which are quite different from each other in subtle ways. ROME abstracts away all the differences, allowing you to treat them as high level Java objects. ROME uses JDOM, my favorite XML parsing library, to do the parsing and building of XML behind the scenes.

My first application using ROME was to parse and aggregate a bunch of external feeds, and was ridiculously simple, about half a page of Java code. As Mark Woodman says in his article "Rome in a Day: Parse and Publish Feeds in Java" on XML.com, the sheer variety of RSS and Atom flavors are enough to make a grown programmer cry. However, the way in which ROME abstracts away all these variations and the simplicity of my resulting code almost made me cry... tears of joy.

However, given that most of the "smarts" of the application would be in the selection of the feeds themselves, and since that required domain expertise I did not have, I decided to put that project aside for a while and explore the other part of ROME, trying to use it to build a feed instead. In any case, in retrospect, I would probably be looking at using the rome-fetcher subproject instead to build the aggregator, since that already provides code to build "well-behaved" feed fetchers.

The feed I choose to rebuild was an existing RSS 2.0 feed. It was generated using JSP XML templates powered by Java services. As such, there were many custom extensions built in, which were not part of any of the standard modules that ROME uses. So I basically had to build a custom extension module for ROME to support the custom tags that this feed used. This post describes the (pretty simple) process.

I could not find any place where this process was described in sufficient newbie detail for me, so after quickly looking through the RSS/Atom/ROME books on Amazon, I settled on "RSS and Atom in Action" (RAIA) by Dave Johnson. One reason for my choice was that it was published by Manning and they provide downloadable PDF versions free with their printed book, so I got my book about 15 minutes after I ordered from my home computer. As it turned out, I was done reading the PDF version by the time the print edition arrived about 5 days later. The print version sits unopened on my desk for now, but I am sure I will need it some day.

But enough idle chatter. Lets get right down to building a custom module that supports three of my custom tags, called my:tag, my:tagDate and my:isTagged respectively. The first is a String, the second a Date and the third a Boolean.

Each module has four components that needs to be built and hooked up with ROME. An interface that describes the URI for the namespace in which the custom tags will live and the getters and setters for each custom tag supported, an implementation of that interface, a parser and a generator. They are shown below:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

// MyModule.java package com.mycompany.feeds.modules.mymodule; import java.util.Date; import com.sun.syndication.feed.module.Module; public interface MyModule extends Module { public static final String URI = "http://www.my.com/spec"; public String getTag(); public void setTag(String tag); public Date getTagDate(); public void setTagDate(Date tagDate); public Boolean getIsTagged(); public void setIsTagged(Boolean isTagged); }

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57

// MyModuleImpl.java package com.mycompany.feeds.modules.mymodule; import java.util.Date; import com.sun.syndication.feed.module.ModuleImpl; public class MyModuleImpl extends ModuleImpl implements MyModule { private static final long serialVersionUID = -8275118704842545845L; private Boolean isTagged; private Date tagDate; private String tag; // boilerplate code. Eclipse will generate all but the constructor but // will keep reporting an error until you do it. public MyModuleImpl() { super(MyModule.class, MyModule.URI); } public void copyFrom(Object obj) { MyModule module = (MyModule) obj; setTag(module.getTag()); setTagDate(module.getTagDate()); setIsTagged(module.getIsTagged()); } public Class getInterface() { return MyModule.class; } // getter and setter impls for MyModule interface public Boolean getIsTagged() { return isTagged; } public String getTag() { return tag; } public Date getTagDate() { return tagDate; } public void setIsTagged(Boolean isTagged) { this.isTagged = isTagged; } public void setTag(String tag) { this.tag = tag; } public void setTagDate(Date tagDate) { this.tagDate = tagDate; } }

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55

// MyModuleGenerator.java package com.mycompany.feeds.modules.mymodule; import java.text.SimpleDateFormat; import java.util.Collections; import java.util.HashSet; import java.util.Set; import org.jdom.Element; import org.jdom.Namespace; import com.sun.syndication.feed.module.Module; import com.sun.syndication.io.ModuleGenerator; public class MyModuleGenerator implements ModuleGenerator { // boilerplate code private static final Namespace NAMESPACE = Namespace.getNamespace("my", MyModule.URI); private static final Set NAMESPACES; static { Set<Namespace> namespaces = new HashSet<Namespace>(); namespaces.add(NAMESPACE); NAMESPACES = Collections.unmodifiableSet(namespaces); } public String getNamespaceUri() { return MyModule.URI; } public Set getNamespaces() { return NAMESPACES; } // Implements the module generation logic private final SimpleDateFormat dateFormat = new SimpleDateFormat("MM/dd/yyyy"); public void generate(Module module, Element element) { MyModule myModule = (MyModule) module; if (myModule.getTag() != null) { Element myElement = new Element("tag", NAMESPACE); myElement.setText(myModule.getTag()); element.addContent(myElement); } if (myModule.getTagDate() != null) { Element myElement = new Element("tagDate", NAMESPACE); myElement.setText(dateFormat.format(myModule.getTagDate())); element.addContent(myElement); } if (myModule.getIsTagged() != null) { Element myElement = new Element("isTagged", NAMESPACE); myElement.setText(String.valueOf(myModule.getIsTagged())); element.addContent(myElement); } } }

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43

// MyModuleParser.java package com.mycompany.feeds.modules.mymodule; import java.text.ParseException; import java.text.SimpleDateFormat; import org.jdom.Element; import org.jdom.Namespace; import com.sun.syndication.feed.module.Module; import com.sun.syndication.io.ModuleParser; public class MyModuleParser implements ModuleParser { // boilerplate public String getNamespaceUri() { return MyModule.URI; } // implements the parsing for MyModule private final SimpleDateFormat dateFormat = new SimpleDateFormat("MM/dd/yyyy"); public Module parse(Element element) { Namespace myNamespace = Namespace.getNamespace(MyModule.URI); MyModule myModule = new MyModuleImpl(); if (element.getNamespace().equals(myNamespace)) { if (element.getName().equals("tag")) { myModule.setTag(element.getTextTrim()); } if (element.getName().equals("tagDate")) { try { myModule.setTagDate(dateFormat.parse(element.getTextTrim())); } catch (ParseException e) { // don't set it if bad date format } } if (element.getName().equals("isTagged")) { myModule.setIsTagged(Boolean.valueOf(element.getTextTrim())); } } return myModule; } }

To let ROME know that these modules should be used, we need to create a rome.properties file in our classpath. The ROME JAR file already has rome.properties files within it that controls its default configuration, and it will read our rome.properties in addition to its own configuration. Our three tags are all item level tags, so we will need to only map the parsers to the item level. The RAIA book shows you how to map feed level modules as well, but the process is quite similar. Here is my rome.properties file (it would be located in src/main/resources in a Maven2 project). I am building an RSS 2.0 feed, so I map it to that dialect here.

1 2 3 4 5 6

# rome.properties rss_2.0.item.ModuleParser.classes=\ com.mycompany.feeds.modules.mymodule.MyModuleParser rss_2.0.item.ModuleGenerator.classes=\ com.mycompany.feeds.modules.mymodule.MyModuleGenerator

Finally, here is how I would call it from within my code:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27

@Test public void testFeedWithMyModule() throws Exception { // create the feed object SyndFeed feed = new SyndFeedImpl(); feed.setFeedType("rss_2.0"); feed.setTitle("My test feed"); ... // add the MyModule namespace to the feed feed.getModules().add(new MyModuleImpl()); // create the item SyndEntry entry = new SyndEntryImpl(); ... // create the module, populate and add to the item MyModule myModule = new MyModuleImpl(); myModule.setTag("tagValue"); myModule.setTagDate(new Date()); myModule.setIsTagged(true); entry.getModules().add(myModule); ... // add entry(s) to the feed feed.getEntries().add(entry); // print it out WireFeedOutput output = new WireFeedOutput(); WireFeed wireFeed = feed.createWireFeed("rss_2.0"); log.debug(output.outputString(wireFeed)); }

As you can see, adding custom modules to ROME is a bit involved, but its really quite simple. Before I started on these two projects, I did not know much about all the various flavors of ROME and about these custom extensions. In fact, this is the first time I have used Namespaces in JDOM. However, Dave Johnson's book provides a lot of background information and a lot of nice examples in Java and C#. I would highly recommend it to anyone who needs to get up to speed quickly with ROME and RSS/Atom. Another very informative article is the article "ROME: Escape syndication hell, a Java developer's perspective" written by two of the original developers of ROME.