ROME has been designed around a plugin mechanism. All the supported feed types (RSSs and Atom) is done by plugins included in the distribution.
Parsing feeds, generating feeds, converting feeds from a concrete feed to a SyndFeed and vice versa, parsing modules and generating modules is done using plugins.
Plugins for new functionality can be added and default plugins can be easily replaced with alternate plugins.
Plugins are defined in a properties file, the rome.properties file.
The default plugins definition file is included in the ROME JAR file, com/sun/syndication/rome.properties, this is the first plugins definition file to be processed. It defines the default parsers, generators and converters for feeds and modules ROME provides.
After loading the default plugins definition file, ROME looks for additional plugins definition files in all the CLASSPATH entries, this time at root level, /rome.properties. And appends the plugins definitions to the existing ones. Note that if there are several /rome.properties files in the different CLASSPATH entries all of them are processed. The order of processing depends on how the ClassLoader processes the CLASSPATH entries, this is normally done in the order of appearance -of the entry- in the CLASSPATH.
For each type of plugin (parser, generator, converter, ect) a list of available plugins is built following the read order just described. The plugins classes are then loaded and instantiated. All plugins have some kind of primary key. In the case or parsers, generators and converters the primary key is the type of feed they handle. In the case of modules, the primary key is the module URI. If a plugin list definition (the aggregation of all the plugins of the same time from all the rome.properties) contains more than one plugin with the same primary key, the latter one is the one that will be used(this enables replacing default plugins with custom ones).
The plugins are read, loaded and managed by the implementation class com.rometools.rome.io.impl.PluginManager. This class is an abstract class and it is extended to provide support for each type of plugin.
Parser plugins are managed by the com.rometools.rome.io.impl.FeedParsers class (subclass of the PluginManager). This plugin manager looks for the WireFeedParser.classes property in all the rome.properties files. The fully qualified names of the parser classes must be separated by whitespaces or commas. For example, the default rome.properties file parser plugins definition is as follows:
# Feed Parser implementation classes
#
WireFeedParser.classes=com.rometools.rome.io.impl.RSS090Parser \
com.rometools.rome.io.impl.RSS091NetscapeParser \
com.rometools.rome.io.impl.RSS091UserlandParser \
com.rometools.rome.io.impl.RSS092Parser \
com.rometools.rome.io.impl.RSS093Parser \
com.rometools.rome.io.impl.RSS094Parser \
com.rometools.rome.io.impl.RSS10Parser \
com.rometools.rome.io.impl.RSS20wNSParser \
com.rometools.rome.io.impl.RSS20Parser \
com.rometools.rome.io.impl.Atom03Parser
All the classes defined in this property have to implement the com.rometools.rome.io.WireFeedParser interface. Parser instances must be thread safe. The return value of the getType() method is used as the primary key. If more than one parser returns the same type, the latter one prevails.
Generator plugins are managed by the com.rometools.rome.io.impl.FeedGenerators class (subclass of the PluginManager). This plugin manager looks for the WireFeedGenerator.classes property in all the rome.properties files. The fully qualified names of the generator classes must be separated by whitespaces or commas. For example, the default rome.properties file generator plugins definition is as follows:
# Feed Generator implementation classes
#
WireFeedGenerator.classes=com.rometools.rome.io.impl.RSS090Generator \
com.rometools.rome.io.impl.RSS091NetscapeGenerator \
com.rometools.rome.io.impl.RSS091UserlandGenerator \
com.rometools.rome.io.impl.RSS092Generator \
com.rometools.rome.io.impl.RSS093Generator \
com.rometools.rome.io.impl.RSS094Generator \
com.rometools.rome.io.impl.RSS10Generator \
com.rometools.rome.io.impl.RSS20Generator \
com.rometools.rome.io.impl.Atom03Generator
All the classes defined in this property have to implement the com.rometools.rome.io.WireFeedGenerator interface. Generator instances must be thread safe. The return value of the getType() method is used as the primary key. If more than one generator returns the same type, the latter one prevails.
Converter plugins are managed by the com.rometools.rome.synd.impl.Converters class (subclass of the PluginManager). This plugin manager looks for the Converter.classes property in all the rome.properties files. The fully qualified names of the converter classes must be separated by whitespaces or commas. For example, the default rome.properties file converter plugins definition is as follows:
# Feed Conversor implementation classes
#
Converter.classes=com.rometools.rome.feed.synd.impl.ConverterForAtom03 \
com.rometools.rome.feed.synd.impl.ConverterForRSS090 \
com.rometools.rome.feed.synd.impl.ConverterForRSS091Netscape \
com.rometools.rome.feed.synd.impl.ConverterForRSS091Userland \
com.rometools.rome.feed.synd.impl.ConverterForRSS092 \
com.rometools.rome.feed.synd.impl.ConverterForRSS093 \
com.rometools.rome.feed.synd.impl.ConverterForRSS094 \
com.rometools.rome.feed.synd.impl.ConverterForRSS10 \
com.rometools.rome.feed.synd.impl.ConverterForRSS20
All the classes defined in this property have to implement the com.rometools.rome.synd.Converter interface. Converter instances must be thread safe. The return value of the getType() method is used as the primary key. If more than one converter returns the same type, the latter one prevails.
There are 2 types of module plugins, module parser plugins and module generator plugins. They use a same pattern feed parsers and generators use.
The main difference is that support for module plugins has to be wired in the feed parser and generator plugins. The default feed parser and generator plugins supporting module plugins are: RSS 1.0, RSS 2.0 and Atom 0.3.
It is important to understand that this wiring is for modules support. Once a feed parser or generator has modules support, new modules can be used just by adding them to right property in the rome.properties file. No code changes are required.
Module parsers and generators are defined at feed and item level. This allow selective handling of modules, for example handling Syndication module at feed level only.
Module parser plugins are managed by the com.rometools.rome.io.impl.ModuleParsers class (subclass of the PluginManager). This plugin manager looks for the .feed.ModuleParser.classes and the .item.ModuleParser.classes properties in all the rome.properties files. must be the type defined by the parser (ie: rss_1.0, atom_0.3). The fully qualified names of the module parser classes must be separated by whitespaces or commas. For example, the default rome.properties file modules parser plugins definition is as follows:
# Parsers for Atom 0.3 feed modules
#
atom_0.3.feed.ModuleParser.classes=com.rometools.rome.io.impl.SyModuleParser \
com.rometools.rome.io.impl.DCModuleParser
# Parsers for Atom 0.3 entry modules
#
atom_0.3.item.ModuleParser.classes=com.rometools.rome.io.impl.DCModuleParser
# Parsers for RSS 1.0 feed modules
#
rss_1.0.feed.ModuleParser.classes=com.rometools.rome.io.impl.SyModuleParser \
com.rometools.rome.io.impl.DCModuleParser
# Parsers for RSS 1.0 item modules
#
rss_1.0.item.ModuleParser.classes=com.rometools.rome.io.impl.DCModuleParser
# Parsers for RSS 2.0 feed modules
#
rss_2.0.feed.ModuleParser.classes=
# Parsers for RSS 2.0 item modules
#
rss_2.0.item.ModuleParser.classes=
All the classes defined in this property have to implement the com.rometools.rome.io.ModuleParser interface. ModuleParser instances must be thread safe. The return value of the getNamesapceUri() method is used as the primary key. If more than one module parser returns the same URI, the latter one prevails.
Module generator plugins are managed by the com.rometools.rome.io.impl.GeneratorParsers class (subclass of the PluginManager). This plugin manager looks for the .feed.ModuleGenerator.classes and the .item.ModuleGenerator.classes properties in all the rome.properties files. must be the type defined by the generator (ie: rss_1.0, atom_0.3). The fully qualified names of the module generator classes must be separated by whitespaces or commas. For example, the default rome.properties file modules generator plugins definition is as follows:
# Generators for Atom 0.3 feed modules
#
atom_0.3.feed.ModuleGenerator.classes=com.rometools.rome.io.impl.SyModuleGenerator \
com.rometools.rome.io.impl.DCModuleGenerator
# Generators for Atom 0.3 entry modules
#
atom_0.3.item.ModuleGenerator.classes=com.rometools.rome.io.impl.DCModuleGenerator
# Generators for RSS 1.0 feed modules
#
rss_1.0.feed.ModuleGenerator.classes=com.rometools.rome.io.impl.SyModuleGenerator \
com.rometools.rome.io.impl.DCModuleGenerator
# Generators for RSS_1.0 entry modules
#
rss_1.0.item.ModuleGenerator.classes=com.rometools.rome.io.impl.DCModuleGenerator
# Generators for RSS 2.0 feed modules
#
rss_2.0.feed.ModuleGenerator.classes=
# Generators for RSS_2.0 entry modules
#
rss_2.0.item.ModuleGenerator.classes=
All the classes defined in this property have to implement the com.rometools.rome.io.ModuleGenerator interface. ModuleGenerator instances must be thread safe. The return value of the getNamesapceUri() method is used as the primary key. If more than one module generator returns the same URI, the latter one prevails.
See also: a step-by-step tutorial for implementing a custom module.