PatchesAndForks/rome
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #1 from imk/master

Browse source 
maven site and config
This commit is contained in:
Patrick Gotthard 2013-09-30 08:28:31 -07:00
commit c60af3f14c
157 changed files with 10649 additions and 16 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
.gitignore vendored Normal file
View file

@ -0,0 +1,4 @@
/target
/.classpath
/.project
/.settings

6
README.md Normal file
View file

@ -0,0 +1,6 @@
rome
====
ROME is a set of RSS and Atom Utilities for Java. It makes it easy to work in Java with most syndication formats: RSS 0.90, RSS 0.91 Netscape, RSS 0.91 Userland, RSS 0.92, RSS 0.93, RSS 0.94, RSS 1.0, RSS 2.0, Atom 0.3, Atom 1.0
More Information: http://rometools.github.io/rome/

85
pom.xml
View file

@ -15,9 +15,9 @@
SyndFeed object that lets you work on with the data without bothering about the SyndFeed object that lets you work on with the data without bothering about the
underlying format. underlying format.
</description> </description>
<url>https://rome.dev.java.net/</url> <url>http://rometools.github.io/rome/</url>
<issueManagement> <issueManagement>
<url>https://rometools.jira.com/browse/ROME#selectedTab=com.atlassian.jira.plugin.system.project%3Aissues-panel</url> <url>https://github.com/rometools/rome/issues</url>
</issueManagement> </issueManagement>
<ciManagement> <ciManagement>
<notifiers> <notifiers>
@ -32,15 +32,9 @@
<mailingLists> <mailingLists>
<mailingList> <mailingList>
<name>dev@rome.dev.java.net</name> <name>dev@rome.dev.java.net</name>
<subscribe> <subscribe>https://rome.dev.java.net/servlets/ProjectMailingListList</subscribe>
https://rome.dev.java.net/servlets/ProjectMailingListList <unsubscribe>https://rome.dev.java.net/servlets/ProjectMailingListList</unsubscribe>
</subscribe> <archive>https://rome.dev.java.net/servlets/SummarizeList?listName=dev</archive>
<unsubscribe>
https://rome.dev.java.net/servlets/ProjectMailingListList
</unsubscribe>
<archive>
https://rome.dev.java.net/servlets/SummarizeList?listName=dev
</archive>
</mailingList> </mailingList>
</mailingLists> </mailingLists>
<developers> <developers>
@ -66,9 +60,9 @@
</developer> </developer>
</developers> </developers>
<scm> <scm>
<connection>scm:svn:https://rometools.jira.com/svn/ROME/trunk</connection> <connection>scm:git:git@github.com:rometools/rome.git</connection>
<developerConnection>scm:svn:https://rometools.jira.com/svn/ROME/trunk</developerConnection> <developerConnection>scm:git:git@github.com:rometools/rome.git</developerConnection>
<url>https://rometools.jira.com/source/browse/ROME</url> <url>https://github.com/rometools/rome</url>
</scm> </scm>
<licenses> <licenses>
<license> <license>
@ -123,11 +117,42 @@
<plugin> <plugin>
<groupId>org.apache.maven.plugins</groupId> <groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId> <artifactId>maven-resources-plugin</artifactId>
<version>2.2</version> <version>2.6</version>
<configuration> <configuration>
<encoding>${project.build.sourceEncoding}</encoding> <encoding>${project.build.sourceEncoding}</encoding>
</configuration> </configuration>
</plugin> </plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>3.3</version>
<configuration>
<port>9000</port>
<tempWebappDirectory>${basedir}/target/site/tempdir</tempWebappDirectory>
</configuration>
<dependencies>
<dependency>
<groupId>org.apache.maven.doxia</groupId>
<artifactId>doxia-module-markdown</artifactId>
<version>1.4</version>
</dependency>
<dependency>
<groupId>org.apache.maven.doxia</groupId>
<artifactId>doxia-module-confluence</artifactId>
<version>1.4</version>
</dependency>
</dependencies>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-scm-publish-plugin</artifactId>
<version>1.0-beta-2</version>
<configuration>
<scmBranch>gh-pages</scmBranch>
<pubScmUrl>scm:git:git@github.com:rometools/rome.git</pubScmUrl>
<content>${project.build.directory}/site</content>
</configuration>
</plugin>
</plugins> </plugins>
</build> </build>
<profiles> <profiles>
@ -197,5 +222,33 @@
<properties> <properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties> </properties>
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-project-info-reports-plugin</artifactId>
<version>2.6</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<reportSets>
<reportSet>
<reports>
<report>javadoc</report>
<report>test-javadoc</report>
</reports>
</reportSet>
<reportSet>
<id>aggregate</id>
<inherited>false</inherited>
<reports>
<report>aggregate</report>
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
</reporting>
</project> </project>

773
src/site/apt/ChangeLog.apt Normal file
View file

@ -0,0 +1,773 @@
-----
Change Log
-----
mkurz
-----
2011-08-15 06:19:27.183
-----
Change Log
*Changes made since v1.0
[[1]] {{{http://java.net/jira/browse/ROME\-127}Issue 127}}: Rome 1.0 not JDK 1.4 compatible
[]
*Changes made since v1.0RC2
[[1]] {{{http://java.net/jira/browse/ROME\-121}Issue 121}}: RSS item category iteration should try to reflect document order
[[1]] New property preserveWireFeed available on SyndFeedInput\
WireFeeds will be preserved if the property preserveWireFeed is set on the SyndFeedInput object it is built from. Atom/RSS Entry/Item objects are also available from SyndEntry objects if the WireFeed is preserved using the new getWireEntry() method. See {{{./PreservingWireFeeds.html}Preserving WireFeeds (rome)}} for details.
[]
*Changes made since v1.0RC1
[[1]] Fix. Date parsing for Atom10 entry and additional W3C masks\
Item date elements were being parsed with the W3C parser instead the lenient one (RFC822 \+ W3C \+ custom masks).\
The following masks were added to W3C masks to handle RFC822 timezone (ie '\-800'):
+------+
yyyy-MM-dd'T'HH:mm:ssZ yyyy-MM-dd't'HH:mm:sszZ
+------+
[[1]] Fix. Contributors properties in SyndEntry were not implementing the semantics of list properties.\
They were returning NULL instead, now they return an empty list if not values are set.
[[1]] Fix. Contributors properties in SyndEntry and SyndFeed were not being converted to/from WireFeed
[[1]] Fix. Syndication Module Generator was failing if some of its values were null.\
Checks for nulll have been added it to the generator to prevent NullPointerExceptions
[[1]] New. Added new constructor to XmlReader
+------+
public XmlReader(InputStream is, boolean lenient, String defaultEncoding)
+------+
[[1]] New. Support atom person construct extensions, using the Extendable interface on SyndPerson:\
Patch from James Roper. See {{{http://java.net/jira/browse/ROME\-110}Issue 1101}} for details
[[1]] New. Maven 2 build for main project\
ROME can now be built with Maven 2
[[1]] New. OSGi support\
OSGi headers to MANIFEST.MF so that rome.jar can also be used in an OSGi environment. See {{{http://java.net/jira/browse/ROME\-117}Issue 117}} for details.
[[1]] New. Allow pretty printing to be turned on and off\
see {{{http://java.net/jira/browse/ROME\-114}Issue 114}} for details. Thanks to Martin Kurz for the patch.
[[1]] Configurable classloading behavior for OSGi compatibility.\
We have received a report of some issues with plugin loading in an OSGi environment ({{{http://java.net/jira/browse/ROME\-118}Issue 118}}). The fix appears to be to change Class.forName to classLoader.loadClass, but the semantics for this are subtly different, so we have made this new behavior user selectable. Set the "rome.pluginmanager.useloadclass" system property to "true" to enable it.
[[1]] More lenient number parsing\
There were a number of problems with feeds providing blank or invalid values in fields which would be numbers. ROME will now handles these better. See issues {{{http://java.net/jira/browse/ROME\-104}104}}, {{{http://java.net/jira/browse/ROME\-107}107}} and {{{http://java.net/jira/browse/ROME\-108}108}} for details.
[]
*Changes made from v0.9 to v1.0RC1
[[1]] New. XmlReader support for default encoding\
The XmlReader can be set with an alternate default encoding in case no encoding has been detected from the transport (HTTP), the stream or the XML prolog. if no value is set the default fallback rules based on the content\-type will be used. The alternate default encoding can be set/viewed via a static methods, <<setDefaultEncoding()>> and <<getDefaultEncoding()>>.
[[1]] Fix. Atom 1.0 links were generated without title and length attributes.\
The Atom 1.0 Generator was not generating title and length attributes when values are present.
[[1]] Fix. XmlReader, multi\-line prolog encoding detection.\
XmlReader handles properly xml\-prolog detection when prolog goes over multiple lies (such as G groups feeds).
[[1]] Fix. Base64 decoding was failing under certain padding conditions.
[[1]] Fix. XmlReader fixes\
Fixed bug that if BOM is UTF8 was not being set to UTF8. Changed logic to use Buffered stream instead pushback stream for all encoding detection. Changed logic of xml prolog detection to avoid having a buffer with half of a unicode character (instead filling up the buffer looking up to first '\>' which means it a valid buffer).
[[1]] New. XmlReader supports default encoding at instance level.\
Via a new constructor is possible to indicate a default encoding different than the default encoding at class level.
[[1]] Fix. Making the EqualsBean to follow equals contract.\
For X.equals(null) it was throwing a NullPointerException, now it returns FALSE.
[[1]] Fix. Render Atom icon and logo attributes.\
AtomGenerator now adds icon and logo elements to xml tree
[[1]] Fix. Updated AtomPub namespace to its permenent home.\
AtomService namespace updated to {{{http://www.w3.org/2007/app}http://www.w3.org/2007/app}}
[[1]] New. Added support for configuration per classloader level.\
The PluginManager (handles Parsers and Generators) now is singleton at classloader level allowing different configurations in different classloaders.
[[1]] Atom parser: better relative URI handling\
Instead of simply resolving each relative URI at runtime and saving only the resolved one, we now save both the relative URI and the resolve one. We introduced the following new methods to provide access to the resolved URI.
* Link.getLinkResolved()
* Link.setLinkResolved()
* Category.getSchemeResolved()
* Category.setSchemeResolved()
* Person.getUriResolved()
* Person.setUriResolved()
[[1]] Utility methods useful in working with Atom protocol feeds\
Added a couple of methods to make it easier to deal with Atompub feeds.
* Entry.isMediaEntry()
* Atom10Parser.parseEntry()
* Atom10Generator.serializeEntry()
[[1]] Bugs fixed\
Fixed the following bugs:
* 49 Better content/summary mapping
* 53 Content.setType not working with subtitles atom 1.0
* 56 fix of bug #39 leads to invalid atom feeds
* 63 Missing link attribute when generating Atom 1.0
* 64 ROME's Atom parser doesn't pick up multiple alt links
* 65 Atom feeds not including logo image
* 71 encoding problem in XmlReader.getXmlProlog()
* 79 Feed.setIcon()/setLogo() ignored by Atom10Generator
* 81 SyndFeedImpl.equals() does not obey equals contract
[[1]] Fix. Parsers where ignoring namespaced prefixed Attributes.\
If an XML feed uses a prefix for the Atom elements and the attributes of Atom elements use the prefix the parser was not picking up those attributes.\
The fix makes the parser to look for prefixed and non\-prefixed attributes.
[[1]] Fix. Atom Feed and Entry beans author and category property getters\
They were returning NULL when there were not authors or categories, they must return an empty list.
[[1]] New. Switch to enable/disable relative URI resolution in Atom 1.0 Parser.\
The Atom10Parser class has a static method, setResolveURIs(boolean) that enables/disables relative URI resolution.
[[1]] New. XmlReader handling content\-type charset values has been relaxed.\
XmlReader handles content\-type charset encoding value within single quotes and double quotes.
[[1]] Fix. Links, authors and contributors properties in SyndFeed were not implementing the semantics of list properties.\
They were returning NULL instead, now they return an empty list if not values are set.
[[1]] Fix. RSS conversion of a SyndFeed was losing the link of the feed if the links property was used instead the link property.\
Over time the SyndFeed has been modified to support more Atom specific properties and their cardinality, conversion to RSS of these properties was not always taken care.\
The RSS converter has been changed so the link from SyndFeed is taken as channel link and if not set the first value of the links property is taken.
[[1]] Fix. WireFeedInput throws IllegalArgumentException if the feed type is not recognized.\
Previously the IllegalArgumentException was wrapped by a ParsingFeedException (Reported by {{{http://java.net/jira/browse/ROME\-91}Issue 91}}).
[[1]] Fix. SyndFeedImpl.equals(other) checks for instance of other before casting.\
The underlying ObjectBean does this check, but in this method a cast is done before to obtain the foreign markup, no the instance check is peformed before to avoid a class cast exception.
[[1]] Fix. Atom content based elements related fixes
* Atom 0.3 Parser/Generator
* Changed title to be treated as a Content construct. ({{{http://www.mnot.net/drafts/draft\-nottingham\-atom\-format\-02.html#rfc.section.4.3}http://www.mnot.net/drafts/draft\-nottingham\-atom\-format\-02.html#rfc.section.4.3}})
* Atom 1.0 Generator:
* changed feed title/subtitle and entry title to be treated as Content constructs. (Parser had this implemented already.)
* added title attribute to links. (Parser had this implemented already.)
* fixed content parsing for some XML content types. e.g. (application/xhtml\+xml)
[[1]] Fix. Atom link and enclosures handling
* Atom 0.3 Converter
* fixed link parsing code to parse all links (not just the first alternate link) and added enclosure support via link rel\="enclosure".
* changed title conversion to use Content instead of plain text.
* Atom 1.0 Converter
* added SyndEnclosure to atom:link rel\=enclosure conversion.
[[1]] Fix. RSS 1.0 URI generation
* RSS 1.0 Generator
* channel/items/Seq/li/@resource now get's the item URI instead of the Link. ({{{http://web.resource.org/rss/1.0/spec#s5.3.5}http://web.resource.org/rss/1.0/spec#s5.3.5}})
[[1]] Fix. Javadocs corrections.
* Fixed some javadoc comments for SyndEntry.
[[1]] Fix. Atom content based elements were not parsed with XML mime types.\
If the mime type was and XML mime type the content value was being lost on parsing.
[[1]] Fix. duplication of content:encoded elements when reading/writing and RSS feed.\
content:encoded elements are treated special, without a module, they have to be removed from the foreign markup to avoid duplication in case of read/write. Note that this fix will break if a content module is used.
[[1]] New. XmlFixerReader converts '&' into '&' when there is no matching entity.\
Feeds commonly use '&' instead '&' in their content, this change converts those orphant '&'s into '&'s.
[[1]] Fix. RSS090Parser does not set the URI property.\
The fix honors the documentation "For RSS 0.91, RSS 0.92, RSS 0.93 & RSS 1.0 ... the SyndEntry uri property will be set with the value of the link element..."
[[1]] New. Removal of all unused namespaces from generated feeds.\
The generators now remove all unused namespaces from the XML document before generating it.
[]
*Changes made from v0.8 to v0.9
[[1]] Design changes
* Support Atom feed.title, feed.subtitle and entry.title {{{http://java.net/jira/browse/ROME\-48}Issue 48}}\
#48 fixed via better support for Atom text constructs title and subtitle. Added get/setTitleEx() and get/setSubtitleEx(), which get get SyndContent objects. Title and subtitle still available from old getters/setters.
* Support for mapping Atom summary/content to RSS description/content {{{https://rome.dev.java.net/servlets/ReadMsg?list\=dev&msgNo\=1680}https://rome.dev.java.net/servlets/ReadMsg?list\=dev&msgNo\=1680}}
* Fixed by introduced Content object in RSS model. ROME now parses as RSS Content. That makes parsing easier and allows us to support a more logical summary/content mapping:
* RSS to/from Atom
* RSS to/from Atom
[[1]] General parsing fixes
* XmlReader xml prolog regular expression does not allow for single quotes {{{http://java.net/jira/browse/ROME\-36}Issue 36}}\
The XmlReader was only parsing prolog encodings within double quotes, the regular expression to detect the encoding has been change to detect single or double quotes.
* Fix. XML prolog parsing now support whitespaces around '\='\
If the XML prolog contained spaces around the '\=' between the encoding attribute name and the encoding attribute value the encoding was not being detected. The fix accepts all valid whitespace characters (as defined in the XML spec).
* RSS parser does not recognize version\="2.00" {{{http://java.net/jira/browse/ROME\-33}Issue 33}}
* Atom 1.0 Text Types Not Set Correctly {{{http://java.net/jira/browse/ROME\-39}Issue 39}}
* Security issue {{{http://java.net/jira/browse/ROME\-46}Issue 46}}
* Fix for the potential problem outlined in {{{http://www.securiteam.com/securitynews/6D0100A5PU.html}http://www.securiteam.com/securitynews/6D0100A5PU.html}}. Thanks to Nelson Minar for bringing this to our attention.
* Fix. Wrong default description type for RSS 2.0 Fix for {{{http://java.net/jira/browse/ROME\-26}Issue 26}}
* Change default description type for RSS 2.0 from text/plain to text/html as per RSS 2.0 spec
* Fix to add all HTML4 entities, according to {{{http://www.w3.org/TR/REC\-html40/sgml/entities.html}http://www.w3.org/TR/REC\-html40/sgml/entities.html}} specially for the HTMLsymbol set (Mathematical, Greek and Symbolic characters for HTML) and the HTMLspecial set (Special characters for HTML).
[[1]] Date parsing fixes
* Additional version and date leniency could extract more information {{{http://java.net/jira/browse/ROME\-24}Issue 24}}
* Non RFC822 Dates not processed in RSS pubDate field {{{http://java.net/jira/browse/ROME\-27}Issue 27}}
* RSS feed parsers were were only parsing RFC822 dates because they were not using the proper date\-time parsing function for the date\-time elements.
* If a W3C date\-time element had no time component it was being parsed as local time instead of GMT, ROME DateParser class has been modified to use GMT in this situation.
* Current JDKs do not handle 'UT' timezone indicator, ROME DateParser class has been modified to handle it.
* Use Atom updated instead of published {{{http://java.net/jira/browse/ROME\-41}Issue 41}}
* Atom 1.0 Date (Updated or Published) Not Set {{{http://java.net/jira/browse/ROME\-42}Issue 42}}
* lastBuildDate does not populate publishedDate {{{http://java.net/jira/browse/ROME\-43}Issue 43}} Provides a feed date for RSS 0.91 feeds that specify lastBuildDate but not pubDate.
* Fix. Parsing some numeric elements was failing due to whitespaces The image.width and image.height of RSS091U, the frequency of SyModule and the cloud.port of RSS092 elements are now being trimmed before doing the integer parsing.
[[1]] Atom link and URI fixes
* Improper relative link resolution in Atom10Parser {{{http://java.net/jira/browse/ROME\-37}Issue 37}}
* ATOM 1.0 Entry links parsing {{{http://java.net/jira/browse/ROME\-38}Issue 38}}
* ConverterForRSS10.java does not set URI for item {{{http://java.net/jira/browse/ROME\-25}Issue 25}}
* Valid IRI href attributes are stripped for atom:link {{{http://java.net/jira/browse/ROME\-34}Issue 34}}
[[1]] Module fixes
* iTunes Module has incorrect author and category support {{{http://java.net/jira/browse/ROME\-35}Issue 35}}
* mediarss.io.MediaModuleParser NumberFormatException {{{http://java.net/jira/browse/ROME\-45}Issue 45}}
* Slash module not serializable for FeedFetcher {{{http://java.net/jira/browse/ROME\-44}Issue 44}}
[]
*Changes made from v0.7 to v0.8
[[1]] Change. Added enclosure support at Synd\* level\
A new bean for handling enclosures at Synd\* level has been created (SyndEnclosure/SyndEnclosureImpl, interface/implementation).\
The SyndEntry/SyndEntryImpl bean has a new 'enclosures' property which returns the list of enclosures for that item.\
The Wire\* to Synd\* converters for RSS propagate enclosures in both directions.\
This enables handling enclosures from RSS 0.92, 0.93, 0.94 and 2.0 at Synd\* level\
Test cases have been modified to cover enclosures at Synd\* level.
[[1]] Change/Fix. Synd\* \- Atom entry dates mapping
* (Change) Atom entries have 3 dates, 'modified', 'issued' and 'created'. Synd entries have only 1 date property 'publishedDate'. When converting from Atom to Synd the first not null date in the order above will be the one set in the Synd entry bean.
* (Fix) When converting from Synd to Atom the Synd entries 'publishedDate' property value is set in both 'modified' and 'issued' properties of the Atom entry.\
This Change/Fix is to be aligned with the Atom 0.3 spec.
[[1]] Fix. Trim enclosure length attribute\
Fix from Trey Drake: At least 1 podcast site (ESPN) occasionally leaves trailing spaces in the enclosure content length attribute. This causes a NumberFormatException.
[[1]] Fix. Conversion to RSS 1.0 if Channel URI is not specified\
Fix for problem converting to RSS 1.0 if not URI is specified at the channel level (it will now attempt to use the Link element)
[[1]] Changes to support Atom 1.0
* In com.sun.syndication.synd, added SyndLink and SyndPerson.
* In SyndEntry added. In SyndEntry, added summary, updatedDate, links collection and support for multiple authors.
* In com.sun.syndication.synd.impl, added Atom10Parser.java, Atom10Generator.java and ConverterForAtom10.java.
[]
*Changes made from v0.6 to v0.7
[[1]] Fix. RFC\-882 dates parsing and generation were using localized names for day and month names\
The date parser and generator were using the JVM default Locale instead forcing an English Locale to use day and month names in English as specified by RFC\-822. Now US Locale is used.
[[1]] Fix. The 'ttl' element of RSS0.94 and RSS2.0 feeds was not being parsed\
The parsers now parse the 'ttl' element and it is available in the resulting Channel bean. Note that 'ttl' info is not available in the SyndFeed bean, thus it's lost when converting from WireFeed to SyndFeed.
[[1]] Change. RSS enclosures with empty 'length' attributes are accepted\
Parsing an RSS feed with an enclosure where the length attribute was an empty String were failing. Now they are parsed and the length is set to 0.
[[1]] Change. RSS 1.0 feeds use URI/Link for unique ID (rdf:about).\
RSS 1.0 specification recommends that the rdf:about attribute URI use the value of the item's link element, though this could be different if the user chooses to override it by specifying their own URI. RSS 1.0 feeds now use the URI if specified, otherwise the link for the item.
[[1]] Fix. toString() was reporting NullPointerException with List properties\
When a List (or Map) property had a NULL element the toString() logic was failing partially due to a NullPointerException.
[[1]] Fix. DC creator elements were being lost when converting to SyndFeed\
DC creator elements were being lost when converting to SyndFeed. This was happening with RSS versions that have native author elements (0.94 and 2.0) and for the managingEditor element at channel level (available in 0.91 Userland and onwards).
[[1]] Change. Date and enumeration elements are trimmed during parsing\
There are some feeds that add whitespaces or carriage return characters before or after the proper date or enumeration value. This was causing ROME to fail processing those elements. This is taken care now as all dates elements in all feed types and Modules and the 'channel.skipHours.hour' and 'channel.skipDays.day' (RSS0.91 \- RSS2.0) are trimmed before parsing and setting their values in the beans.
[[1]] Fix. SyndFeed description now maps to atom:tagline\
Previously, atom:info was being mapped to the feed's description. According to the Atom03 spec atom:info should be ignored by parsers, and the more appropriate element is atom:tagline.
[[1]] Fix. RSS cloud is now generated/parsed correctly\
The 'path' attribute from the cloud was not being generated/parsed. The parser now process all cloud attributes and set the cloud to the channel.
[[1]] Fix. RFC\-822 2 digit years\
Previously RFC\-822 dates did not work correctly with 2 digit years. This is now fixed.
[[1]] Fix. No alternate link causes IndexOutOfBoundsException\
Fix bug where no alternate link causes IndexOutOfBoundsException in ConverterForAtom03 (Thanks to Joseph Van Valen).
[[1]] Change. Date parsing attemps RFC822 on W3C parsing on all feeds\
All feed parsers (RSS and Atom) now attemp both RFC822 and W3C parsing on date values.
[[1]] Fix. XmlFixerReader removes character from stream when parsing an entity that contains an invalid character\
Fix bug in XmlFixerReader where an invalid entity such as "&ent\=", gets put back on the stream without the last character (in this example, "&ent\=" becomes "&ent"). This was most visible when the XmlFixerReader encountered an URL with a query string that has more than one parameter (e.g. {{{http://www.url.com/index.html?qp1\=1&qp2\=2}http://www.url.com/index.html?qp1\=1&qp2\=2}}) \-\- all "\=" after the first one would disappear.
[[1]] Change. DateParser can use additional custom datetime masks\
Besides attempting to parse datetime values in W3C and RFC822 formats additional datetime masks can be specified in the /rome.properties files using the 'datetime.extra.masks' property. To indicate multiple masks the '|' character must be used, all other characters are considered part of the mask. As with parser/generators/converter plugins the masks are read from all /rome.properties file in the classpath.
[]
*Changes made from v0.5 to v0.6
[[1]] Fix. W3C date\-time parsing now handles date\-time with 'Z' modifier\
The W3C date\-time parser was not parsing times using the UTC modifier 'Z'.
[[1]] Fix. XML prolog encoding parsing was failing when other attributes where present in the prolog\
If there was an attribute following the encoding attribute the value of the encoding attribute was misinterpreted. For example, for the XML prolog the detected encoding was <<<UTF\-8" standalone\="yes>>> instead of <<<UTF\-8>>>.
[[1]] Change. XmlReader lenient behavior gives priority to XML prolog encoding over content\-type charset\
In ROME 0.5 the XmlReader first attempts to do a strict charset encoding detection. Only if the strict detection fails it attempts a lenient detection. When the HTTP Content\-Type header is of type <<<text/\*xml>>> and the header does not specify any charset, RFC 3023 mandates that the charset encoding must be <<<US\-ASCII>>>. It's a common error for sites to use the <<<text/\*xml>>> MIME type without charset information and indicate the charset encoding in the XML prolog of the document, being the charset encoding in the XML prolog different from <<<US\-ASCII>>>. The XmlReader lenient behavior has been modified to give precedence to the XML prolog charset encoding, if present, over the HTTP Content\-Type charset encoding.
[[1]] Addition. XML Healer\
ROME parsers, SyndFeedInput and WireFeedInput, have a new feature, XML healing.\
The XML healing trims the beginning of the XML text document if there are whitespaces, enters or XML comments before the XML prolog or the root element. It also replaces all HTML literal entities occurrences with coded entities. These changes convert feeds technically invalid (from the XML specification perspective) into valid ones allowing the SAX XML parser to successfully parse the XML if there are not other errors in it.\
This behavior is active by default. It can be turned on and off using the new 'xmlHealerOn' property in the SyndFeedInput and WireFeedInput classes.\
The idea for this feature was taken from the FeedFilter from Jakarta's commons feedparser.
[[1]] Addition. The XML prolog of generated feeds contains the feed encoding\
ROME generators were creating feeds with the XML prolog encoding always set to 'UTF\-8', if the given Writer had another charset encoding things would break for anybody consuming the feed (a mismatch between the char stream charset and what the XML doc says).\
The SyndFeedOutput and WireFeedOutput generators now use the SyndFeed and WireFeed 'encoding' property to set the 'encoding' attribute in the XML prolog of the generated feeds. It is the responsibility of the developer to ensure that if the String is written to a character stream the stream charset is the same as the feed encoding property.
[[1]] Change. SyndFeed to Atom convertion now uses 'escaped' mode for content elements\
SyndFeed to Atom converter was using 'xml' mode for content elements. This was breaking feeds with content that was not propertly escaped as it was assumed to be XML fragments.
[[1]] Change. RSS 2.0 parser and generator now handles DC Module\
ROME configuration has been changed so RSS 2.0 parser and generator handle DC Module elements at channel level and item level.
[[1]] Fix. RSS0.93, RSS0.94 and RSS2.0 'dc:date' element value was being lost under certain conditions\
If a feed had 'dc:date' elements but not 'pubDate' elements, the 'dc:date' elements where lost when converting from Channel to SyndFeed.\
This was happening for 'dc:date' elements at channel level and at item level.
[[1]] Fix. RSS 1.0 'rdf:resource' and 'rdf:about' item linking attributes use a unique ID now\
The value for the 'rdf:resource' and 'rdf:about' linking attributes was done using the value of the 'link' element. If there is more than one item with the same link the generated feed will be incorrect.\
Instead using the link value now the index of the item is used for the linkage between 'rdf:resource' and 'rdf:about' for items.
[[1]] Fix/Change. Parsing and setting of enumerated elements is case insentive now\
Parsing and bean setting of enumerated values (such as RSS skipDay, Atom content mode, etc) are now case insentive, generation is strict (Postel Law).
[[1]] Fix. Remove enumeration check on 'rel' attribute of Atom link elements\
Because a misunderstanding of Atom 0.3 specification the Atom Link bean was checking the value of the 'rel' property against a set of valid values. The check has been removed.
[[1]] Fix. DC subjects (in RSS versions with native categories) were being lost on conversion to SyndFeed\
All RSS versions with native categories (at both channel and item level) now have the following behavior when converting to SyndFeed.\
DC subjects are converted to SyndCategories. Native categories are converted to SyndCategories. They are both aggregated in a Set (to remove duplicates) then added to the SyndFeed.\
When doing a SyndFeed to Channel conversion, if the RSS version has native categories and handles DC modules the categories will be duplicated as native and DC ones.
[[1]] Fix/Change. RSS 1.0 rdf:about attribute in the channel.\
RSS 1.0 uses the rdf:about attribute at the channel level as an identifier. This was not being parsed or generated (only supported at the item level). Support for this was added along with test cases.
[[1]] Fix/Change/Addition. Multivalued Dublin Core element support.\
Many feeds are using multiple DC elements to tag metadata, the interface for the DCModule has been changed to support Lists of elements, compatibility has been maintained with the existing interface though as the new methods are plural (creators vs. creator), the single value methods will remain as convenience methods. The implementation now uses the lists to represent all of the elements. The parser/generator modules for DC have been updated to reflect these changes along with a few other code cleanups in the DC\* modules.
[[1]] Fix. Removed length constraint checks from RSS1.0 generator\
RSS1.0 specification does not require, only suggests, maximum length for some of the elements. ROME was enforcing those lenghts when generating RSS1.0 feeds. This enforcement has been removed becuase is not mandatory.
[]
*Changes made from v0.4 to v0.5
[[1]] Change. Got rid of Enum class\
All constants in the beans are Strings now, the corresponding property setters check that the value being set is one of the valid constants. Rome has not business defining an Enum class.
[[1]] Change. Got rid of ToString interface\
This is just an implementation convenience, it was polluting Rome API. Modified ToStringBean to work without requiring an interface and method to propagate the prefix to use with properties.
[[1]] Change. ObjectBean, ToStringBean, EqualsBean are not part of the public API anymore\
These are just an implementation convenience, they were polluting Rome API. Rome bean implementations don't extends ObjectBean anymore. Instead they use it in a delegation pattern. While these classes are not public anymore they are part of Rome implementation.
[[1]] Change. CopyFrom interface moved to com.sun.syndication.feed package\
The common package is gone now that the \*Bean classes are not there anymore. No point keeping a package just for an interface.
[[1]] Fix. PluginManager was not doing plugin lookup in the defined order\
PluginManager (manages parsers, generators and convertors for feeds and modules) was not doing the lookup in order the plugins are defined in the rome.properties files. This is needed for parsers where the lookup involves detecting the feed type and the feed type detection goes needs to go from stronger to weaker.
[[1]] Addition. Rome now recognizes RSS 2.0 feeds with 'http://backend.userland.com/rss2' namespace\
These namespace was defined by an RSS 2.0 draft and later was dropped. There are feeds out there using this namespace and Rome was not parsing them.
[[1]] Change. By default XmlReader does a lenient charset encoding detection.\
If the charset encoding cannot be determined per HTTP MIME and XML specifications the following relaxed detection is performed: If the content type is 'text/html' it replaces it with 'text/xml' and tries the per specifications detection again. Else if the XML prolog had a charset encoding that encoding is used. Else if the content type had a charset encoding that encoding is used. Else 'UTF\-8' is used.\
There are 2 new constructors that take a lenient flag to allow strict charset encoding detection. If scrict charset encoding detection is performed and it fails an XmlReaderException is thrown by the constructor. The XmlReaderException contains all the charset encoding information gathered from the stream including the unconsumed stream.
[]
*Changes made from v0.3 to v0.4
[[1]] Fix. Date elements on generated feeds use the right format now\
There were some Date elements in Atom 0.3, DCModule, SyModule, RSS 0.91 and RSS 0.93 that were incorrectly formating the date \[they were just doing a toString() \]. Now they use the RFC822 and W3C format as indicated in their specs.
[[1]] Fix. SyndFeed and SyndEntry getModule(DCModule.URI) method always returns a DCModule, never null\
This issue is related to Fix #19 in v0.3. The DCModule is 'special' for Synd\*, it must always be there. If it is not, it is created implicitly when needed. This was not happening when asking explicitly for the DCModule through the Synd\* interfaces.
[[1]] Addition. Added ParseFeedException to the \*Input classes\
This new exception report the line and column number in the XML document where the parsing has failed.
[[1]] Change. Renamed '\*I' interfaces to just '\*' and default implementations to '\*Impl'\
The Synd\* and Module interfaces/classes were affected. For example the interface that used to be SyndFeedI is now SyndFeed and the class that used to be SyndFeed is now SyndFeedImpl.
[[1]] Change. Ant 'build.xml' files have been improved\
The build.xml were re\-written instead just using the Maven generated ones.
[[1]] Fix. DateParser now uses lenient parsing so as to work with JDK 1.5\
DateParser currently setLenient to false. This does not work with JDK 1.5. Changing the DateParser to setLient to true.
[[1]] Change. SyndCategoryListFacade is not a public class anymore\
It's now a package private class (it should have been like that in the first place).
[[1]] Addition. Added a protected constructor to the Synd\*Impl classes\
This constructor takes a Class parameter. It allows implementations extending SyndContentImpl to be able to use the ObjectBean functionality with extended interfaces (additional public properties). Use case: Hibernate beans that have an 'Id' Long property, a new interface HSynd\* (extending Synd\*) and a new implementation HSynd\*Impl (extending Synd\*Impl) where the clone(), equals(), hashCode() and toString() methods take the properties of the extension into account.
[[1]] Project layout change. Moved samples project to subprojects dir\
The 'samples' project was moved from 'rome/modules/samples' to 'rome/subprojects/samples'. The 'rome/modules' project is left for Module subprojects only.
[[1]] Fix. Plugin manager bug didn't allow custom plugins to replace core plugins\
All plugins are in a Map keyed off by its type (parsers, generators, converters) or URI (modules). There is also a helper List containing the plugins, this list is scanned when looking for a plugin (for example when selecting the right parser). Plugins were added to the List without checking if another element in the List was using the same key. Now the List is built using the Map values, thus the overwriting works fine.
[[1]] Fix. RSS 2.0 Converter (Wire \-\> Synd \- Wire) was not processing modules\
The RSS 2.0 Converter now processes feed and entry modules both ways.
[[1]] Fix. New properties introspection mechanism in common classes\
The java.beans.Introspector does not work as expected on interface properties (it doesn't scan properties of the super interfaces). Now, a private implementation of a properties introspector is used by the common bean classes.
[[1]] Change. Refactored private CopyFrom helper class\
It was com.sun.syndication.feed.synd.impl.SyndCopyFrom now it is com.sun.syndication.common.impl.CopyFromHelper.
[[1]] Fix. RSS2.0 Wire\-Synd converter handles propertly RSS and DC categories\
If the RSS2.0 feed had DC Module categories (subjects) this would override the RSS native categories. Now they are aggregated.
[[1]] Change/Fix. CloneableBean can take an ignore\-properties set\
This change is useful for bean that have convenience properties mapping to other properties. SyndFeed and SyndEntry that map some of its properties (ie publishedDate, author, categories) to DC Module properties. There is not point cloning the convenience ones as they are just facades.\
This fixes a SyndFeedImpl cloning problem with the categories. There is a package private list for the categories to DC subject mapping. The problem was related to accesibility of this package private list implementation by the CloneableBean. The change enables the blacklisting of certain properties (in this categories) when cloning.
[[1]] Change. Refactored Parsers/Generator classes\
Introduced a base parser and base generator to handle modules. For the feed types that define modules support, the modules have to be defined the rome.properties file. For RSS 1.0 and Atom 0.3 Dublin Core and Syndication modules are defined, the first one at feed and entry level the second one at feed level. Note this was already done but hardwired in the specific feed type parsers and generators, now it is done in the base parser and base generator. Some code clean up and removal of duplicated code was also done.
[[1]] Change. Defined and implemented precedence order for native and module elements in feeds\
For feeds supporting modules, some of the module defines elements collide with the feed native elements (this depends on the feed type, and it may affect the data such as publish\-date, author, copyright, categories). The SyndFeed and SyndEntry properties documented as convenience properties are (can be) affected. The convenience properties map into DC Module properties.\
Rome now defines precedence of feed native elements over module elements when converting from WireFeed to SyndFeed. This is, in the situation of a clash, the native element data prevails and the the module element data is lost.\
When converting from SyndFeed to WireFeed, if a SyndFeed convenience property has a native mapping in the target feed type it will be in both the native element and the DC Module element if the feed type defines support for the DC module. The data will appear twice in the feed, in the native elements and in the DC module elements.
[[1]] Change. Module namespaces are defined at root element\
Module namespaces are always defined in the root element. The ModuleGenerator interface has a new method that returns all the namespaces used by the module, the generators use the namespaces returned by this method to inject them in the feed root element.
[[1]] Change/Fix. Test cases refactoring\
Some refactoring in the test cases for the Synd\* entities. Some minor bugs (typos in constants) were found and fixed in the parsers.\
The Ops and Synd tests are 100% complete. Not that they test 100% of Rome functionality but 100% of what they suppose to test.
[[1]] Fix. Atom 0.3 content elements with XML mode were not being parsed and converted properly\
When mode is XML, free text was not being processed, only sub\-elements were being processed.\
The Parser when parsing content with XML mode skips Atom namespace in the output of the processed fragment.\
The Converter when going down pushes content data using XML mode, which is Atom's default (it was ESCAPED before).
[[1]] Addition. Constraints in data length and number of items are observed by RSS generators\
As part of the generators refactoring the generators now verify the data in the Rome beans does not generate invalid feeds.
[[1]] Addition. New XmlReader that detects charset encoding\
The XmlReader class handles the charset encoding of XML documents in Files, raw streams and HTTP streams. It following the rules defined by HTTP, MIME types and XML specifications. All this is nicely explained by Mark Pilgrim in his blog, {{{http://diveintomark.org/archives/2004/02/13/xml\-media\-types}http://diveintomark.org/archives/2004/02/13/xml\-media\-types}}
[[1]] Rome now uses JDOM 1.0\
Dependencies have been updated to use JDOM 1.0. No code changes were needed because of this.
[[1]] Change. The length property in the RSS Enclosure bean is now a long\
It used to be an int, but as it is meant to specify arbitrary lengths (in could be in the order of several megabytes) it was changed to be a long.
[[1]] Addition. SyndFeed and SyndEntry beans have a 'uri' property\
It is used with RSS0.94 & RSS2.0 guid elements and with Atom0.3 id elements. Refer to {{{./RomeV0.4FeedAndEntryURIMapping.html}Feed and entry URI Mapping}} for a full explanation.
[[1]] Addition. New sample, FeedServlet\
Added a new sample, FeedServlet. This servlet creates a feed and returns a feed.
[[1]] Change. RSS0.91 Userland and RSS0.91 Netscape are handled as different feed types\
Instead having a single set of parser/converter/generator implementations there is one set for each one of them. This allows to differenciate incoming RSS0.91 Userland feeds from RSS0.91 Netscape feeds as well as choosing which one to generate.
[]
*Changes made from v0.2 to v0.3
[[1]] Changed loading mechanism for parsers, generators and converters\
Previous mechanism was complicated and it wouldn't work in server environments where you cannot alter System properties at will.\
Now there are no properties to set. Just including a rome.properties file in the root of a JAR file will make Rome to load any parser, generator or converter defined in the properties file and included in the JAR file (To be documented).
[[1]] Added Modules support to RSS 2.0 parser and generator\
We were only looking for modules in RSS 1.0 and Atom 0.3. Now we also look in RSS 2.0.
[[1]] Modules parsers and generators are now per feed type\
They were global, now each feed type parser and generator has it's own set of modules parsers and generators. They are configurable in the rome.properties file.
[[1]] All parsers, generators and converters are loaded once per definition\
There were some cases we were loading them on every WireFeedParser/WireFeedGenerator instantiation. As they are all thread\-safe we just use one instance.
[[1]] Changed some implementation (hidden) class names\
Some typos corrections and adding consistency to the naming.
[[1]] Added Fetcher module\
Added a HTTP fetcher with conditional get and gzip support (See modules/fetcher)
[[1]] Modified the samples module build to fix error\
Previouly some people were having a maven error trying to run some of the samples. This should now be fixed
[[1]] Removed methods with byte stream signatures from Rome IO classes\
They have no way to know what the encoding is or has to be and they are using the platform default. That does not always work, for example when doing HTTP where the default is ISO\-8859\-1.\
Leaving the char streams one and let the developer to do the right thing (Rome cannot do any magic here).
[[1]] Added getModule(String uri) to SyndFeedI, Atom Feed and RSS Channel\
There was not way to obtain a specific module using the module URI, you had to obtain the module list and iterate looking for the module. The getModule(string uri) is a convenience method in all the feed beans to do that.
[[1]] New. Added 'encoding' property to WireFeed and SyndFeedI/SyndFeed\
Impact: It affects RSS, Atom and SyndFeed syndication beans.\
It's not being set or use by parsers and generators as they always deal with a char strean where the charset is already set.\
The converters, going from Channel/Feed 2 SyndFeed and vice versa are wired to pass the encoding if set.
[[1]] Fix. CloneableBean array cloning bug\
Impact: It affects all Rome beans as they all extend ObjectBean that uses CloneableBean\
Arrays were not being cloned but copy by reference. This was affecting all Rome beans as they all extend ObjectBean.
[[1]] Change. CloneableBean, Basic (primitives & string) types not cloned anymore\
Impact: It affects all Rome beans as they all extend ObjectBean that uses CloneableBean\
Basic types are inmutable, no need to clone them. As things are done using reflection there were unnecessary objects creation.
[[1]] Change. CloneableBean, added Date to list of Basic types\
Impact: It affects all Rome beans as they all extend ObjectBean that uses CloneableBean\
Same reasoning as #12
[[1]] Change/Fix. EqualsBeans, works on defined class\
Impact: It affects all Rome beans as they all extend ObjectBean, which uses EqualsBean\
EqualsBean checks for equality by comparing all properties. Until now it was doing this using all properties of the class implementing the bean. This behavior is not correct as implementations may have other properties than the defined in the public interface (and example is: a SyndFeedI implementation for Hibernate that has to have an ID field, and this would apply to all bean interfaces).\
Because of this change, both EqualsBean and ObjectBean take a Class parameter in the constructor. Equals will limit the comparison for equality to the properties of that class. If there is not interface for the bean, just the bean implementation (this is the case of Channel and Feed), the implementation Class is passed
[[1]] Change/Fix. ToStringBean, works on defined class\
Same as #14 but on ToStringBean instead EqualsBean
[[1]] New. Added copyFrom functionality to synd.\* and module.\* beans\
Impact: It affect all synd.\* and module.\* beans and other classes that extend ObjectBean.\
A new interface 'CopyFrom' has been added to commons.\
synd.\* and module.\* bean interfaces implement this interface and their implementations implement the copyFrom functionality.\
The copyFrom functionality allows copying a complete bean feed from one implementation to another. The obvious use case is from the default bean implementation to a persistent aware (ie Hibernate) implementation.\
The implementation uses the same pattern used by EqualsBean, ConeableBean, it's in the synd.impl.\* package, the supporting class is call SyndCopyFrom.\
Note that SyndCategories does not support the copyFrom functionality as it's just a convenience way of accessing DCModule's subjects (where DCModule supports copyFrom). The short explanation is that categories still work and are there after a copyFrom.
[[1]] Fix. WireFeed constructor was passing the WireFeed.class to ObjectBean\
rss.Channel, atom.Feed & WeatherChannel constructor implementations only, no change to their signatures.\
The class is used for property scanning for toString, equals behavior of the ObjectBean.
[[1]] Fix. copyFrom was failing with Enum properties\
It was not possible to do a copyFrom on a feed with SyModule data as it had Enum properties.\
Wrong comparison of classes when checking basic types, in the case of enumeration classes has to check it extends Enum not equality.
[[1]] Fix. SyndFeed and SyndEntry where losing Modules\
If they had modules other than DCModule they were being dropped when accessing convenience methods (getCategories, getLanguage, etc).\
The Synd\* convenience methods just map to the DCModule properties. If there is no DCModule a new one is created if needed. When this happened instead bean added to the list of current modules a new list with just the DCModule was being set.
[[1]] New Sample and tutorial for creating a feed\
A new sample and tutorial that creates and writes a feed has been added.
[[1]] New Sample showing how to add a Module bean, parser and generator to Rome\
This sample defines a dummy module for use with RSS 1.0 (it can work also with RSS 2.0 and Atom 0.3). Still have to write tutorial
[[1]] Undoing change #13 as Date is not inmutable\
The Date class is not inmutable, CloneableBean now clones Date properties.
[]
*Changes made from v0.1 to v0.2
[[1]] FeedInput, added default constructor. Semantics is 'validation off'\
We forgot to added it when it was added to SyndFeed.\
NOTE that validation is not implemented yet. We need DTDs/XML\-Schemas for the different feed syndication types.
[[1]] FeedOutput and SyndOutput outputW3CDom() method typo correction\
Fixed typo in outputW3CDom() method, it was ouptutW3CDom().
[[1]] AbstractFeed, renamed to WireFeed\
Never liked Abstract in the name. From Java inheritance it makes sense, but from the syndication feed perspective doesn't. It's the super class of the 2 wire feed beans Rome has, RSS Channel and Atom Feed.
[[1]] Renamed SyndFeed createRealFeed(feedType) method to createWireFeed(feedType)\
For consistency with change #3
[[1]] SyndFeed, added feedType property\
Read/write property. It indicates what was the feed type of the WireFeed the SyndFeed was created from. And the feed type a WireFeed created with createWireFeed() will have.
[[1]] WireFeed, renamed type property to feedType\
For consistency with #5. Also it's more clear what the type is about.
[[1]] Overloaded SyndFeed createRealFeed() with a no parameter signature
[[1]] FeedOutput, removed feed type from constructor\
It now uses the WireFeed feedType property.
[[1]] SyndOutput, removed feed type from constructor\
It now uses the SyndFeed feedType property define in #5.
[[1]] FeedOutput, removed getType() method\
Now FeedOutput uses the WireFeed feedType property.
[[1]] Removed dependency on Jakarta Commons Codec library\
We were using the Codec component to do Base64 encoding/decoding. Based on feedback to reduce component depencies we've removed this one (yes, we implemented a Base64 encoder/decoder).
[[1]] Removed dependency on Xerces library\
This was an unnecessary dependency as Rome requeries JDK 1.4\+ which includes JAXP implementation. JDOM can use that one.
[[1]] Renamed syndication.io classes/interfaces\
Renaming for naming consistency and to reflect on what type of feed they work on.
+------+
FeedInput --> WireFeedInput
FeedOutput --> WireFeedOutput
FeedParser --> WireFeedParser
FeedGenerator --> WireFeedGenerator
SyndInput --> SyndFeedInput
SyndOutput --> SyndFeedOutputt
+------+
[[1]] Removed syndication.util package, PlugableClasses is now private\
The PlugableClasses class has no business in Rome public API, it's implementation specific, it has been hidden (it should be replaced later with a micro\-container).
[[1]] Added samples to the Rome project directory structure\
Rome samples are a sub\-project located at rome/modules/sample.
[]

363
src/site/apt/HowRomeWorks/RomeV0.4TutorialDefiningACustomModuleBeanParserAndGenerator.apt Normal file
View file

@ -0,0 +1,363 @@
-----
Rome v0.4 Tutorial, Defining a Custom Module (bean, parser and generator)
-----
mkurz
-----
2011-08-14 17:34:02.657
-----
Rome v0.4 Tutorial, Defining a Custom Module (bean, parser and generator)
<<Software requirements:>> Synd J2SE 1.4\+, JDOM 1.0 and Rome 0.4.
This tutorial walks through the steps of creating a custom module for syndication feeds that support additional namespaces (such as RSS 1.0, RSS 2.0 and Atom 0.3).
To understand this tutorial you should be familiar the with Rome API and with the use of modules in syndication feeds.
Out of the box Rome parsers and generators support plug\-ability of modules for RSS 1.0, RSS 2.0 and Atom 0.3 at both feed and item/entry levels. Also support for the Dublin Core and Syndication modules is provided.
The complete source for this tutorial is in the Rome samples bundle as well as in SVN.
*What is the intended outcome of the tutorial?
The goal is to add support for a hypothetical Sample Module by defining a module bean, module parser and module generator and the necessary configuration to wire the parser and generator to an RSS 1.0 parser and RSS 1.0 generator.
The sample module defines 3 elements, 'bar', 'foo' and 'date', where 'bar' and 'date' may occur at most once and the 'foo' element may occur several times. For example, a feed with the Sample Module data would look like:
+------+
<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns="http://purl.org/rss/1.0/"
xmlns:sample="http://rome.dev.java.net/module/sample/1.0">
<channel>
<title>RSS 1.0 Feed with Sample Module</title>
<link>http://rome.dev.java.net</link>
<description>This is a feed showing how to use a custom module with Rome</description>
<items>
<rdf:Seq>
<rdf:li resource="item01" />
<rdf:li resource="item02" />
</rdf:Seq>
</items>
<sample:bar>Channel bar</sample:bar>
<sample:foo>Channel first foo</sample:foo>
<sample:foo>Channel second foo</sample:foo>
</channel>
<item rdf:about="item01">
<title>Title of Item 01</title>
<link>http://rome.dev.java.net/item01</link>
<description>Item 01 does not have Sample module data</description>
</item>
<item rdf:about="item02">
<title>Title of Item 02</title>
<link>http://rome.dev.java.net/item02</link>
<description>Item 02 has Sample module data</description>
<sample:bar>Item 02 bar</sample:bar>
<sample:foo>Item 02 only foo</sample:foo>
<sample:date>2004-07-27T00:00+00:00</sample:date>
</item>
</rdf:RDF>
+------+
*Sample Module Bean
First we must start with the bean interface, SampleModule. SampleModule must extend Module. The Module interface defines the getUri() method, which will return a URI identifying the module. The Module interface also extends the Cloneable, ToString and CopyFrom interfaces to ensure that the beans provide support for basic features as cloning, equality, toString, etc. (for more details on this check the {{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04Common}Understanding the Rome common classes and interfaces}} document).
The SampleModule's URI is defined as a constant, accessible via the getURI() instance method. This is for convenience and good practice only.
Then the module defines 3 properties: bar (String), foos (List) and date (Date). The elements of the foos property list must be strings (wishing for Java 5 generics already?).
+------+
public interface SampleModule extends Module,CopyFrom {
public static final String URI = "http://rome.dev.java.net/module/sample/1.0";
public String getBar();
public void setBar(String bar);
public List getFoos();
public void setFoos(List foos);
public Date getDate();
public void setDate(Date date);
}
+------+
Next we have to write the bean implementation, SampleModuleImpl.
SampleModuleImpl extends ModuleImpl. ModuleImpl is the default implementation of the \=\=Module interface. ModuleImpl extends ObjectBean which provides equals, hashCode, toString and clone support for the properties of the class given in the constructor (SampleModule). Also the URI of the Sample module is indicated; it will be used by the Module.getUri() method.
+------+
public class SampleModuleImpl extends ModuleImpl implements SampleModule {
...
public SampleModule() {
super(SampleModule.class,SampleModule.URI);
}
public String getBar() {
return _bar;
}
...
+------+
The module properties are just Java Bean properties. The only catch is to follow Rome semantics for Collection properties: in the case of a null value for the collection, an empty collection must be returned.. Also, following Rome semantics, all properties are by reference, including mutable ones.
+------+
public class SampleModuleImpl extends ModuleImpl implements SampleModule {
private String _bar;
private List _foos;
private Date _date;
...
public void setBar(String bar) {
_bar = bar;
}
public List getFoos() {
return (_foos==null) ? (_foos=new ArrayList()) : _foos;
}
public void setFoos(List foos) {
_foos = foos;
}
public Date getDate() {
return _date;
}
public void setDate(Date date) {
_date = date;
}
+------+
Now the weird part: the bits for the CopyFrom logic. The {{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04Common}Understanding the Rome common classes and interfaces}} document fully explains the CopyFrom logic in detail. In short, the CopyFrom interface is to support copying properties from one implementation of a bean (defined through an interface) to another implementation of the same bean.
The getInterface() method returns the bean interface of the implementation (this is necessary for collections containing sub\-classes such as a list of modules).
The copyFrom() method copies all the properties from the parameter object (which must be a SampleModule implementation) into the caller bean properties. Note that the copyFrom must do a deep copy.
+------+
public class SampleModuleImpl extends ModuleImpl implements SampleModule {
...
public Class getInterface() {
return SampleModuleI.class;
}
public void copyFrom(Object obj) {
SampleModule sm = (SampleModule) obj;
setBar(sm.getBar());
List foos = new ArrayList(sm.getFoos()); // this is enough for the copy because the list elements are inmutable (Strings)
setFoos(foos);
setDate((Date)sm.getDate().clone()); // because Date is not inmutable.
}
}
+------+
*Sample Module Parser
The sample module parser must implement the ModuleParser interface. This interface defines 2 methods, getNamespaceUri() that returns the URI of the module and parse(Element) which extracts the module elements from the given Element.
The feed parsers will invoke the module parser with a feed element or with an item element. The module parser must look for module elements in the children of the given element. That is was the Sample parser is doing when looking for 'bar', 'foo' and 'date' children elements in the received element.
In the case of the 'foo' element it looks for all occurrences as the Sample module schema allows for more than one occurrence of the 'foo' element. A SampleModule bean is created and the found values are set into it. For the 'date' element it assumes its a date value in W3C datetime format.
If no Sample Module elements are found in the feed, the parse(Element) method returns null. This is to avoid having an empty instance of a module \-not present in the feed\- in the feed bean or in the item bean.
+------+
public class SampleModuleParser implements ModuleParser {
private static final Namespace SAMPLE_NS = Namespace.getNamespace("sample", SampleModule.URI);
public String getNamespaceUri() {
return SampleModule.URI;
}
public Module parse(Element dcRoot) {
boolean foundSomething = false;
SampleModule fm = new SampleModuleImpl();
Element e = dcRoot.getChild("bar", SAMPLE_NS);
if (e != null) {
foundSomething = true;
fm.setBar(e.getText());
}
List eList = dcRoot.getChildren("foo", SAMPLE_NS);
if (eList.size() > 0) {
foundSomething = true;
fm.setFoos(parseFoos(eList));
}
e = dcRoot.getChild("date", SAMPLE_NS);
if (e != null) {
foundSomething = true;
fm.setDate(DateParser.parseW3CDateTime(e.getText()));
}
return (foundSomething) ? fm : null;
}
private List parseFoos(List eList) {
List foos = new ArrayList();
for (int i = 0; i < eList.size(); i++) {
Element e = (Element) eList.get(i);
foos.add(e.getText());
}
return foos;
}
}
+------+
*Sample Module Generator
The sample module generator must implement the ModuleGenerator interface. This interface defines 2 methods, getNamespaceUri() that returns the URI of the module and generate(ModuleI,Element) which injects the module data into the given Element.
The feed generator will invoke the module generator with a feed element or with an item element. The module generator must inject the module properties into the given element (which is a feed or an item). This injection has to be done using the right namespace. The set of namespaces returned by the getNamespaces() method will be used to declare the namespaces used by the module in the feed root element.
If no Sample Module bean is in the feed bean the module generator is not invoked at all.
+------+
public class SampleModuleGenerator implements ModuleGenerator {
private static final Namespace SAMPLE_NS = Namespace.getNamespace("sample", SampleModule.URI);
public String getNamespaceUri() {
return SampleModule.URI;
}
private static final Set NAMESPACES;
static {
Set nss = new HashSet();
nss.add(SAMPLE_NS);
NAMESPACES = Collections.unmodifiableSet(nss);
}
public Set getNamespaceUris() {
return NAMESPACES;
}
public void generate(Module module, Element element) {
// this is not necessary, it is done to avoid the namespace definition in every item.
Element root = element;
while (root.getParent()!=null && root.getParent() instanceof Element) {
root = (Element) element.getParent();
}
root.addNamespaceDeclaration(SAMPLE_NS);
SampleModuleI fm = (SampleModule)module;
if (fm.getBar() != null) {
element.addContent(generateSimpleElement("bar", fm.getBar()));
}
List foos = fm.getFoos();
for (int i = 0; i < foos.size(); i++) {
element.addContent(generateSimpleElement("foo",foos.get(i).toString()));
}
if (fm.getDate() != null) {
element.addContent(generateSimpleElement("date", DateParser.formatW3CDateTime(fm.getDate())));
}
}
protected Element generateSimpleElement(String name, String value) {
Element element = new Element(name, SAMPLE_NS);
element.addContent(value);
return element;
}
}
+------+
*Configuration to make Rome process Sample Module in feeds
The last step is to setup the configuration file to indicate to Rome how and when to use the Sample Module parser and generator.
The configuration is stored in a Properties file, 'rome.properties', that has to be in the root of the classpath or JAR where the Sample Module bean, parser and generator classes are.
You must indicate the syndication feed formats (ie RSS 1.0) that must be aware of the Sample Module. You must indicate if the Sample Module is available for feed or item elements, or for both. You must indicate both the parser and the generator classes.
Following is the 'rome.properties' file for the Sample Module, it's defined for RSS 1.0 only, for both feed and item elements.
+------+
# Parsers for RSS 1.0 feed modules
#
rss_1.0.feed.ModuleParser.classes=com.sun.syndication.samples.module.SampleModuleParser
# Parsers for RSS 1.0 item modules
#
rss_1.0.item.ModuleParser.classes=com.sun.syndication.samples.module.SampleModuleParser
# Generators for RSS 1.0 feed modules
#
rss_1.0.feed.ModuleGenerator.classes=com.sun.syndication.samples.module.SampleModuleGenerator
# Generators for RSS_1.0 entry modules
#
rss_1.0.item.ModuleGenerator.classes=com.sun.syndication.samples.module.SampleModuleGenerator
+------+
If you are defining more than one module, indicate the parser and generator implementation classes separated by commas or spaces.
*Using the Sample Module from the SyndFeed beans
They will be there, just use them. You may get the SampleModule bean using the getModule(String Uri) method of the SyndFeed bean and the SyndEntry bean.
Adding or replacing a syndication feed parser, generator or converter goes along the same lines of what it has been explained in the tutorial for modules. This is explained in the {{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04Plugins}Rome Plugins Mechanism}} topic.

146
src/site/apt/HowRomeWorks/RomeV0.4TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.apt Normal file
View file

@ -0,0 +1,146 @@
-----
Rome v0.4 Tutorial, Using Rome to aggregate many syndication feeds into a single one
-----
mkurz
-----
2011-08-14 14:57:11.190
-----
Rome v0.4 Tutorial, Using Rome to aggregate many syndication feeds into a single one
<<Software requirements:>> J2SE 1.4\+, JDOM 1.0 and Rome 0.4.
Rome represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeed interface. The SyndFeed interfaces and its properties follow the Java Bean patterns. The default implementations provided with Rome are all lightweight classes.
Rome includes parsers to process syndication feeds into SyndFeed instances. The SyndFeedInput class handles the parsers using the correct one based on the syndication feed being processed. The developer does not need to worry about selecting the right parser for a syndication feed, the SyndFeedInput will take care of it by peeking at the syndication feed structure. All it takes to read a syndication feed using Rome are the following 2 lines of code:
+------+
SyndFeedInput input = new SyndFeedInput();
SyndFeed feed = input.build(new XmlReader(feedUrl));
+------+
The first line creates a SyndFeedInput instance that will work with any syndication feed type (RSS and Atom versions). The second line instructs the SyndFeedInput to read the syndication feed from the InputStream of a URL pointing to the feed. The XmlReader is a character based Reader that resolves the encoding following the HTTP MIME types and XML rules for it. The SyndFeedInput.build() method returns a SyndFeed instance that can be easily processed.
Rome also includes generators to create syndication feeds out of SyndFeed instances. The SyndFeedOutput class does this generation. The SyndFeedOutput will generate a syndication feed of the feed type indicated by the SyndFeed object being output. The following two lines of code show how to create a syndication feed output from a SyndFeed instance:
+------+
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,new PrintWriter(System.out));
+------+
The first line creates a SyndFeedOutput instance that will produce syndication feeds. It can output feeds of any type (rss_0.9, rss_0.91, rss_0.92, rss_0.93, rss_0.94, rss_1.0, rss_2.0 & atom_0.3), the SyndFeed feedType property indicates the type. The second line writes the SyndFeed as a syndication feed into the application's output.
SyndFeed instances can also be created and populated within the code. For example:
+------+
SyndFeed aggrFeed = new SyndFeedImpl();
aggrFeed.setFeedType("rss_1.0");
aggrFeed.setTitle("Aggregated Feed");
aggrFeed.setDescription("Anonymous Aggregated Feed");
aggrFeed.setAuthor("anonymous");
aggrFeed.setLink("http://www.anonymous.com");
+------+
The snipped of code above creates a SyndFeed instance using the default implementation provided by Rome, sets the feed type to RSS 1.0, sets the title, description, author and link properties of the feed.
SyndFeed properties can be modified, assigned to other SyndFeed instances, removed, etc. It's important to remember that the getters/setters semantics defined for all SyndFeed properties (and properties of its properties) is a copy by reference, not by value. In other words if you alter the property of a SyndFeed property you are altering the SyndFeed. Or, another example, if you assign the list of entries of one SyndFeed instance to another SyndFeed isntance and then you modify the list or any of the entries in the list, you are modifying the entries of both SyndFeed instances.
The following lines of code show how to copy the entries of a SyndFeed instance being read (inFeed) into a SyndFeed instance being created within the application (feed):
+------+
package com.sun.syndication.samples;
import java.net.URL;
import java.io.InputStreamReader;
import java.io.PrintWriter;
import java.util.List;
import java.util.ArrayList;
import com.sun.syndication.feed.synd.SyndFeed;
import com.sun.syndication.feed.synd.SyndFeedImpl;
import com.sun.syndication.io.SyndFeedOutput;
import com.sun.syndication.io.SyndFeedInput;
import com.sun.syndication.io.XmlReader;
/**
* It aggregates a list of RSS/Atom feeds (they can be of different types)
* into a single feed of the specified type.
* <p>
* @author Alejandro Abdelnur
*
*/
public class FeedAggregator {
public static void main(String[] args) {
boolean ok = false;
if (args.length>=2) {
try {
String outputType = args[0];
SyndFeed feed = new SyndFeedImpl();
feed.setFeedType(outputType);
feed.setTitle("Aggregated Feed");
feed.setDescription("Anonymous Aggregated Feed");
feed.setAuthor("anonymous");
feed.setLink("http://www.anonymous.com");
List entries = new ArrayList();
feed.setEntries(entries);
for (int i=1;i<args.length;i++) {
URL inputUrl = new URL(args[i]);
SyndFeedInput input = new SyndFeedInput();
SyndFeed inFeed = input.build(new XmlReader(inputUrl));
entries.addAll(inFeed.getEntries());
}
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,new PrintWriter(System.out));
ok = true;
}
catch (Exception ex) {
System.out.println("ERROR: "+ex.getMessage());
}
}
if (!ok) {
System.out.println();
System.out.println("FeedAggregator aggregates different feeds into a single one.");
System.out.println("The first parameter must be the feed type for the aggregated feed.");
System.out.println(" [valid values are: rss_0.9, rss_0.91, rss_0.92, rss_0.93, ]");
System.out.println(" [ rss_0.94, rss_1.0, rss_2.0 & atom_0.3 ]");
System.out.println("The second to last parameters are the URLs of feeds to aggregate.");
System.out.println();
}
}
}
+------+

105
src/site/apt/HowRomeWorks/RomeV0.4TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.apt Normal file
View file

@ -0,0 +1,105 @@
-----
Rome v0.4 Tutorial, Using Rome to convert a syndication feed from one type to another
-----
mkurz
-----
2011-08-14 14:53:11.220
-----
Rome v0.4 Tutorial, Using Rome to convert a syndication feed from one type to another
<<Software requirements:>> Synd J2SE 1.4\+, JDOM 1.0 and Rome 0.4.
Rome represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeed interface. The SyndFeed interfaces and its properties follow the Java Bean patterns. The default implementations provided with Rome are all lightweight classes.
Rome includes parsers to process syndication feeds into SyndFeed instances. The SyndFeedInput class handles the parsers using the correct one based on the syndication feed being processed. The developer does not need to worry about selecting the right parser for a syndication feed, the SyndFeedInput will take care of it by peeking at the syndication feed structure. All it takes to read a syndication feed using Rome are the following 2 lines of code:
+------+
SyndFeedInput input = new SyndFeedInput();
SyndFeed feed = input.build(new XmlReader(feedUrl));
+------+
The first line creates a SyndFeedInput instance that will work with any syndication feed type (RSS and Atom versions). The second line instructs the SyndFeedInput to read the syndication feed from the InputStream of a URL pointing to the feed. The XmlReader is a character based Reader that resolves the encoding following the HTTP MIME types and XML rules for it. The SyndFeedInput.build() method returns a SyndFeed instance that can be easily processed.
Rome also includes generators to create syndication feeds out of SyndFeed instances. The SyndFeedOutput class does this generation. The SyndFeedOutput will generate a syndication feed of the feed type indicated by the SyndFeed object being output. The following two lines of code show how to create a syndication feed output from a SyndFeed instance:
+------+
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,new PrintWriter(System.out));
+------+
The first line creates a SyndFeedOutput instance that will produce syndication feeds. It can output feeds of any type (rss_0.9, rss_0.91, rss_0.92, rss_0.93, rss_0.94, rss_1.0, rss_2.0 & atom_0.3), the SyndFeed feedType property indicates the type. The second line writes the SyndFeed as a syndication feed into the application's output.
Following is the full code for a Java application that reads a syndication feed and converts it to other syndication feed type, writing the converted feed to the application's output.
+------+
package com.sun.syndication.samples;
import java.net.URL;
import java.io.InputStreamReader;
import java.io.PrintWriter;
import com.sun.syndication.feed.synd.SyndFeed;
import com.sun.syndication.io.SyndFeedInput;
import com.sun.syndication.io.SyndFeedOutput;
import com.sun.syndication.io.XmlReader;
/**
* It Converts any RSS/Atom feed type to a an RSS/Atom feed of the
* specified type.
* <p>
* @author Alejandro Abdelnur
*
*/
public class FeedConverter {
public static void main(String[] args) {
boolean ok = false;
if (args.length==2) {
try {
String outputType = args[0];
URL feedUrl = new URL(args[1]);
SyndFeedInput input = new SyndFeedInput();
SyndFeed feed = input.build(new XmlReader(feedUrl));
feed.setFeedType(outputType);
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,new PrintWriter(System.out));
ok = true;
}
catch (Exception ex) {
System.out.println("ERROR: "+ex.getMessage());
}
}
if (!ok) {
System.out.println();
System.out.println("FeedConverter converts between syndication feeds types.");
System.out.println("The first parameter must be the feed type to convert to.");
System.out.println(" [valid values are: rss_0.9, rss_0.91, rss_0.92, rss_0.93, ]");
System.out.println(" [ rss_0.94, rss_1.0, rss_2.0 & atom_0.3 ]");
System.out.println("The second parameter must be the URL of the feed to convert.");
System.out.println();
}
}
}
+------+

204
src/site/apt/HowRomeWorks/RomeV0.4TutorialUsingRomeToCreateAndWriteASyndicationFeed.apt Normal file
View file

@ -0,0 +1,204 @@
-----
Rome v0.4 Tutorial, Using Rome to create and write a syndication feed
-----
mkurz
-----
2011-08-14 14:59:35.761
-----
Rome v0.4 Tutorial, Using Rome to create and write a syndication feed
<<Software requirements:>> J2SE 1.4\+, JDOM 1.0 and Rome 0.4.
Rome represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.feed.synd.SyndFeed interface. The SyndFeed interfaces and its properties follow the Java Bean patterns. The default implementations provided with Rome are all lightweight classes.
Creating a feed with SyndFeed beans consists of creating beans and setting their properties. The following code fragments show how a SyndFeed bean with 3 entries is created.
First the SyndFeed instance is created, the preferred syndication format is set and the feed header info (title, link, description) is also set.
+------+
SyndFeed feed = new SyndFeedImpl();
feed.setFeedType(feedType);
feed.setTitle("Sample Feed (created with Rome)");
feed.setLink("http://rome.dev.java.net");
feed.setDescription("This feed has been created using Rome (Java syndication utilities");
+------+
Then a list for entries is created, entries are created and added to the list. Each entry is set with a title, link, published date and a description. The description for the first entry is plain test, for the third entry is HTML. After each entry is created is added to the list.
+------+
List entries = new ArrayList();
SyndEntry entry;
SyndContent description;
entry = new SyndEntryImpl();
entry.setTitle("Rome v1.0");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome01");
entry.setPublishedDate(DATE_PARSER.parse("2004-06-08"));
description = new SyndContentImpl();
description.setType("text/plain");
description.setValue("Initial release of Rome");
entry.setDescription(description);
entries.add(entry);
...
entry = new SyndEntryImpl();
entry.setTitle("Rome v3.0");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome03");
entry.setPublishedDate(DATE_PARSER.parse("2004-07-27"));
description = new SyndContentImpl();
description.setType("text/html");
description.setValue("<p>More Bug fixes, mor API changes, some new features and some Unit testing</p>"+
"<p>For details check the <a href=\"http://wiki.java.net/bin/view/Javawsxml/RomeChangesLog#RomeV03\">Changes Log</a></p>");
entry.setDescription(description);
entries.add(entry);
+------+
Finally the list with entries is added to the SyndFeed bean.
+------+
feed.setEntries(entries);
+------+
The SyndFeed bean is now ready to be written out to a syndication feed XML document. Note that any of supported syndication formats can be set in the feedType property.
Rome includes generators that allow producing syndication feed XML documents from SyndFeed instances. The SyndFeedOutput class handles the generation of the syndication feed XML documents on any of the supported feed formats (RSS and Atom). The developer does not need to worry about selecting the right generator for a syndication feed, the SyndFeedOutput will take care of it by looking at the information in the SyndFeed bean. All it takes to write a syndication feed XML document using Rome \-assuming you have a SyndFeed bean and a Writer instance\- are the following lines of code:
+------+
SyndFeed feed = ...;
Writer writer = ...;
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,writer);
+------+
First a SyndFeedOutput instance is created, this instance will work with any syndication feed type (RSS and Atom versions). Then the feed and the writer are given to the SyndFeedOutput instance, the SyndFeedOutput will write the syndication feed XML document represented by the SyndFeed bean to the Writer stream.
Following is the full code for a Java application that creates a syndication feed and writes it to a file in the specified syndication format.
+------+
package com.sun.syndication.samples;
import com.sun.syndication.feed.synd.*;
import com.sun.syndication.io.SyndFeedOutput;
import java.io.FileWriter;
import java.io.Writer;
import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.List;
/**
* It creates a feed and writes it to a file.
* <p>
*
*/
public class FeedWriter {
private static final DateFormat DATE_PARSER = new SimpleDateFormat("yyyy-MM-dd");
public static void main(String[] args) {
boolean ok = false;
if (args.length==2) {
try {
String feedType = args[0];
String fileName = args[1];
SyndFeed feed = new SyndFeedImpl();
feed.setFeedType(feedType);
feed.setTitle("Sample Feed (created with Rome)");
feed.setLink("http://rome.dev.java.net");
feed.setDescription("This feed has been created using Rome (Java syndication utilities");
List entries = new ArrayList();
SyndEntry entry;
SyndContent description;
entry = new SyndEntryImpl();
entry.setTitle("Rome v1.0");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome01");
entry.setPublishedDate(DATE_PARSER.parse("2004-06-08"));
description = new SyndContentImpl();
description.setType("text/plain");
description.setValue("Initial release of Rome");
entry.setDescription(description);
entries.add(entry);
entry = new SyndEntryImpl();
entry.setTitle("Rome v2.0");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome02");
entry.setPublishedDate(DATE_PARSER.parse("2004-06-16"));
description = new SyndContentImpl();
description.setType("text/plain");
description.setValue("Bug fixes, minor API changes and some new features");
entry.setDescription(description);
entries.add(entry);
entry = new SyndEntryImpl();
entry.setTitle("Rome v3.0");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome03");
entry.setPublishedDate(DATE_PARSER.parse("2004-07-27"));
description = new SyndContentImpl();
description.setType("text/html");
description.setValue("<p>More Bug fixes, mor API changes, some new features and some Unit testing</p>"+
"<p>For details check the <a href=\"http://wiki.java.net/bin/view/Javawsxml/RomeChangesLog#RomeV03\">Changes Log</a></p>");
entry.setDescription(description);
entries.add(entry);
feed.setEntries(entries);
Writer writer = new FileWriter(fileName);
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,writer);
writer.close();
System.out.println("The feed has been written to the file ["+fileName+"]");
ok = true;
}
catch (Exception ex) {
ex.printStackTrace();
System.out.println("ERROR: "+ex.getMessage());
}
}
if (!ok) {
System.out.println();
System.out.println("FeedWriter creates a RSS/Atom feed and writes it to a file.");
System.out.println("The first parameter must be the syndication format for the feed");
System.out.println(" (rss_0.90, rss_0.91, rss_0.92, rss_0.93, rss_0.94, rss_1.0 rss_2.0 or atom_0.3)");
System.out.println("The second parameter must be the file name for the feed");
System.out.println();
}
}
}
+------+

93
src/site/apt/HowRomeWorks/RomeV0.4TutorialUsingRomeToReadASyndicationFeed.apt Normal file
View file

@ -0,0 +1,93 @@
-----
Rome v0.4 Tutorial, Using Rome to read a syndication feed
-----
mkurz
-----
2011-08-14 14:48:33.636
-----
Rome v0.4 Tutorial, Using Rome to read a syndication feed
<<Software requirements:>> J2SE 1.4\+, JDOM 1.0 and Rome 0.4.
Rome represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeed interface. The SyndFeed interfaces and its properties follow the Java Bean patterns. The default implementations provided with Rome are all lightweight classes.
Rome includes parsers to process syndication feeds into SyndFeed instances. The SyndFeedInput class handles the parsers using the correct one based on the syndication feed being processed. The developer does not need to worry about selecting the right parser for a syndication feed, the SyndFeedInput will take care of it by peeking at the syndication feed structure. All it takes to read a syndication feed using Rome are the following 2 lines of code:
+------+
SyndFeedInput input = new SyndFeedInput();
SyndFeed feed = input.build(new XmlReader(feedUrl));
+------+
The first line creates a SyndFeedInput instance that will work with any syndication feed type (RSS and Atom versions). The second line instructs the SyndFeedInput to read the syndication feed from the char based input stream of a URL pointing to the feed. The XmlReader is a character based Reader that resolves the encoding following the HTTP MIME types and XML rules for it. The SyndFeedInput.build() method returns a SyndFeed instance that can be easily processed.
The default SyndFeed implementation has a detailed and clear toString() implementation. The following line just prints it to the application's output.
+------+
System.out.println(feed);
+------+
Following is the full code for a Java application that reads a syndication feed and prints the SyndFeed bean to the application's output.
+------+
package com.sun.syndication.samples;
import java.net.URL;
import java.io.InputStreamReader;
import com.sun.syndication.feed.synd.SyndFeed;
import com.sun.syndication.io.SyndFeedInput;
import com.sun.syndication.io.XmlReader;
/**
* It Reads and prints any RSS/Atom feed type.
* <p>
* @author Alejandro Abdelnur
*
*/
public class FeedReader {
public static void main(String[] args) {
boolean ok = false;
if (args.length==1) {
try {
URL feedUrl = new URL(args[0]);
SyndFeedInput input = new SyndFeedInput();
SyndFeed feed = input.build(new XmlReader(feedUrl));
System.out.println(feed);
ok = true;
}
catch (Exception ex) {
ex.printStackTrace();
System.out.println("ERROR: "+ex.getMessage());
}
}
if (!ok) {
System.out.println();
System.out.println("FeedReader reads and prints any RSS/Atom feed type.");
System.out.println("The first parameter must be the URL of the feed to read.");
System.out.println();
}
}
}
+------+

362
src/site/apt/HowRomeWorks/UnderstandingTheRomeCommonClassesAndInterfaces.apt Normal file
View file

@ -0,0 +1,362 @@
-----
Understanding the Rome common classes and interfaces
-----
mkurz
-----
2011-08-14 17:31:39.284
-----
Understanding the Rome common classes and interfaces
The Rome common package contains a set of Java classes that provide support for all the basic features Java Beans commonly must have: toString, equals, hashcode and cloning. There is also a simple enumeration base class (missing Java 5.0 already).
By implementing or extending the common classes and interfaces Beans don't have to hand code these functions. This greatly simplifies things when Beans have several properties, collection properties and composite properties.
The common classes use Java Bean instrospection on the properties of the classes extending and using them. This is done recursively on all properties.
All Rome Beans (interfaces and default implementations) leverage and use these classes and interfaces defined in the common package.
Ideally all this classes and interface should be part of a general component outside of Rome as they are not syndication specific (something like a commons\-bean component if we use Jakarta Commons naming). They cannot be hidden in an implementation package as Rome public API uses them.
*ToString and ToStringBean
Beans implementing the ToString interface must implement the toString(String prefix) method. This method must print the bean properties names and values, one per per line, separating the name and value with an '\=' sign and prefixing the name with the given prefix parameter using the same notation used in the JSP expression language used in JSTL and in JSP 2.0. This must be done recursively for all array, collection and ToString properties.
The ToStringBean class provides an implementation of the ToString interface with the defined behavior. The ToStringBean constructor takes the class definition the ToStringBean class should use for properties scanning \-using instrospection\- for printing, normally it is the class of the Bean using the ToStringBean. Beans leveraging the ToStringBean implementation can do it using two different patterns.
*Extending ToStringBean
+------+
public class MyBean extend ToStringBean {
public MyBean() {
super(MyBean.class);
}
public Foo getFoo() { ... }
public void setFoo(Foo foo) { ... }
public String getName() { ... }
public void setName(String name) { ... }
public List getValues() { ... }
public void setValues(List values) { ... }
}
+------+
**Using a ToStringBean in delegation mode
+------+
public class MyBean implements ToString {
public Foo getFoo() { ... }
public void setFoo(Foo foo) { ... }
public String getName() { ... }
public void setName(String name) { ... }
public List getValues() { ... }
public void setValues(List values) { ... }
public String toString(String prefix) {
ToStringBean tsBean = new ToStringBean(MyBean.class,this);
return tsBean.toString(prefix);
}
public String toString() {
return toString("myBean");
}
}
+------+
*EqualBean
The EqualsBean class provides a recursive introspetion\-based implementation of the equals() and hashCode() methods working on the Bean properties. The EqualsBean constructor takes the class definition that should be properties scanned (using introspection) by the equals() and thehashCode() methods. The EqualsBean class works on array, collection, bean and basic type properties. Java Beans leveraging the EqualsBean implementation can do it using two different patterns.
**Extending EqualsBean
+------+
public class MyBean extend EqualsBean {
public MyBean() {
super(MyBean.class);
}
public Foo getFoo() { ... }
public void setFoo(Foo foo) { ... }
public String getName() { ... }
public void setName(String name) { ... }
public List getValues() { ... }
public void setValues(List values) { ... }
}
+------+
**Using a EqualsBean in delegation mode
+------+
public class MyBean implements ToString {
public Foo getFoo() { ... }
public void setFoo(Foo foo) { ... }
public String getName() { ... }
public void setName(String name) { ... }
public List getValues() { ... }
public void setValues(List values) { ... }
public boolean equals(Object obj) {
EqualsBean eBean = new EqualsBean(MyBean.class,this);
return eBean.beanEquals(obj);
}
public int hashCode() {
EqualsBean equals = new EqualsBean(MyBean.class,this);
return equals.beanHashCode();
}
}
+------+
*CloneableBean
The CloneableBean class provides a recursive introspetion\-based implementation of the clone() method working on the Bean properties. The CloneableBean class works on array, collection, bean and basic type properties. Java Beans leveraging the CloneableBean implementation can do it using two different patterns.
**Extending CloneableBean
+------+
public class MyBean extend CloneableBean {
public Foo getFoo() { ... }
public void setFoo(Foo foo) { ... }
public String getName() { ... }
public void setName(String name) { ... }
public List getValues() { ... }
public void setValues(List values) { ... }
}
+------+
**Using a CloneableBean in delegation mode
+------+
public class MyBean implements Cloneable {
public Foo getFoo() { ... }
public void setFoo(Foo foo) { ... }
public String getName() { ... }
public void setName(String name) { ... }
public List getValues() { ... }
public void setValues(List values) { ... }
public Object clone() {
CloneableBean cBean = new CloneableBean(this);
return cBean.beanClone();
}
}
+------+
By default, the CloneableBean copies all properties of the given object. It also supports an ignore\-properties set, the property names in this set will not be copied to the cloned instance. This is useful for cases where the Bean has convenience properties (properties that are actually references to other properties or properties of properties). For example SyndFeed and SyndEntry beans have convenience properties, publishedDate, author, copyright and categories all of them mapped to properties in the DC Module.
*ObjectBean
The ObjectBean is a convenience bean providing ToStringBean, EqualsBean and CloneableBean functionality support. Also, ObjectBeans implements the Serializable interface making the beans serializable if all its properties are. Beans extending ObjectBean get toString(), equals(), hashCode() and clone() support as defined above.
And example of using the ObjectBean class is:
+------+
public class MyBean extends ObjectBean {
public MyBean() {
super(MyBean.class);
}
public Foo getFoo() { ... }
public void setFoo(Foo foo) { ... }
public String getName() { ... }
public void setName(String name) { ... }
public List getValues() { ... }
public void setValues(List values) { ... }
}
+------+
*Enum
The Enum is an enumeration base class \[Too bad Java 5.0 is not here yet (Aug/16/2004)\] with equals(), hashCode(), toString(), clone() and serialization support. When used as properties of Beans implementing any of the above function it provides a seamless integration.
And example of using the EnumBean class is:
+------+
public static class Day extends Enum {
private Day(String name) {
super(name);
}
public static final Day SUNDAY = new Day("sunday");
public static final Day MONDAY = new Day("monday");
public static final Day TUESDAY = new Day("tuesday");
public static final Day WEDNESDAY = new Day("wednesday");
public static final Day THURSDAY = new Day("thursday");
public static final Day FRIDAY = new Day("friday");
public static final Day SATURDAY = new Day("saturday");
}
+------+
*CopyFrom
The CopyFrom interface defines functionality similar to a deep cloning. The difference with the clone() method (besides the deep cloning requirements) is that the object to be the copy of the original one has to be explicitly created and it is this object the one that triggers the deep copying process. Implemetations of the CopyFrom interface should work propertly on arrays, collections, CopyFrom and basic type properties.
Using CopyFrom objects enables copying data between different implementations of a given interface without these implementation having to know about each other.
CopyFrom is unidirectional. A class implementing the CopyFrom knows how to extract properties from the given class (commonly having an interface in common).
A simple example using the CopyFrom interface is:
+------+
public interface Foo extends CopyFrom {
public void setName(String name);
public String getName();
public void setValues(Set values);
public Set getValues();
}
public class FooImplA implements Foo {
private String _name;
private Set _values;
public void setName(String name) {
_name = name;
}
public String getName() {
return _name;
}
public void setValues(Set values) {
_values = values;
}
public Set getValues() {
return _values;
}
public void copyFrom(Object obj) {
Foo other = (Foo) obj;
setName(other.getName());
setValues(new HashSet(other.getValues());
}
public Class getInterface() {
return Foo.class;
}
}
public class FooImplB implements Foo {
private Map _data;
public FooImplB() {
_data = new HashMap();
}
public void setName(String name) {
_data.put("name",name);
}
public String getName() {
return (String) _data.get("name");
}
public void setValues(Set values) {
_data.put("values",values);
}
public Set getValues() {
return (Set) _data.get("values");
}
public void copyFrom(Object obj) {
Foo other = (Foo) obj;
setName(other.getName());
setValues(new HashSet(other.getValues());
}
public Class getInterface() {
return Foo.class;
}
}
+------+
A use case for the CopyFrom functionality is a Java Bean implementation of an interface and a persistency implementation (such as Hibernate) of the the same interface that may add extra persistency related properties to the bean (ie, the 'Id' property as the persistency layer primary key).
For bean, array and collection properties the bean being invoked which copyFrom() method is invoked is responsible for those properties.
For properties implementing the CopyFrom interface, the bean must create a property instance implementing the interface returned by the getInterface() method. This allows the bean doing the copyFrom() to handle specialized subclasses of property elements propertly. This is also applicacle to array and collection properties. The 'modules' property of the SyndFeed and SyndEntry beans is a use case of this feature where the copyFrom() invocation must create different beans subclasses for each type of module, the getInteface() helps to find the right implementation.

97
src/site/apt/HowRomeWorks/index.apt Normal file
View file

@ -0,0 +1,97 @@
-----
How Rome works
-----
mkurz
-----
2011-08-16 03:49:43.191
-----
How Rome works
<<Dave Johnson (>><<{{{http://www.rollerweblogger.org/}The Roller Weblogger}}>><<) has written a very nice blog>> <<{{{http://www.rollerweblogger.org/page/roller/20040808#how_rome_works}How Rome Works}}>> <<describing (as the title says) how Rome works. With his permission we are adding it to Rome documentation.>>
I spent some time exploring the new {{{http://rome.dev.java.net/}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 {{{http://rome.dev.java.net/apidocs/0_4/overview\-summary.html}Rome 0.4 Javadocs}}.
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 {{{http://www.xml.com/pub/a/2003/01/22/dive\-into\-xml.html}Pilgrim\-style liberal XML parsing}}. If a Newsfeed is not valid XML, then Rome will fail. Perhaps, as {{{http://www.peerfear.org/rss/permalink/2003/01/23/1043368363\-Smart_Parsing__Not_RSS_Parsing.shtml}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:
[HowRomeWorks.png]
[[1]] Your code calls {{{http://rome.dev.java.net/apidocs/0_4/com/sun/syndication/io/SyndFeedInput.html}SyndFeedInput}} to parse a Newsfeed, for example (see also {{{./RomeV0.4TutorialUsingRomeToReadASyndicationFeed.html}Using Rome to read a syndication feed}}):
+------+
URL feedUrl = new URL("file:blogging-roller.rss");
SyndFeedInput input = new SyndFeedInput();
SyndFeed feed = input.build(new InputStreamReader(feedUrl.openStream()));
+------+
[[1]] SyndFeedInput delegates to WireFeedInput to do the actual parsing.
[[1]] {{{http://rome.dev.java.net/apidocs/0_4/com/sun/syndication/io/WireFeedInput.html}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.
[[1]] The appropriate parser parses the Newsfeed parses the feed, using {{{http://www.jdom.org/}JDom}}, into a {{{http://rome.dev.java.net/apidocs/0_4/com/sun/syndication/feed/WireFeed.html}WireFeed}}. If the Newsfeed is in an RSS format, the the WireFeed is of class {{{http://rome.dev.java.net/apidocs/0_4/com/sun/syndication/feed/rss/Channel.html}Channel}} and contains Items, Clouds, and other RSS things from the {{{http://rome.dev.java.net/apidocs/0_4/com/sun/syndication/feed/rss/package\-summary.html}com.sun.syndication.feed.rss}} package. Or, on the other hand, if the Newsfeed is in Atom format, then the WireFeed is of class {{{http://rome.dev.java.net/apidocs/0_4/com/sun/syndication/feed/atom/Feed.html}Feed}} from the {{{http://rome.dev.java.net/apidocs/0_4/com/sun/syndication/feed/atom/package\-summary.html}com.sun.syndication.atom}} package. In the end, WireFeedInput returns a WireFeed.
[[1]] 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.
[[1]] {{{http://rome.dev.java.net/apidocs/0_4/com/sun/syndication/feed/synd/SyndFeed.html}SyndFeedImpl}} uses a Converter to convert between the format specific WireFeed representation and a format\-independent SyndFeed.
[[1]] 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 {{{./RomeV0.4TutorialDefiningACustomModuleBeanParserAndGenerator.html}define your own custom modules}} too.
Rome also supports {{{./RomeV0.4TutorialUsingRomeToCreateAndWriteASyndicationFeed.html}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.4 Tutorials, here is the full list from the {{{../index.html}Rome Wiki}}:
[[1]] {{{./RomeV0.4TutorialUsingRomeToReadASyndicationFeed.html}Using Rome to read a syndication feed}}
[[1]] {{{./RomeV0.4TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html}Using Rome to convert a syndication feed from one type to another}}
[[1]] {{{./RomeV0.4TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html}Using Rome to aggregate many syndication feeds into a single one}}
[[1]] {{{./RomeV0.4TutorialUsingRomeToCreateAndWriteASyndicationFeed.html}Using Rome to create and write a feed}}
[[1]] {{{./RomeV0.4TutorialDefiningACustomModuleBeanParserAndGenerator.html}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.

99
src/site/apt/HowToBuildRome.apt Normal file
View file

@ -0,0 +1,99 @@
-----
How to build Rome?
-----
mkurz
-----
2011-08-14 17:45:08.966
-----
How to build Rome?
Rome is built using mighty {{{http://maven.apache.org/}Maven}}! This is why these instructions are so short:\-)
If you don't want to build Rome we'd suggest you download a binary build:\-)
*Check out from Subversion
See {{{https://rometools.jira.com/source/browse/ROME}Version Control}} for access intructions and to browse the source from your browser.
Check out the tag version\-0\-1 for version 0.1. Else checkout the trunk for the development version.
*Setup maven
See {{{http://maven.apache.org/run\-maven/index.html}Installing Maven}} for details.
Maven automatically downloads dependencies of a project from an online repository.
*Build rome.jar
At the command prompt type:
+------+
> mvn jar:jar
+------+
This will build
+------+
rome/target/rome-VERSION.jar
+------+
You're good to go.
**Build a full binary distribution
+------+
> mvn
+------+
**Build the project site
+------+
> mvn site
+------+
*For Rome developers
**Work on Rome using Eclipse
+------+
> mvn eclipse:eclipse
+------+
will setup the Eclipse project for you.
We don't use the site:deploy or dist:deploy targets yet since java.net is not very maven\-friendly yet:\-)

57
src/site/apt/PreservingWireFeeds.apt Normal file
View file

@ -0,0 +1,57 @@
-----
Preserving WireFeeds
-----
mkurz
-----
2011-08-14 16:20:59.295
-----
Preserving WireFeeds
WireFeeds will be preserved if the property preserveWireFeed is set on the SyndFeedInput object it is built from:
+------+
SyndFeedInput in = new SyndFeedInput();
in.setPreserveWireFeed(true);
SyndFeed syndFeed = in.build(..);
WireFeed wireFeed = syndFeed.originalWireFeed();
+------+
Atom/RSS Entry/Item objects are also available from SyndEntry objects if the WireFeed is preserved:
+------+
Object obj = syndEntry.getWireEntry();
if (obj != null && obj instanceof Entry) {
// it is an Atom Entry object
// do Atom specific stuff, eg:
Entry entry = (Entry) o;
System.out.println(entry.getRights());
} else if (obj != null && obj instanceof Item) {
// it is a RSS Item object
// do RSS specific stuff eg:
Item item = (Item) o;
System.out.println(item.getComments());
}
+------+
The Fetcher can be set to preserve WireFeeds by setting the preserveWireFeed property to true:
+------+
feedFetcher.setPreserveWireFeed(true);
+------+
\-\- Main.nicklothian \- 11 Mar 2009

210
src/site/apt/ProductsOrSitesPoweredByROME.apt Normal file
View file

@ -0,0 +1,210 @@
-----
Products or sites powered by ROME
-----
sbasegmez
-----
2013-03-14 07:44:37.389
-----
Products or sites powered by ROME
If your site or project is powered by ROME, please take the time to write a short testimonial on this wiki page, or send a mail to {{{mailto:users@rome.dev.java.net.}users@rome.dev.java.net.}} Feel free to use our "Powered by ROME" badges in your work. (Several badge variations are available at the bottom of this page.)
*Open Source using ROME
* {{{http://firenze.berlios.de/}Firenze}}\
Firenze is a free Java based open source command line podcast receiver. It is powered by the ROME syndication framework. With Firenze you can easily subscribe to your favorite Podcast feeds and reveive them.
* {{{http://fnr.sourceforge.net/}Feed'n Read}}\
Feed'n Read (FnR) is a free Java based open source newsfeed reader. It is powered by the ROME syndication framework and therefore supports all current formats (RSS 0.90, 0.91, 0.92, 0.93, 0.94, 1.00, 2.00, ATOM 0.30 and 1.00). It disposes of an intuitive, fast and responsive user interface using the eclipse Rich Client Platform (RCP), i.e. JFace and SWT. Thus it combines the platform independent Java world on one hand with a fast native user interface on the other hand.
* {{{http://tudu.sourceforge.net/}Tudu Lists}}\
An AJAXian Todo Lists manager. We moved from our hand\-made solution to ROME with great pleasure \- it was fast and easy, and the overall performance is very good (11 ms per request in average today). You can try it out on our live site at {{{http://tudu.ess.ch/}http://tudu.ess.ch}}.
* {{{http://snipsnap.org/}SnipSnap}}
* {{{http://www.rollerweblogger.org/page/project}Roller Weblogger and Aggregator}}\
Roller is a weblog server. In Roller 1.1 there is a new aggregator feature, called PlanetRoller, based on ROME and ROME fetcher. Dave Johnson, who created Roller, {{{http://rollerweblogger.org/page/roller/20050213#rome_texen_planet_roller}created PlanetRoller in a couple of days}}, leveraging ROME and ROME fetcher to do all the hard work. You can try out at {{{http://www.rollerweblogger.org/planet/roller.html}PlanetRoller}}.
* {{{http://incubator.apache.org/activemq/}ActiveMQ}}\
Apache ActiveMQ is a fast open source JMS 1.1 provider and Message Fabric supporting clustering, peer networks, discovery, TCP, SSL, multicast, persistence, XA and integrates seamlessly into J2EE 1.4 containers, light weight containers and any Java application. ActiveMQ is released under the Apache 2.0 License. \
Currently ActiveMQ is using Rome to be able to {{{http://docs.codehaus.org/display/ACTIVEMQ/RSS\+and\+Atom}browse message queues}} (with or without filters applied) as RSS or Atom feeds.
* {{{http://www.xwiki.org/}XWiki}}
* {{{http://www.thauvin.net/mobitopia/mobibot/}mobibot}}
* {{{http://sourceforge.net/projects/stat4j/}stat4j}}\
Used ROME to create an RSS/ATOM Log4j Appender. Read more about it {{{http://www.jroller.com/comments/laraDAB?anchor\=rss_atom_log4j_appender}here}}.
* {{{http://www.spotdev.net/}SPOT Manager}}\
SPOT Manager uses ROME to parse RSS feeds and send them to your MSN Direct wristwatch! Learn about MSN Direct {{{http://www.msndirect.com/}here.}} Download the program from {{{http://www.spotdev.net/}SPOTDev.net}}.
* {{{http://logdistiller.sf.net/}LogDistiller}}\
LogDistiller is an extensible tool to merge and sort logs : reports can be stored in a feed file thanks to Rome.
* {{{http://openvision.tv/}ION Internet Video Console}}\
The I/ON Internet Video Console fuses together leading technologies into one simple media player, connecting you directly to the video you want. Avoid the ads, pop\-ups, and spyware that come with watching video in a browser and watch the web. ROME powers our RSS capabilities. Learn more and download {{{http://openvision.tv/}here}}.
* {{{http://code.google.com/p/blog\-mover}Blog Mover}}\
Blog Mover's goal is allowing your blog moving freely between each BSP(Blog Service Provider). Learn more and try it {{{http://blog\-mover.redv.com/}here}}.
* {{{http://scarab.tigris.org/}Scarab}}\
The goal of the Scarab project is to build a highly customisable Artifact tracking system. It's distributed under a BSD/Apache style license.
* {{{http://ozmozr.org/}Ozmozr}}\
Ozmozr is a website for online learning communities being developed by the {{{http://www.cosl.usu.edu/}Center for Open Sustainable Learning}} at {{{http://www.usu.edu/}Utah State University}}. In ozmozr, users are both content producers and consumers, relying on their social networks to filter and distribute meaningful content. Ozmozr was built to leverage emergent technologies and support social and collaborative information filtering, self\-organization, identity development, and free/open resource\-sharing.
[]
*Open Source Research Prototypes using ROME
* {{{http://www.infosys.tuwien.ac.at/prototype/morse/}MORSE}}\
The {{{http://www.infosys.tuwien.ac.at/prototype/morse/}Model\-Aware Repository and Service Environment}} (MORSE) is a service\-based environment for the storage and retrieval of models and model\-instances at both design\- and runtime. Models, and model\-elements are identified by Universally Unique Identifiers (UUID) and stored and managed in the MORSE repository. The MORSE repository provides versioning capabilities so that models can be manipulated at runtime and new and old versions of the models can be maintained in parallel. MORSE exposes various services to runtime clients and modeling tools. For instance, a {{{http://www.infosys.tuwien.ac.at/m2projects/at.ac.tuwien.infosys.tholmes.morse/rs\-impl/}feed}} reflects the latest changes within the repository.
[]
*Free, Based On Open Standards, using ROME
* {{{http://www.scheduleworld.com/}ScheduleWorld}}
* {{{http://feedpod.dev.java.net/}FeedPod}}
[]
*Commercial using ROME
* {{{http://interactivebrokers.com/}Interactive Brokers TraderWorkstation (TWS)}}\
Interactive Brokers is leading software based broker. IB offers Universal Direct\-Access Trading and sophisticated trade management tools at highly competitive costs to professional traders and investors worldwide. IB is the gateway to trading a broad array of financial instruments \-\- stocks, options, futures, corporate bonds as well as forex \-\- on over 50 exchanges and marketplaces in 14 countries. TraderWorkstation is java\-based trading platform; ROME library is used to fetch, aggregate and visualize news related to securities listed in the application.
* {{{http://weblogs.at/parss/stories/2315/}parss}}\
From the antville guys, that we met at blogtalk 1.0 2 years ago.
* {{{http://www.publicinteractive.com/}Public Interactive}}\
Public Interactive® is the leading integrated Application Service Provider (ASP) of on\-line collaborative tools, community engagement technologies, content syndication services and member and audience relationship management systems for the public broadcasting industry. Rome is used for syndicating news content and Podcasts local published by stations in the Public Interactive network.
* {{{http://www.blog\-city.com/}Blog\-City Ltd}}\
Blog\-City.com has been using ROME for many months now, utilising both the core project and the Fetcher project to allow bloggers to run their own mini\-aggregators within their blog.
* {{{http://www.reger.com/}Reger.com}}\
All blogs running at reger.com include ROME feeds. With the custom ROME module we wrote entry data is included in the RSS feeds. DataBlogging allows people to append activity\-specific data to each of their entries. In addition to the pre\-built log types (Running Log, Biking Log, Movie Log, etc), users can create custom log types with whatever data fields they need. The module outputs those data fields. Users simply customize their log types, adding and removing fields, and then the RSS feed automatically includes it. An RDDL document for the namespace can be found at{{{http://www.reger.com/about/specs/entrydata.rddl}http://www.reger.com/about/specs/entrydata.rddl}} Thanks again for all of the help and for making ROME great!
* {{{http://techrepublic.com.com/}CNET Networks/TechRepublic.com}}\
CNET Networks uses ROME with an application called the RSS Harvester. The purpose of this application is to harvest a list of predefined RSS/ATOM feeds, saving all new items for each feed in a database. In addition, each feed has an associated keyword that allows for easy surfacing of harvested data. \
Once the feed data has been collected, internal editors can surface links to the harvested data on the TechRepublic website by including a call to a JSP component. This component passes several parameters including the number of items to return, the number of items from a particular site and an associated keyword. For example, {{{http://techrepublic.com.com/2001\-10591\-0.html}http://techrepublic.com.com/2001\-10591\-0.html}} (see the section "More on ...") we surface related articles. \
We are also using Rome for Re\-Blogging on TechRepublic.com. Users can start their own blogs on the site as well as choose to import an RSS feed from an existing blog such as blogger.com. When the user imports an existing blog we use Rome to parse the RSS/ATOM feed then convert it to a TechRepublic blog. Any new blog posts on the external blog are automatically imported to TechRepublic.
* {{{http://www.edmunds.com/insideline/}Edmunds.com Inside Line}}\
We are currently using ROME as our feed generator and as a feed parser. Currently we publish RSS feeds of our latest articles on www.insideline.com, however, we also use it to provide updates between our sites. For example, our community site {{{http://townhall\-talk.edmunds.com/}Townhall}} produces RSS feeds which we then parse using ROME on our {{{http://www.edmunds.com/insideline}Inside Line}} property. Rome has significantly speed up our development times thanks to its clean object model and its ability to generate multiple feed types.
* {{{http://phobos.apple.com/WebObjects/MZStore.woa/wa/viewArtist?artistId\=118405710}HBO Podcasts}} (iTunes Music Store Link)\
HoPE (HBO Podcast Engine) powered by ROME and the iTunes Podcast module. To date has served over 15\-million podcasts for HBO podcast content such as The Sopranos, Real Time with Bill Maher, and Rome
* {{{http://www.dressupyourwedding.com/Article.do}DressUpYourWedding}}
[]
*Sites using ROME
* {{{http://www.yabot.net/}Yabot}}\
Yabot is a news service currently available in five editions (May 2008).
Discovering and implementing ROME made Yabot's feed aggregation faster and easier. In previous versions we rendered the XML our selves but with ROME now doing most of this work developers can focus on presentation and integration features. Thanks!
Mats, co\-founder @ Yabot \-{{{http://www.yabot.net/}http://www.yabot.net}}
* {{{http://www.wasalive.com/}WASALive}}\
Wasalive is a news, blogs and forums search engine. Results are sort by a mix of relevancy and date. Thanks to ROME library, Wasabot fetch and parse more than 70k feeds/days and store 3M posts. Thanks to ROME UTF8 support Wasalive is avalaible in {{{http://ru.wasalive.com/}Russian}}, {{{http://fr.wasalive.com/}French}},{{{http://es.wasalive.com/}Spanish}}, {{{http://en.wasalive.com/}English}}
* {{{http://www.airport\-information.com/}http://www.airport\-information.com}}\
Rome is used to create a RSS feed with news on airports worldwide. The database runs under Tomcat. The Rome library was very helpful and allowed an easy and quick implementation. \-\- Main.airportinformation \- 28 Jan 2008
* {{{http://www.abclinuxu.cz/}http://www.abclinuxu.cz}}\
I use rome in daily production on www.abclinuxu.cz for watching cca 8 feeds and generating cca 60 feeds. After fixing charset related issues (thanks!) it runs smoothly. I am happy that I could remove my old propietary RSS rw code with Rome ... Leos
* {{{http://feeds.my.aol.com/}http://feeds.my.aol.com}}\
The latest My AOL product, a customizable, feed\-driven web application, uses the Rome library to read, manipulate, and normalize RSS, RDF, and Atom feeds. My AOL was built on a very rapid development schedule, and Rome made much of it a lot easier than it otherwise would have been. \-\-Bill Kocik, Sr. Software Engineer, America Online, Inc.
* {{{http://www.backbase.com/}http://www.backbase.com}}\
Rome is used on our site to provide rss feeds for forum threads. Implementation took me something like few hours (including downloading and installation), so needless to say I am very happy. Thanks. m.j.milicevic
* {{{http://oszone.org/}The Open Source Zone}}\
Rome is used to power the {{{http://oszone.org/channels}Planet}} section of The Open Source Zone, where we aggregate the most interesting feeds concerning Open Source. Took very little to implement, thanks to Rome. Rome Fetcher is used too, which is great.
* {{{http://www.rel8r.com/}rel8r.com}}\
rel8r is a tag search and feed aggregator. Rome is used extensively for collecting feeds as well as for publishing all of the aggregated feeds. We love it. \- Travis
* {{{http://newsrack.in/}NewsRack}}\
Several organizations in the social development sector monitor news that is relevant to their work. This is a time\-consuming and laborious process for some groups, especially when the news is monitored, marked, cut, and filed using hard copies of newspapers and magazines. This process is very much the case in India. However, much of this work can be automated using web versions of newspapers and magazines. In this context, the broad goal of this project is to automate news monitoring. \
NewsRack is a tool/service for classifying, filing, and long\-term archiving of news. Users specify filtering rules which are used to select relevant articles from incoming news feeds. The selected articles are then classified into various categories. This process is similar to the process of specifying email filters to pre\-sort incoming mail into various folders. \
NewsRack is currently using Rome. I am looking for developers, so, if this project tickles you, please get in touch! \- Subramanya Sastry
* {{{http://www.rsspress.it/}http://www.rsspress.it}}\
An Italian Rss Aggregator, with a very nice design and layout, very simple to use, with a lot of rss feeds not only in italian language. You can register it and have your personalized homepage with your preferred news.
* {{{http://www.geonames.org/rss\-to\-georss\-converter.html}Geonames RSS to GeoRSS}}\
The Geonames "RSS to GeoRSS Converter" reads the entries of an RSS feed and searches the Geonames Database to find a location for the entry text. If a relevant location is found, its latitude and longitude are added to the RSS feed using the GeoRSS encoding.
* {{{http://www.feedarea.de/}feedarea.de}}\
FeedArea.de is a RSS, Atom and Podcast portal using Rome for handling the feed submissions.
* {{{http://www.podblock.de/}podblock.de}} / {{{http://www.podblock.com/}podblock.com}}\
PodBlock is a podcast portal using Rome for handling the feed submissions.
* {{{http://www.javamix.co.uk/}javaMix.co.uk}}\
javaMix is a java news aggregation website using Rome to find the news.
* {{{http://www.javamix.co.uk/}JavaMix}}\
the latest java news, articles and resources
* {{{http://wirecatch.com/}Wirecatch}}\
Wirecatch is a semantic news aggregator and visualization tool. It uses Rome to grab several news feeds and show connections and relationships between names, concepts and documents.
* {{{http://swiftmob.com/}Swift}}\
Swift imports rss feeds and formats them for mobile devices. Swift also include many other tools for building mobile friendly webpages that will reshape themselves for each phone so the experience for the end user is as good as possible.
* {{{http://devmeat.com/}DevMeat}}\
DevMeat deliver fresh meat for software developers and Rome is TOP cook !
* {{{http://folder2feed.nogoodatcoding.com/}Folder2Feed}}\
Folder2Feed allows users to generate feeds from the contents of local and network folders; providing an easy way to monitor updates to folders of interest for a large audience.
* {{{http://www.podcast.tv/}podcast.tv}}
* {{{http://www.podcast.it/}podcast.it}}
* {{{http://www.podcast.at/}podcast.at}}\
Podcast.tv, podcast.it and podcast.at are podcast directories using Rome for handling the feed submissions and parsing.
* {{{http://collaborationtoday.info/}CollaborationToday.info}}\
Collaboration Today is a news aggregator, also an open source software developed by OpenNTF. This site is for IBM Collaboration Solutions professionals covering news about various IBM products like IBM Connections, IBM Notes/ Domino, IBM WebSphere Portal etc. and cross product topics like mobile, cloud and analytics. Rome is running on background and fetching stories from various sites.
[]
*Powered By ROME Badges Here are badges for use with your ROME\-powered site or software:
* <<Static:>>
* <<Animated:>>
[]
Please copy the image to your own server rather than link to the image on its current host.

60
src/site/apt/ROMEAndMaven2.apt Normal file
View file

@ -0,0 +1,60 @@
-----
ROME and Maven 2
-----
mkurz
-----
2011-08-15 10:53:40.491
-----
ROME and Maven 2
this page is not up to date
Starting with ROME 1.0 RC2, rome jars are deployed on the {{{http://download.java.net/maven/2/}java.net maven repository}}.
In your project you can add this repository by putting the following XML into your pom.xml
+------+
<repository>
<id>maven2-repository.dev.java.net</id>
<name>Java.net Repository for Maven</name>
<url>http://download.java.net/maven/2/</url>
<layout>default</layout>
</repository>
+------+
As of 22, April 2009, the jars are deployed for the following releases:
* ROME 1.0
* ROME Fetcher 1.0
* ROME Modules 0.3.2
[]
To include the Rome 1.0 in your maven2 project:
+------+
<dependency>
<groupId>rome</groupId>
<artifactId>rome</artifactId>
<version>1.0</version>
</dependency>
+------+
\-\- Main.mj_ \- 22 Apr 2009

19
src/site/apt/ROMEAndOSGI.apt Normal file
View file

@ -0,0 +1,19 @@
-----
ROME and OSGI
-----
mkurz
-----
2011-08-15 10:54:49.376
-----
ROME and OSGI
From ROME 1.0 RC2 onwards, the ROME jar includes OSGi information in its manifest.
Note that we have received some reports that ROME plugin classloading may cause problems with OSGi. Setting the system property "rome.pluginmanager.useloadclass" to "true" may help avoid this. See {{{http://java.net/jira/browse/ROME\-118}Issue 118}} for further information.
\-\- Main.nicklothian \- 08 Jan 2009

29
src/site/apt/ROMEDevelopmentProcess.apt Normal file
View file

@ -0,0 +1,29 @@
-----
ROME Development Process
-----
mkurz
-----
2011-08-15 10:38:27.942
-----
ROME Development Process
We're welcoming our first external developer, {{{http://www.mackmo.com/nick/blog/}Nick Lothian}} today, so we thought it would be good to set a few basic rules for this project. We don't want to be too formal, since we're still alpha, and trust our developer's common sense to "do the right thing".
* Please before commiting anything send an email in the rome developer lists to explain what you want to do
* When you create some new code, please javadoc it, and unit tests are welcome
* If your code involves new functionality for end users, please document it on the wiki.
* and update the {{{./ChangeLog.html}RomeChangesLog}}
* I think that's it: Welcome to Rome
[]
\-\- {{{http://wiki.java.net/twiki/bin/view/Main/PatrickChanezon}PatrickChanezon}} \- 17 Jun 2004

386
src/site/apt/ROMEDevelopmentProposals/ROME21stProposalJune10th2006NOTCURRENT.apt Normal file
View file

@ -0,0 +1,386 @@
-----
ROME2 1st Proposal (June 10th 2006) NOT CURRENT
-----
mkurz
-----
2011-08-15 11:12:21.744
-----
ROME2 1st Proposal (June 10th 2006) NOT CURRENT
It has been 2 years since ROME started and along the way we've fixed, improved, enhanced and changed the API and the implementation. We've had to address things we did not think at first, we have to add support for specifications that were not around when ROME started, doing that has not being a hard task. The best indicator we've done a fair job with ROME is adoption.
Some cracks are starting to appear, mistakes in the design (such as overloading the use of DCModule), a bit of implementation over\-engineering (such as the home grown bean\-introspector and the <<smart>> ObjectBean & co classes), a more complex than needed API (the existence of 2 abstraction levels for feed, Synd and Wire beans).
This proposal attempts to address the problems and limitations we currently have with ROME.
*Backwards Compatibility, Support and Upgrade
ROME2 will change the API breaking backwards compatibility (after all we are an Open Source Project and that is what they do best).
We will maintain ROME 1.0 (bugfixing only) for 1 year to allow a smooth transition for all ROME users. We will also prepare migration/upgrade tips (based on our own experience) for the ROME community.
*Leveraging New Language Features
ROME2 will make use of Generics to type collections in its beans. It will also use the <<enum>> construct when applicable.
*Minimum Number of Dependencies
ROME2 will implement its core competency (Atom and RSS parsing, generation and manipulation), it will leverage other components as much as possible but it will focus, as ROME, in being as lean as possible not only in its code by in its dependencies (keeping them down to a reasonable minimum).
*One Abstraction Level, 2 Models
ROME2 will not have an abstract representation of feeds (the Synd beans). It will have 2 distinct models, Atom and RSS, both of them first citizens.
ROME2 users will use the model that fits more their needs.
Conversion (automatic and implicit) between the 2 models will be part of ROME2.
*No Interfaces, Pluggable Beans
Interfaces are good, in fact they are great. However, when using them with beans that have to be created by the developer it ads noise to the code. Interfaces are used for all parameters and variables but implementations must be used to create the bean instances thus hard\-coding areas of the application to a specific implementation. Or a factory pattern has to be use throughout the code to hide the implementation, with a side effect of removing clarity from the code.
ROME2 will bring the best of both worlds, it will allow coding such as
+------+
Feed feed = new Feed();
Entry entry1 = new Entry();
Entry entry2 = new Entry();
feed.getEntries().add(entry1);
feed.getEntries().add(entry2);
+------+
While allowing pluggability of the beans implementation. The pluggability will be achieved using a combination of a factory pattern and a self\-proxy patterns, both of them transparent to the ROME2 user.
For example the ROME2 API bean for the Atom feed would be something like:
+------+
public class Feed {
private Feed feed;
public Feed() {
if (this.getClass() == Feed.class) {
feed = BeanFactory.getFactory().create(Feed.class);
}
}
public final Feed getImplementation() {
return feed;
}
public Text getTitle() {
return feed.getTitle();
}
public void setTitle(Text title) {
feed.setTitle(title);
}
...
}
+------+
The ROME2 (default/provided) implementation bean for the Atom feed would be something like:
+------+
public class FeedBean extends Feed {
private Text title;
public Text getTitle() {
return title;
}
public void setTitle(Text title) {
this.title = title;
}
...
}
+------+
ROME2 users will use the ROME2 API bean as plain objects that they are. The ROME2 API beans will delegate all their properties to an instance implementing their corresponding class. This instance will be the implementation bean which is created by the BeanFactory.
To provide alternate implementation beans an alternate BeanFactory has to be provided.
To write an alternate implementation beans the ROME2 API bean has be used as an interface, all property methods have to be overridden, nothing else.
When extending ROME2 API beans, for example providing a new module bean, it is left to the implementor to follow this pattern or to use plain beans for the the additional module.
For cases (they shouldn't be many) that a ROME2 user needs to manipulate the implementation bean, all ROME2 API beans will give access to it via the getImplementation() method.
*Using multiple Bean implementations simultaneously
ROME2 will support the use of multiple implementation beans simultaneously.
A use case could be retrieving a feed from a persistent store (which uses its own implementation beans), retrieving a feed from the internet (using the default implementation beans), merging their entries and producing an output feed, into the persistent store or out to the internet.
ROME2 public API will include the following classes for this purpose:
+------+
public abstract class BeanFactory {
public abstract <T> T create(Class<T> beanClass);
}
public class BeanFactoryInjector {
public static void execute(BeanFactory factory, Runnable runnable) { .. }
}
+------+
When these two classes are not used explicitly ROME2 will use the default BeanFactory that creates default implementation beans.
For alternate implementation beans a BeanFactory has to be provided. This factory will be responsible for creating a complete ROME2 bean family.
The code to create ROME2 beans with an alternate factory will have to be written in the run() method of a Runnable object and it will have to be executed via the BeanFactoryInjector.execute() method.
The created ROME2 beans could be used outside of the Runnable.run() method, because of this ROME2 users have to be aware that it is possible to mix and match implementation beans and that may not always have a happy ending if not thought properly.
*Collection Elements
All collection properties (such as the authors, categories, contributors, links and entries of an Atom feed bean) will only have getter methods in the ROME2 API beans, no setter methods. For example:
+------+
public class Feed {
public List<Person> getAuthors() { ... }
public List<Category> getCategories() { ... }
...
}
+------+
This will ensure that the implementation bean has control on the implementation of the collection being used. This is particularly important to enable alternate implementation beans to fetch data from a repository as the collection is iterated over.
Persistent experts we need your input here.
*Modules
Feeds, both RSS and Atom, are extensible via namespaced elements at feed/channel and entry/item level, these namespace elements are known as modules. Beans supporting modules (feed, channel, entry and item) will all have the following method to support modules.
+------+
public Map<String,Module> getModules() { ... }
+------+
Because modules are uniquely identified by their URI, a Map will be used, the key will be the URI of the module and the value the module itself. As with other ROME2 API bean collection properties, the getModules() property has a getter only, the Map implementation is controlled by the implementation bean.
Module URIs in ROME2, as all the links URLs in the beans, will be Strings thus reducing object creation explosion a bit. For cases that some URI manipulation is required, the JDK URI class should be used.
*Dynamic Modules Support
ROME2 modules design has to ensure it provides simple and comprehensive support for dynamic modules such as SLE and GData.
*Unknown Modules
A special Module subclass, UnknownModule, will serve as placeholder for module data not explicitly processed by ROME2 available parsers/generators. This will allow to consume and re\-export a feed without losing unknown (to ROME2) modules. Each unknown module will be keyed off with its URI in the map of the associated feed, channel, entry or item.
The data of the unknown module will be available as a String. ROME2 users should not use \=UnknownModule\='s data directly, if they need to manipulate that data they should find or implement bean/parser/generator for the module they need to manipulate.
Because unknown modules brings some extra overhead in the parsing and generating process ROME2 will have a property to enable/disable processing of unknown modules.
*The xml:lang Attributes
All ROME2 API beans will have xml:lang attributes, String and enum and primitive types properties won't.
*The xml:base Attributes
The xml:base attribute will not be present in any ROME2 API bean.
It will be the responsibility of the parsers to resolve any relative URL present in the feed at parsing time. Similarly, generators may relativize URLs as a size optimization (for God's sake we are doing XML).
*Conversion between Feed Types
A FeedConverter class will provide conversion from Atom to RSS beans and vice versa, both at feed/channel and entry/item level. All properties, including modules data will be copied, after an conversion the state of the beans will be completely independent.
*Object Class Methods in ROME2 Beans
The equals() and hashCode() methods will not be overridden. All ROME2 beans are mutable, it is not safe to use them as keys of hash structures.
Cloning will not be supported by ROME2 beans, instead they will have a copyFrom() method which is type safe and does a deep copy. Cloning a ROME2 bean will be a two step process, for example:
+------+
Feed feed1 = new Feed();
...
Feed feed2 = new Feed();
feed2.copyFrom(feed1);
+------+
The toString() method in the beans will print the property that most likely identifies the bean plus the class name of the implementation bean. For example for a Feed bean the output of toString() would be:
+------+
[http://foo.com/atom.xml - xxx.rome2.impl.pojo.atom.FeedBean]
+------+
\-\-\+\+ Plugins ClassLoading
Bean implementations, parsers, generators, converters and all pluggable ROME2 components will be loaded using the same classLoader ROME2 core classes are loaded from.
This is to keep simple the handling of them via singletons and their instantiation. Supporting different classLoaders would require complex handling for instantiation, to avoid missing classes and class mismatches.
As an example of how easy things can go sour, imagine ROME2 core classes in the common path of a web\-container and 2 web\-apps adding their own beans/parsers/generators/modules, the singletons managing them are in ROME2 core, managed by the common classLoader, a simple singleton won't cut it. ROME2 core will be small enough that it will not be a memory consumption issue if it is once in each web\-app.
*Parsers and Generators
XML parsing and generation will support stream mode. We may even consider using streaming as the underlaying default implementation even if manipulating a feed bean on its whole in memory. We have to see if how this could be done leveraging Abdera, else using StAX API directly. This also means we may get rid of the JDom dependency.
For example, the streaming version of an Atom parser and generator would be something like:
+------+
public interface AtomReader {
// repeatable operation, returns was has been read from the header so far
Feed readFeed() throws FeedException;
// returns null when reaches the end of the feed
Entry readEntry() throws FeedException;
void close() throws FeedException;
}
public interface AtomWriter {
// if called must be called once and before a write(Entry)
void write(Feed feed) throws FeedException;
// if the first write is for an entry, then the output is an entry document
abstract void write(Entry entry) throws FeedException;
void close() throws FeedException;
}
+------+
As with ROME, in ROME2 Parsers will be as lenient as possible. Generators will be strict.
*Feed Validators
A bean FeedValidator class will verify that a feed or entry bean is valid for a given feed type. Feed generators would use this class to ensure feed correctness.
*Feed Conversion
Conversion from Atom beans to RSS beans and vice versa will be done by a FeedConverter class that would have the following signature:
+------+
public class FeedConverter {
public Feed convertToFeed(Channel channel, boolean processItems) { ... }
public Entry convertToEntry(Item item) { ... }
public Channel convertToChannel(Feed feed, boolean processEntries) { ... }
public Item convertToItem(Entry entry) { ... }
}
+------+
Because the mapping from Atom to RSS elements is sometimes subject do discussion and different requirements the FeedConverter class will be pluggable. It will implement the self\-proxy pattern ROME2 API beans implement.
*Parser and Generator Filters
Manipulation of feeds during parsing and generation at feed/channel and entry/item level will be possible by implementing readers and writers wrappers that work on top of the original reader and writer instances.
This filtering/wrapping could be automated via configuration.
*Sources
* {{{./rome2proto.zip}rome2proto.zip}}
[]

397
src/site/apt/ROMEDevelopmentProposals/ROME22ndProposalJuly18th2006CURRENT.apt Normal file
View file

@ -0,0 +1,397 @@
-----
ROME2 2nd Proposal (July 18th 2006) CURRENT
-----
mkurz
-----
2011-08-15 11:06:23.384
-----
ROME2 2nd Proposal (July 18th 2006) CURRENT
It has been 2 years since ROME started and along the way we've fixed, improved, enhanced and changed the API and the implementation. We've had to address things we did not think at first, we have to add support for specifications that were not around when ROME started, doing that has not being a hard task. The best indicator we've done a fair job with ROME is adoption.
Some cracks are starting to appear, mistakes in the design (such as overloading the use of DCModule), a bit of implementation over\-engineering (such as the home grown bean\-introspector and the <<smart>> ObjectBean & co classes), a more complex than needed API (the existence of 2 abstraction levels for feed, Synd and Wire beans).
This proposal attempts to address the problems and limitations we currently have with ROME.
*Backwards Compatibility, Support and Upgrade
ROME2 will change the API breaking backwards compatibility (after all we are an Open Source Project and that is what they do best).
We will maintain ROME 1.0 (bugfixing only) for 1 year to allow a smooth transition for all ROME users. We will also prepare migration/upgrade tips (based on our own experience) for the ROME community.
*Leveraging New Language Features
ROME2 will make use of Generics to type collections in its beans. It will also use the <<enum>> construct when applicable.
*Minimum Number of Dependencies
ROME2 will implement its core competency (Atom and RSS parsing, generation and manipulation), it will leverage other components as much as possible but it will, as ROME, be as lean as possible not only in its code but in its dependencies (keeping them down to a reasonable minimum).
*One Abstraction Level, 2 Models
ROME2 will not have an abstract representation of feeds (the Synd beans). It will have 2 distinct models, Atom and RSS, both of them first citizens.
ROME2 users will use the model that fits more their needs.
Conversion (automatic and programmatic) between the 2 models will be part of ROME2.
*Bean Interfaces
After some discussions on the first ROME2 proposal we are going back to the interface model. The self proxy pattern proposed in the first proposal (to be able use arbitrary implementations) adds a bit of complexity into understanding what is going one plus it does not address in a clean way the needs for persistency (such as Hibernate or JPA).
All ROME2 beans will interfaces. Different from ROME, the implementation classes for the ROME2 beans will not be part of the public API. Instead using directly constructors to create ROME2 beans, a factory pattern will be used. A Convenience class, Rome, will wrap the factory class providing a concise way of creating a ROME2 bean.
For example, creating ROME2 beans using the Rome class convenience class will be something like:
+------+
Feed feed = Rome.create(Feed.class);
Entry entry1 = Rome.create(Entry.class));
Entry entry2 = Rome.create(Entry);
feed.getEntries().add(entry1);
feed.getEntries().add(entry2);
+------+
Which is equivalent to (using the Rome Bean factory class):
+------+
Feed feed = BeanFactory.getFactory().create(Feed.class);
Entry entry1 = BeanFactory.getFactory().create(Entry.class));
Entry entry2 = BeanFactory.getFactory().create(Entry);
feed.getEntries().add(entry1);
feed.getEntries().add(entry2);
+------+
To provide an alternate implementation beans an alternate set of beans will have to be provided. In addition, if necessary, an alternate bean factory could be used.
To write an alternate implementation the bean classes will have to implement the ROME2 interface beans.
*Using multiple Bean implementations simultaneously
ROME2 will support the use of multiple implementation beans simultaneously by changing the bean factory at anytime.
A use case could be retrieving a feed from a persistent store (which uses its own implementation beans), retrieving a feed from the internet (using the default implementation beans), merging their entries and producing an output feed, into the persistent store or out to the internet.
*Bean Factory Scopes
The bean factory will support a default factory and a context factory. The default factory is used if no context factory is available. The context factory uses a InheritableThreadLocal to store the factory in context, this is useful for use in dependency injection containers (Servlet, Spring, etc).
*Collection Elements
All collection properties (such as the authors, categories, contributors, links and entries of an Atom feed bean) will only have getter methods in the ROME2 API beans, no setter methods. For example:
+------+
public class Feed {
public List<Person> getAuthors() { ... }
public List<Category> getCategories() { ... }
...
}
+------+
This will ensure that the implementation bean has control on the implementation of the collection being used. This is particularly important to enable alternate implementation beans to fetch data from a repository as the collection is iterated over.
*Modules
Feeds, both RSS and Atom, are extensible via namespaced elements at feed/channel and entry/item level, these namespace elements are known as modules. Beans supporting modules (feed, channel, entry and item) will all have the following method to support modules.
+------+
public Map<String,Module> getModules() { ... }
+------+
Because modules are uniquely identified by their URI, a Map will be used, the key will be the URI of the module and the value the module itself. As with other ROME2 API bean collection properties, the getModules() property has a getter only, the Map implementation is controlled by the implementation bean.
Module URIs in ROME2, as all the links URLs in the beans, will be Strings thus reducing object creation explosion a bit. For cases that some URI manipulation is required, the JDK URI class should be used.
*Dynamic Modules Support
ROME2 modules design has to ensure it provides simple and comprehensive support for dynamic modules such as SLE and GData.
*Unknown Modules
A special Module subclass, UnknownModule, will serve as placeholder for module data not explicitly processed by ROME2 available parsers/generators. This will allow to consume and re\-export a feed without losing unknown (to ROME2) modules. Each unknown module will be keyed off with its URI in the map of the associated feed, channel, entry or item.
The data of the unknown module will be available as a String. ROME2 users should not use \=UnknownModule\='s data directly, if they need to manipulate that data they should find or implement bean/parser/generator for the module they need to manipulate.
Because unknown modules brings some extra overhead in the parsing and generating process ROME2 will have a property to enable/disable processing of unknown modules.
*The xml:lang Attributes
All ROME2 API beans will have xml:lang attributes, String and enum and primitive types properties won't.
*The xml:base Attributes
The xml:base attribute will not be present in any ROME2 API bean.
It will be the responsibility of the parsers to resolve any relative URL present in the feed at parsing time. Similarly, generators may relativize URLs as a size optimization (for God's sake we are doing XML).
*Object Class Methods in ROME2 Beans
The equals() and hashCode() methods will not be overridden. As all ROME2 beans are mutable, it is not safe to use them as keys of hash structures.
Cloning will not be directly defined by ROME2 interface beans, instead they will have a copyFrom() method which is type safe and does a deep copy. Cloning a ROME2 bean will be a two step process, for example:
+------+
Feed feed1 = Rome.create(Feed.class);
...
Feed feed2 = Rome.create(Feed.class);
feed2.copyFrom(feed1);
+------+
The toString() method in the beans will print the property that most likely identifies the bean plus the class name of the implementation bean. For example for a Feed bean the output of toString() would be:
+------+
[xxx.rome2.impl.pojo.atom.FeedBean - http://foo.com/atom.xml]
+------+
\-\-\+\+ Plugins ClassLoading
Bean implementations, parsers, generators, converters and all pluggable ROME2 components will be loaded using the same classLoader ROME2 core classes are loaded from.
This is to keep simple the handling of them via singletons and their instantiation. Supporting different classLoaders would require complex handling for instantiation, to avoid missing classes and class mismatches.
NOTE: As an example of how easy things can go sour, imagine ROME2 core classes in the common path of a web\-container and 2 web\-apps adding their own beans/parsers/generators/modules, the singletons managing them are in ROME2 core, managed by the common classLoader, a simple singleton won't cut it. ROME2 core will be small enough that it will not be a memory consumption issue if it is once in each web\-app.
*Parsers and Generators
To support large feeds (several megabytes or even gigabytes) ROME2 will support stream parsing. We have to see if how this could be done leveraging Abdera, else using StAX API directly.
Using XML stream parsers/generators is more complicated than using a DOM ones, to make easier for developers to implement parsers and generators ROME2 will take care of the details of the XML streaming API and it will expose feed fragments (the feed header and entries) via the JDom API, as JDom Elements. For example, the streaming version of an Atom parser and generator would be something like:
+------+
public interface AtomParser {
// A JDom Document with just the root element, its attributes and namespaces in it.
boolean canParseFeed(Document jdomDoc);
// repeatable operation, returns was has been read from the header so far
// feed parameter has whatever is has been readed from the feed header so far.
// If the given feed parameter is not null data from the jdom element is injected in it.
Feed parseFeed(Element jdomFeedElement, Feed feed) throws FeedException;
// the jdomFeedElement allows the parser to get context (such as base URL, namespaces)
// for the entry being parsed.
Entry parseEntry(Element jdomFeedElement, Element jdomEntryElement) throws FeedException;
}
public interface AtomGenerator {
String getFeedType();
// if called must be called once and before a generateEntry(Entry)
Element generateFeed(Feed feed) throws FeedException;
Element generateEntry(Entry entry) throws FeedException;
}
+------+
For Modules the parser and generator interface would be something like:
+------+
public interface ModuleParser<M extends Module> {
String getUri();
M parseModule(Element jdomFeedElement);
M parseModule(Element jdomFeedElement, Element jdomEntryElement);
}
public interface ModuleGenerator<M extends Module> {
String getUri();
Element generateModule(M module);
}
+------+
Parsers and Generators for modules will follow the same principle.
As with ROME, in ROME2 Parsers will be as lenient as possible. Generators will be strict.
*ROME2 IO classes
Feed parsers and generators will not be directly accessed by the ROME2 user, they are used by ROME2 to expose a more convenient API in the form of streaming API and builder API. For example:
+------+
public class RomeIO {
// streaming API
public static AtomReader createAtomReader(Reader reader, boolean xmlHealing) { };
public static RssReader createRssReader(Reader reader, boolean xmlHealing) { };
public static AtomWriter createAtomWriter(Writer writer, String feedType) { };
public static RssWriter createRssWriter(Writer writer, String feedType) { };
// builder API
public Feed parseAsFeed(Reader reader) { };
public Channel parseAsChannel(Reader reader) { };
public void generate(Writer writer, Feed feed, String feedType) { };
public void generate(Writer writer, Channel channel, String feedType) { };
}
public interface AtomReader {
String getFeedType();
// repeatable read, returns the current parsed state of the feed header
Feed readFeed() throws FeedException;
// returns a feed entry while there are more, NULL when done
Entry readEntry() throws FeedException;
// closes the feed reader
void close() throws FeedException;
}
public interface AtomWriter {
String getFeedType();
// if called must be called once and before a write(Entry)
void writeFeed(Feed feed) throws FeedException;
// if the first write is for an Entry, then the output is an item document
void writeEntry(Entry entry) throws FeedException;
void close() throws FeedException;
}
+------+
*Feed Validators
A bean FeedValidator class will verify that a feed or entry bean is valid for a given feed type. Feed generators would use this class to ensure feed correctness.
*Feed Conversion
Conversion from Atom to RSS beans and vice versa will be done by an implementation of the FeedConverter interface. Conversion will be supported at both feed/channel and entry/item level. All properties, including modules data will be copied, after an conversion the state of the beans will be completely independent.
The converter implementation will be pluggable, the implementation will be obtained from the bean factory and the Rome convenience class.
Conversion from Atom beans to RSS beans and vice versa will be done by a FeedConverter class that would have the following signature:
+------+
public interface FeedConverter {
public Feed convertToFeed(Channel channel);
public Feed convertToFeed(Channel channel, boolean processItems);
public Entry convertToEntry(Item item);
public Channel convertToChannel(Feed feed);
public Channel convertToChannel(Feed feed, boolean processEntries);
public Item convertToItem(Entry entry);
}
+------+
*Parser and Generator Filters
Manipulation of feeds during parsing and generation at feed/channel and entry/item level would be possible by implementing readers and writers wrappers that work on top of the original reader and writer instances.
This filtering/wrapping could be automated via configuration.
*Sources
The following ZIP file only includes the ROME2 beans as described in this proposal, it does not include any of the parser, generator or IO API.
* {{{./rome2proto2.zip}rome2proto2.zip}}
[]

64
src/site/apt/ROMEDevelopmentProposals/ROMEFeatureRequests.apt Normal file
View file

@ -0,0 +1,64 @@
-----
ROME Feature Requests
-----
mkurz
-----
2011-08-15 10:49:48.825
-----
ROME Feature Requests
* <<BUG:>> com.sun.syndication.io.impl.DateParser:Date parseW3CDateTime(String) incorrectly uses a comma (",") rather than a decimal (".") to delimit the seconds from miliseconds. The correct format can be found on {{{http://www.w3.org/TR/NOTE\-datetime}http://www.w3.org/TR/NOTE\-datetime}}. The bug is on line 170 (version 0.8). The fix is to replace the line with this: <<<int secFraction \= pre.indexOf(".");>>> \-\- JLP 9/4/2006
* <<BUG:>> Atom 1.0 parsing uses wrong Content types. "text", "html", "xhtml" do not match what is parse from the content elements. Subsequently, the content elements always have a null value \- no way to get content.
* <<BUG:>> Link in description is not parsed\
Try to parse {{{http://jakarta.apache.org/site/rss.xml}http://jakarta.apache.org/site/rss.xml}}, look at entry {{{http://jakarta.apache.org/site/news/news\-2006\-q1.html#20060107.1}http://jakarta.apache.org/site/news/news\-2006\-q1.html#20060107.1}} This entry has an "\<a href..." in the first line, which isn't parsed by Rome \-\- Main.iterson \- 25 Jan 2006
* <<BUG:>> Support all encodings\
The problem is when reading RSS a space between the encoding to the value or ualue in '' insted of "" will cause error, for example: this will work work encoding\="windows\-1255" but this: encoding \= "windows\-1255" or encoding\='windows\-1255' won't work.
* <<BUG:>> The reader doesn't attempt use the masks that defined in the rome.properties for reading the date for all date parsing method, e.g. RSS093Parser.parseItem uses DateParser.parserRFC822 which is not covered by that logic \-\- Main.den_st \- 17 Jan 2006; if it will use the mask the code will run good. I had a problem to read date and I defined a mask in the properties file (datetime.extra.masks\=yyyy\-MM\-dd'T'HH:mm:ss trying to read 2005\-09\-22T09:00:41\} ). Then i try to change one of the mask at runtime to the mask i defined in the properties file and it works good. The logic in the code trys to format the date with each one of the default masks if it faild it returns null instead of trying to format the date using the format that defined in the rome.properties file.
* Support for writing to OutputStreams. If I want to compress the feeds to a (.gz) file or write to a socket, I have to extend SyndFeedOutput and WireFeedOutput to add a method called output(SyndFeed, OuputStream). It would be nice to have that built in instead. \-\- Main.agherna \- 08 Aug 2005
* I'd like the getDate method on feeds and entries to go to the associated modules and retrieve the appropriate dc:date when the getDate() method returns null. This way entries from feeds like this one: {{{http://www.magpiebrain.com/index.xml}http://www.magpiebrain.com/index.xml}} would have valid dates without requiring me to write code work out what format the feed is in and act accordingly.
* Would like to see {{{../../opml/index.html}OPML}} parser also.\
<<<This is already supported by Rome>>>. RSS2.0 parser, see {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html}Date Elements mapping}} by default does not process Modules. Refer to the Modules Plugins documentation to see how to enable this.
* {{{http://bobwyman.pubsub.com/main/2004/09/implementations.html}RFC3229}} support (in {{{../../fetcher/index.html}RomeFetcher}} and example code implementing it for production) would be a killer feature.
* The RSS 1.0 Spec {{{http://web.resource.org/rss/1.0/spec}http://web.resource.org/rss/1.0/spec}} indicates that the <<suggested>> maximum length for a description field on an entry is 500 characters, but the 0.4 codebase enforces 500 characters as a hard limit \-\- exceeding it on input or output generates a FeedException. Since one doesn't always have control over the feeds one consumes, it seems to me that it would be a good idea if Rome were more forgiving in accepting feed entries that exceed the suggested lengths.
* Is there a chance to include an option in Rome for liberal parsing, ie. trying to get most out of a feed even when it's non\-conforming without throwing exceptions? I believe RSS is pretty close to HTML not from a technical point of view but thinking of practical use. Hence, RSS feeds will be incorrect in many cases however they still could join the party with a tolerant parser. Maybe Rome could do for Java what {{{http://diveintomark.org/projects/feed_parser/}Mark Pilgrim}} has done for Python (although I did not verify his ultraliberal parser's tolerance)?
* More liberal parsing for dates, to handle un\-parseable dates like: "12 sep 1998", "'05" or monsters like this one : "\[2005\]". I faced this problem using DCModule, dc:date attribute can have mentioned values. In older versions of my app there were no constrains for date format, so users have written them very freely.
* I think that Rome has problems parsing rss feeds where the xml contains a link to a stylesheet. Try parsing {{{http://ihatemyflatmate.blogspot.com/atom.xml}http://ihatemyflatmate.blogspot.com/atom.xml}} (Atom) or {{{http://msdn.microsoft.com/rss.xml}http://msdn.microsoft.com/rss.xml}} (RSS 1.0). I get Exceptions with both, and they both have stylesheets, whereas other working feeds don't.
* It would be very nice to have a possibility to add stylesheet to generated feed. I can do this by replacing header in generated String, but this method is ...
* There are problems with the correct encoding of HTML when generating RSS2.0. It is in the area of extended character sets. If you encode the following:
+------+
<FONT size="2">Quatre pi&amp;#232;ces</FONT>
+------+
In the hope of gettin "Quatre pièces" in your html feed. You get from the SynFeedOutput.output() this:
+------+
&amp;lt;FONT size="2"&amp;gt;Quatre pi&amp;amp;#232;ces&amp;lt;/FONT&amp;gt;
+------+
Which ends up with "Quatre pièces" being displayed in the RSS Reader that is taking your feed. To get the correct ouput I have had to resort to outputString.replaceAll("&#","&#"); OK as a a workaround but not very elegant or performant! \-\- Main.rjwallis \- 19 Mar 2005
* From that what i know about Rome it's impossible to use "\<\[!CDDATA \[" entities in content of feed's tags. i know this isn't essential, but it would a very nice feature.
* Provide support for lastBuildDate in RSS, many news provider, including Yahoo News and BBC use lastBuildDate instead of lastPublishDate.
[]

38
src/site/apt/ROMEDevelopmentProposals/index.apt Normal file
View file

@ -0,0 +1,38 @@
-----
ROME Development Proposals
-----
mkurz
-----
2011-08-15 11:17:30.648
-----
ROME Development Proposals
*ROME Development Proposals
Link to new ROME feature and release proposals here.
*ROME2 Proposal
* {{{../ROMEROADMAPProposed.html}ROME ROADMAP (Proposed) (rome)}}
* {{{./ROME21stProposalJune10th2006NOTCURRENT.html}ROME2 first proposal }} (Jun/10/2006).
* {{{./ROME22ndProposalJuly18th2006CURRENT.html}ROME2 second proposal }} (Jul/18/2006).
[]
*Requests for Enhancement (RFEs)
* {{{https://rometools.jira.com/browse/ROME}Issue tracking system}} \- file RFEs here
* {{{./ROMEFeatureRequests.html}Feature Requests}} \- old feature request page
[]

78
src/site/apt/ROMEROADMAPProposed.apt Normal file
View file

@ -0,0 +1,78 @@
-----
ROME ROADMAP (Proposed)
-----
mkurz
-----
2011-08-15 11:15:23.229
-----
ROME ROADMAP (Proposed)
*----+--+
| |
version
||
changes
|
*----+--+
|
1.1
|
Omnibus release with ROME patches + JDK 1.5 changes.
|
*----+--+
|
1.5
|
Migration to org.rometools (light break compat)
|
*----+--+
|
1.6
|
Elimination of Synd* interfaces and Synd*Impl in favor of base objects (break compat)
|
*----+--+
|
1.7
|
Introduction of "Rome" class with pass-by-ref context for modules
|
*----+--+
|
1.8
|
Addition of a factory by package for the Rome class.
|
*----+--+
|
1.9
|
JSR-330   remix of the Rome class and all deps.
|
*----+--+
*Old Development Proposals
* {{{./ROMEDevelopmentProposals/ROME22ndProposalJuly18th2006CURRENT.html}ROME2 2nd Proposal (July 18th 2006) CURRENT (rome)}}
* {{{./ROMEDevelopmentProposals/ROME21stProposalJune10th2006NOTCURRENT.html}ROME2 1st Proposal (June 10th 2006) NOT CURRENT (rome)}}
[]

73
src/site/apt/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1HowToBuildAndRunTheTutorialsSampleCode.apt Normal file
View file

@ -0,0 +1,73 @@
-----
Rome v0.1, How to build and run the tutorials sample code
-----
mkurz
-----
2011-08-15 14:39:07.651
-----
Rome v0.1, How to build and run the tutorials sample code
*Building the samples with Maven
This is, as usual, the easiest way.
There's only one configuration step: Maven downloads dependencies from an online repository (by default ibiblio), to a local repository (on UNIX usually in \~/.maven/repository). Because the rome distribution is not yet on ibiblio, you need to add it yourself, either to your local repository, or to your own intranet maven repository if you have such a thing in your organization.
If you built Rome run maven jar:install in the rome project to install Rome's jar in your Maven repository.
If you got Rome binary distribution copy the Rome's jar file to your Maven repository (on UNIX that would be cp rome\-0.1/rome\-0.1.jar   \~/.maven/repository/rome/jars/).
Then building the samples it's easy as a pie, just run maven jar in the rome\-samples project and you are all set.
*Building the samples with Ant
Hopefully maven is helpful in supporting poor ant users who did not make the switch yet:\-) We generated an Ant build.xml file in order for you to be able to build rome\-samples with Ant. (Actually, Maven did it for us, the maven ant goal).
The targets present in the build.xml are very helpful, ant get\-deps will download from ibiblio to rome\-samples/target/lib all the jar files Rome depends on and are needed for building an application using Rome.
The only thing that will be left out is Rome's jar file itself: you'll need to copy it to the rome\-samples/target/lib directory (For example in UNIX would be cp rome\-0.1/rome\-0.1.jar  rome\-samples/target/lib, where rome\-0.1 is the binary distribution).
To build rome\-samples just run ant jar.
*Running the samples with Maven
The Maven goals for running the samples are defined in maven.xml. They should all generate the same file named toto, but somehow it ends up empty. However the output is correctly sent to the console. We'll fix that glitch later.
maven run\-agr runs the FeedAggregator sample
maven run\-conv runs the FeedConverter sample
maven run\-read runs the FeedReader sample
*Running the samples with Ant
All ant targets for the samples generate the same file named toto: feel free to customize this build.xml to your own needs. Also today all these targets depends on the jar target, which represents some overhead if you have already built. Get rid of that once your project is well setup.
ant run\-aggr runs the FeedAggregator sample
ant run\-conv runs the FeedConverter sample
ant run\-read runs the FeedReader sample

155
src/site/apt/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.apt Normal file
View file

@ -0,0 +1,155 @@
-----
Rome v0.1 Tutorial, Using Rome to aggregate many syndication feeds into a single one
-----
mkurz
-----
2011-08-15 14:38:10.131
-----
Rome v0.1 Tutorial, Using Rome to aggregate many syndication feeds into a single one
<<Software requirements:>> J2SE 1.4\+, Xerces 2.4.0, JDOM B10, Commons Codec 1.2 and Rome 0.1.
Rome represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeedI interface. The SyndFeedI interfaces and its properties follow the Java Bean patterns. The default implementations provided with Rome are all lightweight classes.
Rome includes parsers to process syndication feeds into SyndFeedI instances. The SyndInput class handles the parsers using the correct one based on the syndication feed being processed. The developer does not need to worry about selecting the right parser for a syndication feed, the SyndInput will take care of it by peeking at the syndication feed structure. All it takes to read a syndication feed using Rome are the following 2 lines of code:
+------+
SyndInput input = new SyndInput();
SyndFeedI feed = input.build(feedUrl.openStream());
+------+
The first line creates a SyndInput instance that will work with any syndication feed type (RSS and Atom versions). The second line instructs the SyndInput to read the syndication feed from the InputStream of a URL pointing to the feed. The SyndInput.build() method returns a SyndFeedI instance that can be easily processed.
Rome also includes generators to create syndication feeds out of SyndFeedI instances. The SyndOutput class does this generation. When creating a syndication feed output, the developer has to indicate the syndication feed type for the ouput, and the SyndOutput will use the right generator for it. The following two lines of code show how to create a syndication feed output from a SyndFeedI instance:
+------+
SyndOutput output = new SyndOutput(outputType);
output.output(feed,System.out);
+------+
The first line creates a SyndOutput instance that will produce syndication feeds of the type indicated by the outputType parameter. The outputType parameter can be any of the following values: rss_0.9, rss_0.91, rss_0.92, rss_0.93, rss_0.94, rss_1.0, rss_2.0 & atom_0.3. The second line writes the SyndFeedI as a syndication feed into the application's output.
SyndFeedI can also be created and populated within the code. For example:
+------+
SyndFeedI aggrFeed = new SyndFeed();
aggrFeed.setTitle("Aggregated Feed");
aggrFeed.setDescription("Anonymous Aggregated Feed");
aggrFeed.setAuthor("anonymous");
aggrFeed.setLink("http://www.anonymous.com");
+------+
The snipped of code above creates a SyndFeedI instance using the default implementation provided by Rome and sets the title, description, author and link properties of the feed.
SyndFeedI properties can be modified, assigned to other SyndFeedI instances, removed, etc. It's important to remember that the getters/setters semantics defined for all SyndFeedI properties (and properties of its properties) is a copy by reference, not by value. In other words if you alter the property of a SyndFeedI property you are altering the SyndFeedI. Or, another example, if you assign the list of entries of one SyndFeedI instance to another SyndFeedI isntance and then you modify the list or any of the entries in the list, you are modifying the entries of both SyndFeedI instances.
The following lines of code show how to copy the entries of a SyndFeedI instance being read (inFeed) into a SyndFeedI instance being created within the application (feed):
+------+
SyndFeedI feed = new SyndFeed();
...
List entries = new ArrayList();
feed.setEntries(entries);
...
SyndInput input = new SyndInput(false);
SyndFeedI inFeed = input.build(inputUrl.openStream());
entries.addAll(inFeed.getEntries());
+------+
Note that it's OK to assign the entries list to the feed and later add entries to it as all SyndFeedI getters/setters do copy by reference.
Following is the full code for a Java application that reads a list of syndication feed, aggregates their items into a single feed, and writes the aggregated feed to the application's output.
+------+
package com.sun.syndication.samples;
import java.net.URL;
import java.util.List;
import java.util.ArrayList;
import com.sun.syndication.feed.synd.SyndFeedI;
import com.sun.syndication.feed.synd.SyndFeed;
import com.sun.syndication.feed.synd.SyndEntryI;
import com.sun.syndication.io.SyndInput;
import com.sun.syndication.io.SyndOutput;
public class FeedAggregator {
public static void main(String[] args) {
boolean ok = false;
if (args.length>=2) {
try {
String outputType = args[0];
SyndFeedI feed = new SyndFeed();
feed.setTitle("Aggregated Feed");
feed.setDescription("Anonymous Aggregated Feed");
feed.setAuthor("anonymous");
feed.setLink("http://www.anonymous.com");
List entries = new ArrayList();
feed.setEntries(entries);
for (int i=1;i<args.length;i++) {
URL inputUrl = new URL(args[i]);
SyndInput input = new SyndInput(false);
SyndFeedI inFeed = input.build(inputUrl.openStream());
entries.addAll(inFeed.getEntries());
}
SyndOutput output = new SyndOutput(outputType);
output.output(feed,System.out);
ok = true;
}
catch (Exception ex) {
System.out.println("ERROR: "+ex.getMessage());
}
}
if (!ok) {
System.out.println();
System.out.println("FeedAggregator aggregates different feeds into a single one.");
System.out.println("The first parameter must be the feed type for the aggregated feed.");
System.out.println(" [valid values are: rss_0.9, rss_0.91, rss_0.92, rss_0.93, ]");
System.out.println(" [ rss_0.94, rss_1.0, rss_2.0 & atom_0.3 ]");
System.out.println("The second to last parameters are the URLs of feeds to aggregate.");
System.out.println();
}
}
}
+------+

95
src/site/apt/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.apt Normal file
View file

@ -0,0 +1,95 @@
-----
Rome v0.1 Tutorial, Using Rome to convert a syndication feed from one type to another
-----
mkurz
-----
2011-08-15 14:36:33.399
-----
Rome v0.1 Tutorial, Using Rome to convert a syndication feed from one type to another
<<Software requirements:>> Synd J2SE 1.4\+, Xerces 2.4.0, JDOM B10, Commons Codec 1.2 and Rome 0.1.
Rome represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeedI interface. The SyndFeedI interfaces and its properties follow the Java Bean patterns. The default implementations provided with Rome are all lightweight classes.
Rome includes parsers to process syndication feeds into SyndFeedI instances. The SyndInput class handles the parsers using the correct one based on the syndication feed being processed. The developer does not need to worry about selecting the right parser for a syndication feed, the SyndInput will take care of it by peeking at the syndication feed structure. All it takes to read a syndication feed using Rome are the following 2 lines of code:
+------+
SyndInput input = new SyndInput();
SyndFeedI feed = input.build(feedUrl.openStream());
+------+
The first line creates a SyndInput instance that will work with any syndication feed type (RSS and Atom versions). The second line instructs the SyndInput to read the syndication feed from the InputStream of a URL pointing to the feed. The SyndInput.build() method returns a SyndFeedI instance that can be easily processed.
Rome also includes generators to create syndication feeds out of SyndFeedI instances. The SyndOutput class does this generation. When creating a syndication feed output, the developer has to indicate the syndication feed type for the ouput, and the SyndOutput will use the right generator for it. The following two lines of code show how to create a syndication feed output from a SyndFeedI instance:
+------+
SyndOutput output = new SyndOutput(outputType);
output.output(feed,System.out);
+------+
The first line creates a SyndOutput instance that will produce syndication feeds of the type indicated by the outputType parameter. The outputType parameter can be any of the following values: rss_0.9, rss_0.91, rss_0.92, rss_0.93, rss_0.94, rss_1.0, rss_2.0 & atom_0.3. The second line writes the SyndFeedI as a syndication feed into the application's output.
Following is the full code for a Java application that reads a syndication feed and converts it to other syndication feed type, writing the converted feed to the application's output.
+------+
package com.sun.syndication.samples;
import java.net.URL;
import com.sun.syndication.feed.synd.SyndFeedI;
import com.sun.syndication.io.SyndInput;
import com.sun.syndication.io.SyndOutput;
public class FeedConverter {
public static void main(String[] args) {
boolean ok = false;
if (args.length==2) {
try {
String outputType = args[0];
URL feedUrl = new URL(args[1]);
SyndInput input = new SyndInput(false);
SyndFeedI feed = input.build(feedUrl.openStream());
SyndOutput output = new SyndOutput(outputType);
output.output(feed,System.out);
ok = true;
}
catch (Exception ex) {
System.out.println("ERROR: "+ex.getMessage());
}
}
if (!ok) {
System.out.println();
System.out.println("FeedConverter converts between syndication feeds types.");
System.out.println("The first parameter must be the feed type to convert to.");
System.out.println(" [valid values are: rss_0.9, rss_0.91, rss_0.92, rss_0.93, ]");
System.out.println(" [ rss_0.94, rss_1.0, rss_2.0 & atom_0.3 ]");
System.out.println("The second parameter must be the URL of the feed to convert.");
System.out.println();
}
}
}
+------+

84
src/site/apt/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1TutorialUsingRomeToReadASyndicationFeed.apt Normal file
View file

@ -0,0 +1,84 @@
-----
Rome v0.1 Tutorial, Using Rome to read a syndication feed
-----
mkurz
-----
2011-08-15 14:35:18.803
-----
Rome v0.1 Tutorial, Using Rome to read a syndication feed
<<Software requirements:>> J2SE 1.4\+, Xerces 2.4.0, JDOM B10, Commons Codec 1.2 and Rome 0.1.
Rome represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeedI interface. The SyndFeedI interfaces and its properties follow the Java Bean patterns. The default implementations provided with Rome are all lightweight classes.
Rome includes parsers to process syndication feeds into SyndFeedI instances. The SyndInput class handles the parsers using the correct one based on the syndication feed being processed. The developer does not need to worry about selecting the right parser for a syndication feed, the SyndInput will take care of it by peeking at the syndication feed structure. All it takes to read a syndication feed using Rome are the following 2 lines of code:
+------+
SyndInput input = new SyndInput();
SyndFeedI feed = input.build(feedUrl.openStream());
+------+
The first line creates a SyndInput instance that will work with any syndication feed type (RSS and Atom versions). The second line instructs the SyndInput to read the syndication feed from the InputStream of a URL pointing to the feed. The SyndInput.build() method returns a SyndFeedI instance that can be easily processed.
The default SyndFeedI implementation has a detailed and clear toString() implementation. The following line just prints it to the application's output.
+------+
System.out.println(feed);
+------+
Following is the full code for a Java application that reads a syndication feed and prints the SyndFeedI bean to the application's output.
+------+
package com.sun.syndication.samples;
import java.net.URL;
import com.sun.syndication.feed.synd.SyndFeedI;
import com.sun.syndication.io.SyndInput;
public class FeedReader {
public static void main(String[] args) {
boolean ok = false;
if (args.length==1) {
try {
URL feedUrl = new URL(args[0]);
SyndInput input = new SyndInput();
SyndFeedI feed = input.build(feedUrl.openStream());
System.out.println(feed);
ok = true;
}
catch (Exception ex) {
System.out.println("ERROR: "+ex.getMessage());
}
}
if (!ok) {
System.out.println();
System.out.println("FeedReader reads and prints any RSS/Atom feed type.");
System.out.println("The first parameter must be the URL of the feed to read.");
System.out.println();
}
}
}
+------+

25
src/site/apt/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/index.apt Normal file
View file

@ -0,0 +1,25 @@
-----
Rome v0.1 Tutorials
-----
mkurz
-----
2011-08-15 14:28:13.572
-----
Rome v0.1 Tutorials
The following tutorials show how to use the Rome API. They focus on the higher abstraction layer of classes offered by Rome, what we call the Synd\* classes. By using the Synd\* classes developers don't have to deal with the specifics of any syndication feed. They work with normalized feeds, the Synd\* feeds. This makes it much easier to write applications that have to deal with all the variety of syndication feed types in use today.
[[1]] {{{./RomeV0.1TutorialUsingRomeToReadASyndicationFeed.html}Using Rome to read a syndication feed}}
[[1]] {{{./RomeV0.1TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html}Using Rome to convert a syndication feed from one type to another}}
[[1]] {{{./RomeV0.1TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html}Using Rome to aggregate many syndication feeds into a single one}}
[]
For instructions on how to build and run the samples used in the tutorials {{{./RomeV0.1HowToBuildAndRunTheTutorialsSampleCode.html}click here}}.

64
src/site/apt/ROMEReleases/ROME0.1Beta/index.apt Normal file
View file

@ -0,0 +1,64 @@
-----
ROME 0.1 Beta
-----
mkurz
-----
2011-08-15 14:33:58.218
-----
ROME 0.1 Beta
*Dependencies
* J2SE 1.4\+ (Not J2SE 1.3\+ as it was initially documented)
* {{{http://www.jdom.org/}JDOM Beta 10}}
* {{{http://jakarta.apache.org/commons/codec/}Jakarta Commons Codec 1.2}}
* Rome v0.1 does not depend on Xerces as it was initially documented
[]
*Downloads
* {{{./rome\-0.1\-src.zip}rome\-0.1\-src.zip}}
* {{{./rome\-0.1.tar.gz}rome\-0.1.tar.gz}}
* {{{./rome\-0.1.zip}rome\-0.1.zip}}
* {{{./rome\-0.1\-src.tar.gz}rome\-0.1\-src.tar.gz}}
* {{{./rome\-samples\-0.1\-src.zip}rome\-samples\-0.1\-src.zip}}
* {{{./rome\-samples\-0.1.tar.gz}rome\-samples\-0.1.tar.gz}}
* {{{./rome\-samples\-0.1.zip}rome\-samples\-0.1.zip}}
* {{{./rome\-samples\-0.1\-src.tar.gz}rome\-samples\-0.1\-src.tar.gz}}
[]
*Additional Information
* {{{./RomeV0.1Tutorials/index.html}Tutorials}}
[]
*Known Issues
* On Mac OS X 10.2.8 Maven cannot run the samples, the JVM exist with a reflection error in a native method
* On Mac OS X 10.2.8 to run the samples using Ant you need to include Xerces 2.4.0 in the CLASSPATH. Otherwise it does not the XML Parser implementation
[]

143
src/site/apt/ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/RomeV0.2TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.apt Normal file
View file

@ -0,0 +1,143 @@
-----
Rome v0.2 Tutorial, Using Rome to aggregate many syndication feeds into a single one
-----
mkurz
-----
2011-08-15 14:44:18.890
-----
Rome v0.2 Tutorial, Using Rome to aggregate many syndication feeds into a single one
<<Software requirements:>> J2SE 1.4\+, JDOM B10 and Rome 0.2.
Rome represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeedI interface. The SyndFeedI interfaces and its properties follow the Java Bean patterns. The default implementations provided with Rome are all lightweight classes.
Rome includes parsers to process syndication feeds into SyndFeedI instances. The SyndFeedInput class handles the parsers using the correct one based on the syndication feed being processed. The developer does not need to worry about selecting the right parser for a syndication feed, the SyndFeedInput will take care of it by peeking at the syndication feed structure. All it takes to read a syndication feed using Rome are the following 2 lines of code:
+------+
SyndFeedInput input = new SyndFeedInput();
SyndFeedI feed = input.build(feedUrl.openStream());
+------+
The first line creates a SyndFeedInput instance that will work with any syndication feed type (RSS and Atom versions). The second line instructs the SyndFeedInput to read the syndication feed from the InputStream of a URL pointing to the feed. The SyndFeedInput.build() method returns a SyndFeedI instance that can be easily processed.
Rome also includes generators to create syndication feeds out of SyndFeedI instances. The SyndFeedOutput class does this generation. The SyndFeedOutput will generate a syndication feed of the feed type indicated by the SyndFeedI object being output. The following two lines of code show how to create a syndication feed output from a SyndFeedI instance:
+------+
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,System.out);
+------+
The first line creates a SyndFeedOutput instance that will produce syndication feeds. It can output feeds of any type (rss_0.9, rss_0.91, rss_0.92, rss_0.93, rss_0.94, rss_1.0, rss_2.0 & atom_0.3), the SyndFeedI feedType property indicates the type. The second line writes the SyndFeedI as a syndication feed into the application's output.
SyndFeedI can also be created and populated within the code. For example:
+------+
SyndFeedI aggrFeed = new SyndFeed();
aggrFeed.setFeedType("rss_1.0");
aggrFeed.setTitle("Aggregated Feed");
aggrFeed.setDescription("Anonymous Aggregated Feed");
aggrFeed.setAuthor("anonymous");
aggrFeed.setLink("http://www.anonymous.com");
+------+
The snipped of code above creates a SyndFeedI instance using the default implementation provided by Rome, sets the feed type to RSS 1.0, sets the title, description, author and link properties of the feed.
SyndFeedI properties can be modified, assigned to other SyndFeedI instances, removed, etc. It's important to remember that the getters/setters semantics defined for all SyndFeedI properties (and properties of its properties) is a copy by reference, not by value. In other words if you alter the property of a SyndFeedI property you are altering the SyndFeedI. Or, another example, if you assign the list of entries of one SyndFeedI instance to another SyndFeedI isntance and then you modify the list or any of the entries in the list, you are modifying the entries of both SyndFeedI instances.
The following lines of code show how to copy the entries of a SyndFeedI instance being read (inFeed) into a SyndFeedI instance being created within the application (feed):
+------+
package com.sun.syndication.samples;
import java.net.URL;
import java.util.List;
import java.util.ArrayList;
import com.sun.syndication.feed.synd.SyndFeedI;
import com.sun.syndication.feed.synd.SyndFeed;
import com.sun.syndication.io.SyndFeedOutput;
import com.sun.syndication.io.SyndFeedInput;
/**
* It aggregates a list of RSS/Atom feeds (they can be of different types)
* into a single feed of the specified type.
* <p>
* @author Alejandro Abdelnur
*
*/
public class FeedAggregator {
public static void main(String[] args) {
boolean ok = false;
if (args.length>=2) {
try {
String outputType = args[0];
SyndFeedI feed = new SyndFeed();
feed.setFeedType(outputType);
feed.setTitle("Aggregated Feed");
feed.setDescription("Anonymous Aggregated Feed");
feed.setAuthor("anonymous");
feed.setLink("http://www.anonymous.com");
List entries = new ArrayList();
feed.setEntries(entries);
for (int i=1;i<args.length;i++) {
URL inputUrl = new URL(args[i]);
SyndFeedInput input = new SyndFeedInput();
SyndFeedI inFeed = input.build(inputUrl.openStream());
entries.addAll(inFeed.getEntries());
}
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,System.out);
ok = true;
}
catch (Exception ex) {
System.out.println("ERROR: "+ex.getMessage());
}
}
if (!ok) {
System.out.println();
System.out.println("FeedAggregator aggregates different feeds into a single one.");
System.out.println("The first parameter must be the feed type for the aggregated feed.");
System.out.println(" [valid values are: rss_0.9, rss_0.91, rss_0.92, rss_0.93, ]");
System.out.println(" [ rss_0.94, rss_1.0, rss_2.0 & atom_0.3 ]");
System.out.println("The second to last parameters are the URLs of feeds to aggregate.");
System.out.println();
}
}
}
+------+

102
src/site/apt/ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/RomeV0.2TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.apt Normal file
View file

@ -0,0 +1,102 @@
-----
Rome v0.2 Tutorial, Using Rome to convert a syndication feed from one type to another
-----
mkurz
-----
2011-08-15 14:43:11.092
-----
Rome v0.2 Tutorial, Using Rome to convert a syndication feed from one type to another
<<Software requirements:>> Synd J2SE 1.4\+, JDOM B10 and Rome 0.2.
Rome represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeedI interface. The SyndFeedI interfaces and its properties follow the Java Bean patterns. The default implementations provided with Rome are all lightweight classes.
Rome includes parsers to process syndication feeds into SyndFeedI instances. The SyndFeedInput class handles the parsers using the correct one based on the syndication feed being processed. The developer does not need to worry about selecting the right parser for a syndication feed, the SyndFeedInput will take care of it by peeking at the syndication feed structure. All it takes to read a syndication feed using Rome are the following 2 lines of code:
+------+
SyndFeedInput input = new SyndFeedInput();
SyndFeedI feed = input.build(feedUrl.openStream());
+------+
The first line creates a SyndFeedInput instance that will work with any syndication feed type (RSS and Atom versions). The second line instructs the SyndFeedInput to read the syndication feed from the InputStream of a URL pointing to the feed. The SyndFeedInput.build() method returns a SyndFeedI instance that can be easily processed.
Rome also includes generators to create syndication feeds out of SyndFeedI instances. The SyndFeedOutput class does this generation. The SyndFeedOutput will generate a syndication feed of the feed type indicated by the SyndFeedI object being output. The following two lines of code show how to create a syndication feed output from a SyndFeedI instance:
+------+
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,System.out);
+------+
The first line creates a SyndFeedOutput instance that will produce syndication feeds. It can output feeds of any type (rss_0.9, rss_0.91, rss_0.92, rss_0.93, rss_0.94, rss_1.0, rss_2.0 & atom_0.3), the SyndFeedI feedType property indicates the type. The second line writes the SyndFeedI as a syndication feed into the application's output.
Following is the full code for a Java application that reads a syndication feed and converts it to other syndication feed type, writing the converted feed to the application's output.
+------+
package com.sun.syndication.samples;
import java.net.URL;
import com.sun.syndication.feed.synd.SyndFeedI;
import com.sun.syndication.io.SyndFeedInput;
import com.sun.syndication.io.SyndFeedOutput;
/**
* It Converts any RSS/Atom feed type to a an RSS/Atom feed of the
* specified type.
* <p>
* @author Alejandro Abdelnur
*
*/
public class FeedConverter {
public static void main(String[] args) {
boolean ok = false;
if (args.length==2) {
try {
String outputType = args[0];
URL feedUrl = new URL(args[1]);
SyndFeedInput input = new SyndFeedInput();
SyndFeedI feed = input.build(feedUrl.openStream());
feed.setFeedType(outputType);
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,System.out);
ok = true;
}
catch (Exception ex) {
System.out.println("ERROR: "+ex.getMessage());
}
}
if (!ok) {
System.out.println();
System.out.println("FeedConverter converts between syndication feeds types.");
System.out.println("The first parameter must be the feed type to convert to.");
System.out.println(" [valid values are: rss_0.9, rss_0.91, rss_0.92, rss_0.93, ]");
System.out.println(" [ rss_0.94, rss_1.0, rss_2.0 & atom_0.3 ]");
System.out.println("The second parameter must be the URL of the feed to convert.");
System.out.println();
}
}
}
+------+

91
src/site/apt/ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/RomeV0.2TutorialUsingRomeToReadASyndicationFeed.apt Normal file
View file

@ -0,0 +1,91 @@
-----
Rome v0.2 Tutorial, Using Rome to read a syndication feed
-----
mkurz
-----
2011-08-15 14:42:09.813
-----
Rome v0.2 Tutorial, Using Rome to read a syndication feed
<<Software requirements:>> J2SE 1.4\+, JDOM B10 and Rome 0.2.
Rome represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeedI interface. The SyndFeedI interfaces and its properties follow the Java Bean patterns. The default implementations provided with Rome are all lightweight classes.
Rome includes parsers to process syndication feeds into SyndFeedI instances. The SyndFeedInput class handles the parsers using the correct one based on the syndication feed being processed. The developer does not need to worry about selecting the right parser for a syndication feed, the SyndFeedInput will take care of it by peeking at the syndication feed structure. All it takes to read a syndication feed using Rome are the following 2 lines of code:
+------+
SyndFeedInput input = new SyndFeedInput();
SyndFeedI feed = input.build(feedUrl.openStream());
+------+
The first line creates a SyndFeedInput instance that will work with any syndication feed type (RSS and Atom versions). The second line instructs the SyndFeedInput to read the syndication feed from the InputStream of a URL pointing to the feed. The SyndFeedInput.build() method returns a SyndFeedI instance that can be easily processed.
The default SyndFeedI implementation has a detailed and clear toString() implementation. The following line just prints it to the application's output.
+------+
System.out.println(feed);
+------+
Following is the full code for a Java application that reads a syndication feed and prints the SyndFeedI bean to the application's output.
+------+
package com.sun.syndication.samples;
import java.net.URL;
import com.sun.syndication.feed.synd.SyndFeedI;
import com.sun.syndication.io.SyndFeedInput;
/**
* It Reads and prints any RSS/Atom feed type.
* <p>
* @author Alejandro Abdelnur
*
*/
public class FeedReader {
public static void main(String[] args) {
boolean ok = false;
if (args.length==1) {
try {
URL feedUrl = new URL(args[0]);
SyndFeedInput input = new SyndFeedInput();
SyndFeedI feed = input.build(feedUrl.openStream());
System.out.println(feed);
ok = true;
}
catch (Exception ex) {
ex.printStackTrace();
System.out.println("ERROR: "+ex.getMessage());
}
}
if (!ok) {
System.out.println();
System.out.println("FeedReader reads and prints any RSS/Atom feed type.");
System.out.println("The first parameter must be the URL of the feed to read.");
System.out.println();
}
}
}
+------+

25
src/site/apt/ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/index.apt Normal file
View file

@ -0,0 +1,25 @@
-----
Rome v0.2 Tutorials
-----
mkurz
-----
2011-08-15 14:41:00.881
-----
Rome v0.2 Tutorials
The following tutorials show how to use the Rome API. They focus on the higher abstraction layer of classes offered by Rome, what we call the Synd\* classes. By using the Synd\* classes developers don't have to deal with the specifics of any syndication feed. They work with normalized feeds, the Synd\* feeds. This makes it much easier to write applications that have to deal with all the variety of syndication feed types in use today.
[[1]] {{{./RomeV0.2TutorialUsingRomeToReadASyndicationFeed.html}Using Rome to read a syndication feed}}
[[1]] {{{./RomeV0.2TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html}Using Rome to convert a syndication feed from one type to another}}
[[1]] {{{./RomeV0.2TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html}Using Rome to aggregate many syndication feeds into a single one}}
[]
The instructions for building and running the samples are identical to the {{{../../ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1HowToBuildAndRunTheTutorialsSampleCode.html}instructions for Rome v0.1}}.

60
src/site/apt/ROMEReleases/ROME0.2Beta/index.apt Normal file
View file

@ -0,0 +1,60 @@
-----
ROME 0.2 Beta
-----
mkurz
-----
2011-08-15 14:31:23.934
-----
ROME 0.2 Beta
*Dependencies
* J2SE 1.4\+
* {{{http://www.jdom.org/}JDOM Beta 10}}
[]
*Downloads
* {{{./rome\-0.2\-src.zip}rome\-0.2\-src.zip}}
* {{{./rome\-0.2.tar.gz}rome\-0.2.tar.gz}}
* {{{./rome\-0.2.zip}rome\-0.2.zip}}
* {{{./rome\-0.2\-src.tar.gz}rome\-0.2\-src.tar.gz}}
* {{{./rome\-samples\-0.2\-src.tar.gz}rome\-samples\-0.2\-src.tar.gz}}
* {{{./rome\-samples\-0.2.tar.gz}rome\-samples\-0.2.tar.gz}}
* {{{./rome\-samples\-0.2.zip}rome\-samples\-0.2.zip}}
* {{{./rome\-samples\-0.2\-src.zip}rome\-samples\-0.2\-src.zip}}
[]
*Aditional Information
* {{{./RomeV0.2Tutorials/index.html}Tutorials}}
* Changes Log
[]
*Known Issues
* Same issues as Rome v0.1
[]

81
src/site/apt/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3HowToBuildAndRunTheTutorialsSampleCode.apt Normal file
View file

@ -0,0 +1,81 @@
-----
Rome v0.3, How to build and run the tutorials sample code
-----
mkurz
-----
2011-08-15 13:52:00.856
-----
Rome v0.3, How to build and run the tutorials sample code
*Building the samples with Maven
This is, as usual, the easiest way.
There's only one configuration step: Maven downloads dependencies from an online repository (by default ibiblio), to a local repository (on UNIX usually in <<<\~/.maven/repository>>>). Because the rome distribution is not yet on ibiblio, you need to add it yourself, either to your local repository, or to your own intranet maven repository if you have such a thing in your organization.
If you built Rome run maven jar:install in the rome project to install Rome's jar in your Maven repository.
If you got Rome binary distribution copy the Rome's jar file to your Maven repository (on UNIX that would be <<<cp rome\-0.3/rome\-0.3.jar   \~/.maven/repository/rome/jars/>>>).
Then building the samples it's easy as a pie, just run maven jar in the rome\-samples project and you are all set.
*Building the samples with Ant
Hopefully maven is helpful in supporting poor ant users who did not make the switch yet We generated an Ant build.xml file in order for you to be able to build rome\-samples with Ant. (Actually, Maven did it for us, the maven ant goal).
The targets present in the build.xml are very helpful, ant get\-deps will download from ibiblio to rome\-samples/target/lib all the jar files Rome depends on and are needed for building an application using Rome.
The only thing that will be left out is Rome's jar file itself: you'll need to copy it to the rome\-samples/target/lib directory (For example in UNIX would be <<<cp rome\-0.3/rome\-0.3.jar  rome\-samples/target/lib>>>, where rome\-0.3 is the binary distribution).
To build rome\-samples just run <<<ant jar>>>.
*Running the samples with Maven
The Maven goals for running the samples are defined in maven.xml. They should all generate the same file named toto, but somehow it ends up empty. However the output is correctly sent to the console. We'll fix that glitch later.
* <<<maven run\-agr>>> runs the FeedAggregator sample
* <<<maven run\-conv>>> runs the FeedConverter sample
* <<<maven run\-read>>> runs the FeedReader sample
* <<<maven run\-write>>> runs the FeedWriter sample
* <<<maven run\-sampleModule>>> runs the FeedConverter sample against a file with Sample Module data (shows off custom module plugin)
[]
*Running the samples with Ant
All ant targets for the samples generate the same file named toto: feel free to customize this build.xml to your own needs. Also today all these targets depends on the jar target, which represents some overhead if you have already built. Get rid of that once your project is well setup.
* <<<ant run\-aggr>>> runs the FeedAggregator sample
* <<<ant run\-conv>>> runs the FeedConverter sample
* <<<ant run\-read>>> runs the FeedReader sample
* <<<ant run\-write>>> runs the FeedWriter sample
* <<<ant run\-sampleModule>>> runs the FeedConverter sample against a file with Sample Module data (shows off custom module plugin)
[]

348
src/site/apt/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialDefiningACustomModuleBeanParserAndGenerator.apt Normal file
View file

@ -0,0 +1,348 @@
-----
Rome v0.3 Tutorial, Defining a Custom Module (bean, parser and generator)
-----
mkurz
-----
2011-08-15 13:58:16.611
-----
Rome v0.3 Tutorial, Defining a Custom Module (bean, parser and generator)
This tutorial walks through the steps of creating a custom module for syndication feeds that support additional namespaces (such as RSS 1.0, RSS 2.0 and Atom 0.3).
To understand this tutorial you should be familiar the with Rome API and with the use of modules in syndication feeds.
Out of the box Rome parsers and generators support plug\-ability of modules for RSS 1.0, RSS 2.0 and Atom 0.3 at both feed and item/entry levels. Also support for the Dublin Core and Syndication modules is provided.
The complete source for this tutorial is in the Rome samples bundle as well as in CVS.
*What is the intended outcome of the tutorial?
The goal is to add support for a hypothetical Sample Module by defining a module bean, module parser and module generator and the necessary configuration to wire the parser and generator to an RSS 1.0 parser and RSS 1.0 generator.
The sample module defines 3 elements, 'bar', 'foo' and 'date', where 'bar' and 'date' may occur at most once and the 'foo' element may occur several times. For example, a feed with the Sample Module data would look like:
+------+
<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns="http://purl.org/rss/1.0/"
xmlns:sample="http://rome.dev.java.net/module/sample/1.0">
<channel>
<title>RSS 1.0 Feed with Sample Module</title>
<link>http://rome.dev.java.net</link>
<description>This is a feed showing how to use a custom module with Rome</description>
<items>
<rdf:Seq>
<rdf:li resource="item01" />
<rdf:li resource="item02" />
</rdf:Seq>
</items>
<sample:bar>Channel bar</sample:bar>
<sample:foo>Channel first foo</sample:foo>
<sample:foo>Channel second foo</sample:foo>
</channel>
<item rdf:about="item01">
<title>Title of Item 01</title>
<link>http://rome.dev.java.net/item01</link>
<description>Item 01 does not have Sample module data</description>
</item>
<item rdf:about="item02">
<title>Title of Item 02</title>
<link>http://rome.dev.java.net/item02</link>
<description>Item 02 has Sample module data</description>
<sample:bar>Item 02 bar</sample:bar>
<sample:foo>Item 02 only foo</sample:foo>
<sample:date>2004-07-27T00:00+00:00</sample:date>
</item>
</rdf:RDF>
+------+
*Sample Module Bean
First we must start with the bean interface, SampleModuleI. SampleModuleI must extend ModuleI. The ModuleI interface defines the getUri() method, which will return a URI identifying the module. The ModuleI interface also extends the Cloneable, ToString and CopyFrom interfaces to ensure that the beans provide support for basic features as cloning, equality, toString, etc. (for more details on this check the Understanding the Rome common classes and interfaces document).
The SampleModule's URI is defined as a constant, accessible via the getURI() instance method. This is for convenience and good practice only.
Then the module defines 3 properties: bar (String), foos (List) and date (Date). The elements of the foos property list must be strings (wishing for Java 5 generics already?).
+------+
public interface SampleModuleI extends ModuleI,CopyFrom {
public static final String URI = "http://rome.dev.java.net/module/sample/1.0";
public String getBar();
public void setBar(String bar);
public List getFoos();
public void setFoos(List foos);
public Date getDate();
public void setDate(Date date);
}
+------+
Next we have to write the bean implementation, SampleModule.
SampleModule extends Module (the implementation counterpart of ModuleI). Module extends ObjectBean which provides equals, hashCode, toString and clone support for the properties of the class given in the constructor (SampleModuleI). Also the URI of the Sample module is indicated; it will be used by the Module.getUri() method.
+------+
public class SampleModule extends Module implements SampleModuleI {
...
public SampleModule() {
super(SampleModuleI.class,SampleModuleI.URI);
}
public String getBar() {
return _bar;
}
...
+------+
The module properties are just Java Bean properties. The only catch is to follow Rome semantics for Collection properties: in the case of a null value for the collection, an empty collection must be returned.. Also, following Rome semantics, all properties are by reference, including mutable ones.
+------+
public class SampleModule extends Module implements SampleModuleI {
private String _bar;
private List _foos;
private Date _date;
...
public void setBar(String bar) {
_bar = bar;
}
public List getFoos() {
return (_foos==null) ? (_foos=new ArrayList()) : _foos;
}
public void setFoos(List foos) {
_foos = foos;
}
public Date getDate() {
return _date;
}
public void setDate(Date date) {
_date = date;
}
+------+
Now the weird part: the bits for the CopyFrom logic. The Understanding the Rome common classes and interfaces document fully explains the CopyFrom logic in detail. In short, the CopyFrom interface is to support copying properties from one implementation of a bean (defined through an interface) to another implementation of the same bean.
The getInterface() method returns the bean interface of the implementation (this is necessary for collections containing sub\-classes such as a list of modules).
The copyFrom() method copies all the properties from the parameter object (which must be a SampleModuleI implementation) into the caller bean properties. Note that the copyFrom must do a deep copy.
+------+
public class SampleModule extends Module implements SampleModuleI {
...
public Class getInterface() {
return SampleModuleI.class;
}
public void copyFrom(Object obj) {
SampleModuleI sm = (SampleModuleI) obj;
setBar(sm.getBar());
List foos = new ArrayList(sm.getFoos()); // this is enough for the copy because the list elements are inmutable (Strings)
setFoos(foos);
setDate((Date)sm.getDate().clone()); // because Date is not inmutable.
}
}
+------+
*Sample Module Parser
The sample module parser must implement the ModuleParser interface. This interface defines 2 methods, getNamespaceUri() that returns the URI of the module and parse(Element) which extracts the module elements from the given Element.
The feed parsers will invoke the module parser with a feed element or with an item element. The module parser must look for module elements in the children of the given element. That is was the Sample parser is doing when looking for 'bar', 'foo' and 'date' children elements in the received element.
In the case of the 'foo' element it looks for all occurrences as the Sample module schema allows for more than one occurrence of the 'foo' element. A SampleModule bean is created and the found values are set into it. For the 'date' element it assumes its a date value in W3C datetime format.
If no Sample Module elements are found in the feed, the parse(Element) method returns null. This is to avoid having an empty instance of a module \-not present in the feed\- in the feed bean or in the item bean.
+------+
public class SampleModuleParser implements ModuleParser {
private static final Namespace SAMPLE_NS = Namespace.getNamespace("sample", SampleModuleI.URI);
public String getNamespaceUri() {
return SampleModuleI.URI;
}
public ModuleI parse(Element dcRoot) {
boolean foundSomething = false;
SampleModuleI fm = new SampleModule();
Element e = dcRoot.getChild("bar", SAMPLE_NS);
if (e != null) {
foundSomething = true;
fm.setBar(e.getText());
}
List eList = dcRoot.getChildren("foo", SAMPLE_NS);
if (eList.size() > 0) {
foundSomething = true;
fm.setFoos(parseFoos(eList));
}
e = dcRoot.getChild("date", SAMPLE_NS);
if (e != null) {
foundSomething = true;
fm.setDate(DateParser.parseW3CDateTime(e.getText()));
}
return (foundSomething) ? fm : null;
}
private List parseFoos(List eList) {
List foos = new ArrayList();
for (int i = 0; i < eList.size(); i++) {
Element e = (Element) eList.get(i);
foos.add(e.getText());
}
return foos;
}
}
+------+
*Sample Module Generator
The sample module generator must implement the ModuleGenerator interface. This interface defines 2 methods, getNamespaceUri() that returns the URI of the module and generate(ModuleI,Element) which injects the module data into the given Element.
The feed generator will invoke the module generator with a feed element or with an item element. The module generator must inject the module properties into the given element (which is a feed or an item). This injection has to be done using the right namespace.
If no Sample Module bean is in the feed bean the module generator is not invoked at all.
+------+
public class SampleModuleGenerator implements ModuleGenerator {
private static final Namespace SAMPLE_NS = Namespace.getNamespace("sample", SampleModuleI.URI);
public String getNamespaceUri() {
return SampleModuleI.URI;
}
public void generate(ModuleI module, Element element) {
// this is not necessary, it is done to avoid the namespace definition in every item.
Element root = element;
while (root.getParent()!=null && root.getParent() instanceof Element) {
root = (Element) element.getParent();
}
root.addNamespaceDeclaration(SAMPLE_NS);
SampleModuleI fm = (SampleModuleI)module;
if (fm.getBar() != null) {
element.addContent(generateSimpleElement("bar", fm.getBar()));
}
List foos = fm.getFoos();
for (int i = 0; i < foos.size(); i++) {
element.addContent(generateSimpleElement("foo",foos.get(i).toString()));
}
if (fm.getDate() != null) {
element.addContent(generateSimpleElement("date", DateParser.parseW3CDateTime(fm.getDate())));
}
}
protected Element generateSimpleElement(String name, String value) {
Element element = new Element(name, SAMPLE_NS);
element.addContent(value);
return element;
}
}
+------+
*Configuration to make Rome process Sample Module in feeds
The last step is to setup the configuration file to indicate to Rome how and when to use the Sample Module parser and generator.
The configuration is stored in a Properties file, 'rome.properties', that has to be in the root of the classpath or JAR where the Sample Module bean, parser and generator classes are.
You must indicate the syndication feed formats (ie RSS 1.0) that must be aware of the Sample Module. You must indicate if the Sample Module is available for feed or item elements, or for both. You must indicate both the parser and the generator classes.
Following is the 'rome.properties' file for the Sample Module, it's defined for RSS 1.0 only, for both feed and item elements.
+------+
# Parsers for RSS 1.0 feed modules
#
rss_1.0.feed.ModuleParser.classes=com.sun.syndication.samples.module.SampleModuleParser
# Parsers for RSS 1.0 item modules
#
rss_1.0.item.ModuleParser.classes=com.sun.syndication.samples.module.SampleModuleParser
# Generators for RSS 1.0 feed modules
#
rss_1.0.feed.ModuleGenerator.classes=com.sun.syndication.samples.module.SampleModuleGenerator
# Generators for RSS_1.0 entry modules
#
rss_1.0.item.ModuleGenerator.classes=com.sun.syndication.samples.module.SampleModuleGenerator
+------+
If you are defining more than one module, indicate the parser and generator implementation classes separated by commas or spaces.
*Using the Sample Module from the SyndFeedI beans
They will be there, just use them. You may get the SampleModuleI bean using the getModule(String Uri) method of the SyndFeedI bean and the SyndEntryI bean.
Adding or replacing a syndication feed parser, generator or converter is along the same lines of what it has been explained in the tutorial for modules. Eventually we'll have a doc on that too

148
src/site/apt/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.apt Normal file
View file

@ -0,0 +1,148 @@
-----
Rome v0.3 Tutorial, Using Rome to aggregate many syndication feeds into a single one
-----
mkurz
-----
2011-08-15 14:02:32.685
-----
Rome v0.3 Tutorial, Using Rome to aggregate many syndication feeds into a single one
<<Software requirements:>> J2SE 1.4\+, JDOM B10 and Rome 0.3.
Rome represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeedI interface. The SyndFeedI interfaces and its properties follow the Java Bean patterns. The default implementations provided with Rome are all lightweight classes.
Rome includes parsers to process syndication feeds into SyndFeedI instances. The SyndFeedInput class handles the parsers using the correct one based on the syndication feed being processed. The developer does not need to worry about selecting the right parser for a syndication feed, the SyndFeedInput will take care of it by peeking at the syndication feed structure. All it takes to read a syndication feed using Rome are the following 2 lines of code:
+------+
SyndFeedInput input = new SyndFeedInput();
SyndFeedI feed = input.build(new InputStreamReader(feedUrl.openStream()));
+------+
Obtaining the char based input stream has been simplified in this tutorial, the sample code in the distribution is a little more complex to handle charset encodings properly.
The first line creates a SyndFeedInput instance that will work with any syndication feed type (RSS and Atom versions). The second line instructs the SyndFeedInput to read the syndication feed from the InputStream of a URL pointing to the feed. The SyndFeedInput.build() method returns a SyndFeedI instance that can be easily processed.
Rome also includes generators to create syndication feeds out of SyndFeedI instances. The SyndFeedOutput class does this generation. The SyndFeedOutput will generate a syndication feed of the feed type indicated by the SyndFeedI object being output. The following two lines of code show how to create a syndication feed output from a SyndFeedI instance:
+------+
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,new PrintWriter(System.out));
+------+
The first line creates a SyndFeedOutput instance that will produce syndication feeds. It can output feeds of any type (rss_0.9, rss_0.91, rss_0.92, rss_0.93, rss_0.94, rss_1.0, rss_2.0 & atom_0.3), the SyndFeedI feedType property indicates the type. The second line writes the SyndFeedI as a syndication feed into the application's output.
SyndFeedI can also be created and populated within the code. For example:
+------+
SyndFeedI aggrFeed = new SyndFeed();
aggrFeed.setFeedType("rss_1.0");
aggrFeed.setTitle("Aggregated Feed");
aggrFeed.setDescription("Anonymous Aggregated Feed");
aggrFeed.setAuthor("anonymous");
aggrFeed.setLink("http://www.anonymous.com");
+------+
The snipped of code above creates a SyndFeedI instance using the default implementation provided by Rome, sets the feed type to RSS 1.0, sets the title, description, author and link properties of the feed.
SyndFeedI properties can be modified, assigned to other SyndFeedI instances, removed, etc. It's important to remember that the getters/setters semantics defined for all SyndFeedI properties (and properties of its properties) is a copy by reference, not by value. In other words if you alter the property of a SyndFeedI property you are altering the SyndFeedI. Or, another example, if you assign the list of entries of one SyndFeedI instance to another SyndFeedI isntance and then you modify the list or any of the entries in the list, you are modifying the entries of both SyndFeedI instances.
The following lines of code show how to copy the entries of a SyndFeedI instance being read (inFeed) into a SyndFeedI instance being created within the application (feed):
+------+
package com.sun.syndication.samples;
import java.net.URL;
import java.io.InputStreamReader;
import java.io.PrintWriter;
import java.util.List;
import java.util.ArrayList;
import com.sun.syndication.feed.synd.SyndFeedI;
import com.sun.syndication.feed.synd.SyndFeed;
import com.sun.syndication.io.SyndFeedOutput;
import com.sun.syndication.io.SyndFeedInput;
/**
* It aggregates a list of RSS/Atom feeds (they can be of different types)
* into a single feed of the specified type.
* <p>
* @author Alejandro Abdelnur
*
*/
public class FeedAggregator {
public static void main(String[] args) {
boolean ok = false;
if (args.length>=2) {
try {
String outputType = args[0];
SyndFeedI feed = new SyndFeed();
feed.setFeedType(outputType);
feed.setTitle("Aggregated Feed");
feed.setDescription("Anonymous Aggregated Feed");
feed.setAuthor("anonymous");
feed.setLink("http://www.anonymous.com");
List entries = new ArrayList();
feed.setEntries(entries);
for (int i=1;i<args.length;i++) {
URL inputUrl = new URL(args[i]);
SyndFeedInput input = new SyndFeedInput();
SyndFeedI inFeed = input.build(new InputStreamReader(inputUrl.openStream()));
entries.addAll(inFeed.getEntries());
}
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,new PrintWriter(System.out));
ok = true;
}
catch (Exception ex) {
System.out.println("ERROR: "+ex.getMessage());
}
}
if (!ok) {
System.out.println();
System.out.println("FeedAggregator aggregates different feeds into a single one.");
System.out.println("The first parameter must be the feed type for the aggregated feed.");
System.out.println(" [valid values are: rss_0.9, rss_0.91, rss_0.92, rss_0.93, ]");
System.out.println(" [ rss_0.94, rss_1.0, rss_2.0 & atom_0.3 ]");
System.out.println("The second to last parameters are the URLs of feeds to aggregate.");
System.out.println();
}
}
}
+------+

106
src/site/apt/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.apt Normal file
View file

@ -0,0 +1,106 @@
-----
Rome v0.3 Tutorial, Using Rome to convert a syndication feed from one type to another
-----
mkurz
-----
2011-08-15 14:03:59.552
-----
Rome v0.3 Tutorial, Using Rome to convert a syndication feed from one type to another
<<Software requirements:>> Synd J2SE 1.4\+, JDOM B10 and Rome 0.3.
Rome represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeedI interface. The SyndFeedI interfaces and its properties follow the Java Bean patterns. The default implementations provided with Rome are all lightweight classes.
Rome includes parsers to process syndication feeds into SyndFeedI instances. The SyndFeedInput class handles the parsers using the correct one based on the syndication feed being processed. The developer does not need to worry about selecting the right parser for a syndication feed, the SyndFeedInput will take care of it by peeking at the syndication feed structure. All it takes to read a syndication feed using Rome are the following 2 lines of code:
+------+
SyndFeedInput input = new SyndFeedInput();
SyndFeedI feed = input.build(new InputStreamReader(feedUrl.openStream()));
+------+
Obtaining the char based input stream has been simplified in this tutorial, the sample code in the distribution is a little more complex to handle charset encodings properly.
The first line creates a SyndFeedInput instance that will work with any syndication feed type (RSS and Atom versions). The second line instructs the SyndFeedInput to read the syndication feed from the InputStream of a URL pointing to the feed. The SyndFeedInput.build() method returns a SyndFeedI instance that can be easily processed.
Rome also includes generators to create syndication feeds out of SyndFeedI instances. The SyndFeedOutput class does this generation. The SyndFeedOutput will generate a syndication feed of the feed type indicated by the SyndFeedI object being output. The following two lines of code show how to create a syndication feed output from a SyndFeedI instance:
+------+
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,new PrintWriter(System.out));
+------+
The first line creates a SyndFeedOutput instance that will produce syndication feeds. It can output feeds of any type (rss_0.9, rss_0.91, rss_0.92, rss_0.93, rss_0.94, rss_1.0, rss_2.0 & atom_0.3), the SyndFeedI feedType property indicates the type. The second line writes the SyndFeedI as a syndication feed into the application's output.
Following is the full code for a Java application that reads a syndication feed and converts it to other syndication feed type, writing the converted feed to the application's output.
+------+
package com.sun.syndication.samples;
import java.net.URL;
import java.io.InputStreamReader;
import java.io.PrintWriter;
import com.sun.syndication.feed.synd.SyndFeedI;
import com.sun.syndication.io.SyndFeedInput;
import com.sun.syndication.io.SyndFeedOutput;
/**
* It Converts any RSS/Atom feed type to a an RSS/Atom feed of the
* specified type.
* <p>
* @author Alejandro Abdelnur
*
*/
public class FeedConverter {
public static void main(String[] args) {
boolean ok = false;
if (args.length==2) {
try {
String outputType = args[0];
URL feedUrl = new URL(args[1]);
SyndFeedInput input = new SyndFeedInput();
SyndFeedI feed = input.build(new InputStreamReader(feedUrl.openStream()));
feed.setFeedType(outputType);
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,new PrintWriter(System.out));
ok = true;
}
catch (Exception ex) {
System.out.println("ERROR: "+ex.getMessage());
}
}
if (!ok) {
System.out.println();
System.out.println("FeedConverter converts between syndication feeds types.");
System.out.println("The first parameter must be the feed type to convert to.");
System.out.println(" [valid values are: rss_0.9, rss_0.91, rss_0.92, rss_0.93, ]");
System.out.println(" [ rss_0.94, rss_1.0, rss_2.0 & atom_0.3 ]");
System.out.println("The second parameter must be the URL of the feed to convert.");
System.out.println();
}
}
}
+------+

204
src/site/apt/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToCreateAndWriteASyndicationFeed.apt Normal file
View file

@ -0,0 +1,204 @@
-----
Rome v0.3 Tutorial, Using Rome to create and write a syndication feed
-----
mkurz
-----
2011-08-15 14:00:50.552
-----
Rome v0.3 Tutorial, Using Rome to create and write a syndication feed
<<Software requirements:>> J2SE 1.4\+, JDOM B10 and Rome 0.3.
Rome represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeedI interface. The SyndFeedI interfaces and its properties follow the Java Bean patterns. The default implementations provided with Rome are all lightweight classes.
Creating a feed with SyndFeedI beans consists of creating beans and setting their properties. The following code fragments show how a SyndFeedI bean with 3 entries is created.
First the SyndFeedI instance is created, the preferred syndication format is set and the feed header info (title, link, description) is also set.
+------+
SyndFeedI feed = new SyndFeed();
feed.setFeedType(feedType);
feed.setTitle("Sample Feed (created with Rome)");
feed.setLink("http://rome.dev.java.net");
feed.setDescription("This feed has been created using Rome (Java syndication utilities");
+------+
Then a list for entries is created, entries are created and added to the list. Each entry is set with a title, link, published date and a description. The description for the first entry is plain test, for the third entry is HTML. After each entry is created is added to the list.
+------+
List entries = new ArrayList();
SyndEntryI entry;
SyndContentI description;
entry = new SyndEntry();
entry.setTitle("Rome v1.0");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome01");
entry.setPublishedDate(DATE_PARSER.parse("2004-06-08"));
description = new SyndContent();
description.setType("text/plain");
description.setValue("Initial release of Rome");
entry.setDescription(description);
entries.add(entry);
...
entry = new SyndEntry();
entry.setTitle("Rome v3.0");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome03");
entry.setPublishedDate(DATE_PARSER.parse("2004-07-27"));
description = new SyndContent();
description.setType("text/html");
description.setValue("<p>More Bug fixes, mor API changes, some new features and some Unit testing</p>"+
"<p>For details check the <a href=\"http://wiki.java.net/bin/view/Javawsxml/RomeChangesLog#RomeV03\">Changes Log</a></p>");
entry.setDescription(description);
entries.add(entry);
+------+
Finally the list with entries is added to the SyndFeedI bean.
+------+
feed.setEntries(entries);
+------+
The SyndFeedI bean is now ready to be written out to a syndication feed XML document. Note that any of supported syndication formats can be set in the feedType property.
Rome includes generators that allow producing syndication feed XML documents from SyndFeedI instances. The SyndFeedOutput class handles the generation of the syndication feed XML documents on any of the supported feed formats (RSS and Atom). The developer does not need to worry about selecting the right generator for a syndication feed, the SyndFeedOutput will take care of it by looking at the information in the SyndFeedI bean. All it takes to write a syndication feed XML document using Rome \-assuming you have a SyndFeedI bean and a Writer instance\- are the following lines of code:
+------+
SyndFeedI feed = ...;
Writer writer = ...;
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,writer);
+------+
First a SyndFeedOutput instance is created, this instance will work with any syndication feed type (RSS and Atom versions). Then the feed and the writer are given to the SyndFeedOutput instance, the SyndFeedOutput will write the syndication feed XML document represented by the SyndFeedI bean to the Writer stream.
Following is the full code for a Java application that creates a syndication feed and writes it to a file in the specified syndication format.
+------+
package com.sun.syndication.samples;
import com.sun.syndication.feed.synd.*;
import com.sun.syndication.io.SyndFeedOutput;
import java.io.FileWriter;
import java.io.Writer;
import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.List;
/**
* It creates a feed and writes it to a file.
* <p>
*
*/
public class FeedWriter {
private static final DateFormat DATE_PARSER = new SimpleDateFormat("yyyy-MM-dd");
public static void main(String[] args) {
boolean ok = false;
if (args.length==2) {
try {
String feedType = args[0];
String fileName = args[1];
SyndFeedI feed = new SyndFeed();
feed.setFeedType(feedType);
feed.setTitle("Sample Feed (created with Rome)");
feed.setLink("http://rome.dev.java.net");
feed.setDescription("This feed has been created using Rome (Java syndication utilities");
List entries = new ArrayList();
SyndEntryI entry;
SyndContentI description;
entry = new SyndEntry();
entry.setTitle("Rome v1.0");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome01");
entry.setPublishedDate(DATE_PARSER.parse("2004-06-08"));
description = new SyndContent();
description.setType("text/plain");
description.setValue("Initial release of Rome");
entry.setDescription(description);
entries.add(entry);
entry = new SyndEntry();
entry.setTitle("Rome v2.0");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome02");
entry.setPublishedDate(DATE_PARSER.parse("2004-06-16"));
description = new SyndContent();
description.setType("text/plain");
description.setValue("Bug fixes, minor API changes and some new features");
entry.setDescription(description);
entries.add(entry);
entry = new SyndEntry();
entry.setTitle("Rome v3.0");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome03");
entry.setPublishedDate(DATE_PARSER.parse("2004-07-27"));
description = new SyndContent();
description.setType("text/html");
description.setValue("<p>More Bug fixes, mor API changes, some new features and some Unit testing</p>"+
"<p>For details check the <a href=\"http://wiki.java.net/bin/view/Javawsxml/RomeChangesLog#RomeV03\">Changes Log</a></p>");
entry.setDescription(description);
entries.add(entry);
feed.setEntries(entries);
Writer writer = new FileWriter(fileName);
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,writer);
writer.close();
System.out.println("The feed has been written to the file ["+fileName+"]");
ok = true;
}
catch (Exception ex) {
ex.printStackTrace();
System.out.println("ERROR: "+ex.getMessage());
}
}
if (!ok) {
System.out.println();
System.out.println("FeedWriter creates a RSS/Atom feed and writes it to a file.");
System.out.println("The first parameter must be the syndication format for the feed");
System.out.println(" (rss_0.90, rss_0.91, rss_0.92, rss_0.93, rss_0.94, rss_1.0 rss_2.0 or atom_0.3)");
System.out.println("The second parameter must be the file name for the feed");
System.out.println();
}
}
}
+------+

95
src/site/apt/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToReadASyndicationFeed.apt Normal file
View file

@ -0,0 +1,95 @@
-----
Rome v0.3 Tutorial, Using Rome to read a syndication feed
-----
mkurz
-----
2011-08-15 13:53:37.700
-----
Rome v0.3 Tutorial, Using Rome to read a syndication feed
<<Software requirements:>> J2SE 1.4\+, JDOM B10 and Rome 0.3.
Rome represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeedI interface. The SyndFeedI interfaces and its properties follow the Java Bean patterns. The default implementations provided with Rome are all lightweight classes.
Rome includes parsers to process syndication feeds into SyndFeedI instances. The SyndFeedInput class handles the parsers using the correct one based on the syndication feed being processed. The developer does not need to worry about selecting the right parser for a syndication feed, the SyndFeedInput will take care of it by peeking at the syndication feed structure. All it takes to read a syndication feed using Rome are the following 2 lines of code:
+------+
SyndFeedInput input = new SyndFeedInput();
SyndFeedI feed = input.build(new InputStreamReader(feedUrl.openStream()));
+------+
The first line creates a SyndFeedInput instance that will work with any syndication feed type (RSS and Atom versions). The second line instructs the SyndFeedInput to read the syndication feed from the char based input stream of a URL pointing to the feed. The SyndFeedInput.build() method returns a SyndFeedI instance that can be easily processed.
Obtaining the char based input stream has been simplified in this tutorial, the sample code in the distribution is a little more complex to handle charset encodings properly.
The default SyndFeedI implementation has a detailed and clear toString() implementation. The following line just prints it to the application's output.
+------+
System.out.println(feed);
+------+
Following is the full code for a Java application that reads a syndication feed and prints the SyndFeedI bean to the application's output.
+------+
package com.sun.syndication.samples;
import java.net.URL;
import java.io.InputStreamReader;
import com.sun.syndication.feed.synd.SyndFeedI;
import com.sun.syndication.io.SyndFeedInput;
/**
* It Reads and prints any RSS/Atom feed type.
* <p>
* @author Alejandro Abdelnur
*
*/
public class FeedReader {
public static void main(String[] args) {
boolean ok = false;
if (args.length==1) {
try {
URL feedUrl = new URL(args[0]);
SyndFeedInput input = new SyndFeedInput();
SyndFeedI feed = input.build(new InputStreamReader(feedUrl.openStream()));
System.out.println(feed);
ok = true;
}
catch (Exception ex) {
ex.printStackTrace();
System.out.println("ERROR: "+ex.getMessage());
}
}
if (!ok) {
System.out.println();
System.out.println("FeedReader reads and prints any RSS/Atom feed type.");
System.out.println("The first parameter must be the URL of the feed to read.");
System.out.println();
}
}
}
+------+

29
src/site/apt/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/index.apt Normal file
View file

@ -0,0 +1,29 @@
-----
Rome v0.3 Tutorials
-----
mkurz
-----
2011-08-15 13:49:23.826
-----
Rome v0.3 Tutorials
The following tutorials show how to use the Rome API. They focus on the higher abstraction layer of classes offered by Rome, what we call the Synd\* classes. By using the Synd\* classes developers don't have to deal with the specifics of any syndication feed. They work with normalized feeds, the Synd\* feeds. This makes it much easier to write applications that have to deal with all the variety of syndication feed types in use today.
[[1]] {{{./RomeV0.3TutorialUsingRomeToReadASyndicationFeed.html}Using Rome to read a syndication feed}}
[[1]] {{{./RomeV0.3TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html}Using Rome to convert a syndication feed from one type to another}}
[[1]] {{{./RomeV0.3TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html}Using Rome to aggregate many syndication feeds into a single one}}
[[1]] {{{./RomeV0.3TutorialUsingRomeToCreateAndWriteASyndicationFeed.html}Using Rome to create and write a feed}} <<<(New)>>>
[[1]] {{{./RomeV0.3TutorialDefiningACustomModuleBeanParserAndGenerator.html}Defining a Custom Module bean, parser and generator}} <<<(New)>>>
[]
For instructions on how to build and run the samples used in the tutorials {{{./RomeV0.3HowToBuildAndRunTheTutorialsSampleCode.html}click here}}.

60
src/site/apt/ROMEReleases/ROME0.3Beta/index.apt Normal file
View file

@ -0,0 +1,60 @@
-----
ROME 0.3 Beta
-----
mkurz
-----
2011-08-15 13:47:07.902
-----
ROME 0.3 Beta
*Dependencies
* J2SE 1.4\+
* {{{http://www.jdom.org/}JDOM Beta 10}}
[]
*Downloads
* {{{./rome\-0.3\-src.zip}rome\-0.3\-src.zip}}
* {{{./rome\-0.3.tar.gz}rome\-0.3.tar.gz}}
* {{{./rome\-0.3.zip}rome\-0.3.zip}}
* {{{./rome\-0.3\-src.tar.gz}rome\-0.3\-src.tar.gz}}
* {{{./rome\-samples\-0.3\-src.tar.gz}rome\-samples\-0.3\-src.tar.gz}}
* {{{./rome\-samples\-0.3\-src.zip}rome\-samples\-0.3\-src.zip}}
[]
*Additional Information
* {{{./RomeV0.3Tutorials/index.html}Tutorials}} (2 New ones)
* Changes Log
[]
*Known Issues
* Same issues as Rome v0.1
* When processing XML documents with DTD (ie: Netscape RSS 0.91) if the XML parser implementation is not Xerces and the system does not have access ot the internet, the XML parser will fail.
* If the feed starts with a {{{http://www.unicode.org/faq/utf_bom.html#BOM}BOM}} the JAXP SAX parser may fail, using {{{http://xml.apache.org/xerces2\-j}Xerces 2.6.2}} addresses the problem.
[]

84
src/site/apt/ROMEReleases/ROME0.4Beta/RomeV0.4Tutorials/RomeV0.4HowToBuildAndRunTheTutorialsSampleCode.apt Normal file
View file

@ -0,0 +1,84 @@
-----
Rome v0.4, How to build and run the tutorials sample code
-----
mkurz
-----
2011-08-15 13:32:24.939
-----
Rome v0.4, How to build and run the tutorials sample code
*Building the samples with Maven
This is, as usual, the easiest way.
There's only one configuration step: Maven downloads dependencies from an online repository (by default ibiblio), to a local repository (on UNIX usually in \~/.maven/repository). Because the rome distribution is not yet on ibiblio, you need to add it yourself, either to your local repository, or to your own intranet maven repository if you have such a thing in your organization.
If you built Rome run maven jar:install in the rome project to install Rome's jar in your Maven repository.
If you got Rome binary distribution copy the Rome's jar file to your Maven repository (on UNIX that would be <<<cp rome\-0.4/rome\-0.4.jar   \~/.maven/repository/rome/jars/>>>).
Then building the samples it's easy as a pie, just run maven jar in the samples sub\-project and you are all set.
To build the sample Web Application, just run maven war in the samples sub\-project. The WAR file, <<<rome\-samples.war>>>, will be created under the <<<target>>> directory.
*Building the samples with Ant
The targets present in the build.xml are very helpful, ant get\-deps will download from ibiblio to rome\-samples/target/lib all the jar files Rome depends on and are needed for building an application using Rome.
In order to build the samples (or any subprojects), you'll need to first ensure that rome itself is built. You can do this simply by running ant in the project root directory.
Once this is done, change to the samples directory, and just run ant. This will produce two files, rome\-samples.jar which contains the sample applications, and rome\-samples.war which will contain a deployable web application war file for the FeedServlet sample.
*Running the samples with Maven
The Maven goals for running the samples are defined in maven.xml. They should all generate the same file named toto, but somehow it ends up empty. However the output is correctly sent to the console. We'll fix that glitch later.
* <<<maven run\-agr>>> runs the FeedAggregator sample
* <<<maven run\-conv>>> runs the FeedConverter sample
* <<<maven run\-read>>> runs the FeedReader sample
* <<<maven run\-write>>> runs the FeedWriter sample
* <<<maven run\-sampleModule>>> runs the FeedConverter sample against a file with Sample Module data (shows off custom module plugin)
[]
To run the sample Web Application you'll need to deploy the WAR file into your servlet container. If you are using Tomcat 4 or Tomcat 5 and the WAR file was dropped in the <<<$\{TOMCAT\}/webapps>>> directory the URL for the <<<FeedServlet>>> would be {{{http://localhost:8080/rome\-samples/feed}http://localhost:8080/rome\-samples/feed}} in a default localhost Tomcat installation.
*Running the samples with Ant
All ant targets for the samples generate the same file named toto: feel free to customize this build.xml to your own needs. Also today all these targets depends on the jar target, which represents some overhead if you have already built. Get rid of that once your project is well setup.
* <<<ant run\-aggr>>> runs the FeedAggregator sample
* <<<ant run\-conv>>> runs the FeedConverter sample
* <<<ant run\-read>>> runs the FeedReader sample
* <<<ant run\-write>>> runs the FeedWriter sample
* <<<ant run\-sampleModule>>> runs the FeedConverter sample against a file with Sample Module data (shows off custom module plugin)
[]

242
src/site/apt/ROMEReleases/ROME0.4Beta/RomeV0.4Tutorials/RomeV0.4TutorialUsingRomeWithinAServletToCreateAndReturnAFeed.apt Normal file
View file

@ -0,0 +1,242 @@
-----
Rome v0.4 Tutorial, Using Rome within a Servlet to create and return a feed
-----
mkurz
-----
2011-08-15 13:29:48.938
-----
Rome v0.4 Tutorial, Using Rome within a Servlet to create and return a feed
<<Software requirements:>> J2SE 1.4\+, Servlet Container 2.3\+, JDOM 1.0 and Rome 0.4.
This sample consists of a servlet that serves a feed as response. The feed type (RSS in any of its variants or Atom) can be specified as a URL parameter when requesting the feed. The returned feed is hardwired in the sample and it would be straight forward to modify the sample to generate the feed dynamically (i.e. from data stored in a database).
The core logic of the <<<FeedServlet>>> is in the following fragment of code:
+------+
public class FeedServlet extends HttpServlet {
...
public void doGet(HttpServletRequest req,HttpServletResponse res) throws IOException {
...
SyndFeed feed = getFeed(req);
String feedType = req.getParameter(FEED_TYPE);
feedType = (feedType!=null) ? feedType : _defaultFeedType;
feed.setFeedType(feedType);
res.setContentType(MIME_TYPE);
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,res.getWriter());
...
}
protected SyndFeed getFeed(HttpServletRequest req) throws IOException,FeedException {
SyndFeed feed = new SyndFeedImpl();
feed = ...
return feed;
}
}
+------+
The servlet returns a feed upon HTTP GET requests with the <<<doGet()>>> method.
First the <<<SyndFeed>>> bean is obtained by invoking the <<<getFeed()>>> method, the request object is passed as it could be used to obtain request contextual information to create the feed. How to create a feed using SyndFeed bean is explained in detail in the {{{../../../HowRomeWorks/RomeV0.4TutorialUsingRomeToCreateAndWriteASyndicationFeed.html}Using Rome to create and write a feed}} Tutorial.
Then the feed type of the response is determined, first looking at the request parameters and falling back to a default feed type (specified by a servlet init parameter) if the type is not indicated in the request parameters. Setting the feed type in the feed bean will indicate the <<<SyndFeedOutput>>> the feed type to output.
Finally, the response is set with the proper content type (the MIME_TYPE constant is 'application/xml; charset\=UTF\-8') and the feed is written to response writer using the <<<SyndFeedOutput>>> output classes.
Following is the full code for the servlet.
+------+
package com.sun.syndication.samples.servlet;
import com.sun.syndication.feed.synd.*;
import com.sun.syndication.io.FeedException;
import com.sun.syndication.io.SyndFeedOutput;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.text.DateFormat;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.List;
/**
* Sample Servlet that serves a feed created with Rome.
* <p>
* The feed type is determined by the 'type' request parameter, if the parameter is missing it defaults
* to the 'default.feed.type' servlet init parameter, if the init parameter is missing it defaults to 'atom_0.3'
* <p>
* @author Alejandro Abdelnur
*
*/
public class FeedServlet extends HttpServlet {
private static final String DEFAULT_FEED_TYPE = "default.feed.type";
private static final String FEED_TYPE = "type";
private static final String MIME_TYPE = "application/xml; charset=UTF-8";
private static final String COULD_NOT_GENERATE_FEED_ERROR = "Could not generate feed";
private static final DateFormat DATE_PARSER = new SimpleDateFormat("yyyy-MM-dd");
private String _defaultFeedType;
public void init() {
_defaultFeedType = getServletConfig().getInitParameter(DEFAULT_FEED_TYPE);
_defaultFeedType = (_defaultFeedType!=null) ? _defaultFeedType : "atom_0.3";
}
public void doGet(HttpServletRequest req,HttpServletResponse res) throws IOException {
try {
SyndFeed feed = getFeed(req);
String feedType = req.getParameter(FEED_TYPE);
feedType = (feedType!=null) ? feedType : _defaultFeedType;
feed.setFeedType(feedType);
res.setContentType(MIME_TYPE);
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,res.getWriter());
}
catch (FeedException ex) {
String msg = COULD_NOT_GENERATE_FEED_ERROR;
log(msg,ex);
res.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR,msg);
}
}
protected SyndFeed getFeed(HttpServletRequest req) throws IOException,FeedException {
SyndFeed feed = new SyndFeedImpl();
feed.setTitle("Sample Feed (created with Rome)");
feed.setLink("http://rome.dev.java.net");
feed.setDescription("This feed has been created using Rome (Java syndication utilities");
List entries = new ArrayList();
SyndEntry entry;
SyndContent description;
entry = new SyndEntryImpl();
entry.setTitle("Rome v0.1");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome01");
try {
entry.setPublishedDate(DATE_PARSER.parse("2004-06-08"));
}
catch (ParseException ex) {
// IT CANNOT HAPPEN WITH THIS SAMPLE
}
description = new SyndContentImpl();
description.setType("text/plain");
description.setValue("Initial release of Rome");
entry.setDescription(description);
entries.add(entry);
entry = new SyndEntryImpl();
entry.setTitle("Rome v0.2");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome02");
try {
entry.setPublishedDate(DATE_PARSER.parse("2004-06-16"));
}
catch (ParseException ex) {
// IT CANNOT HAPPEN WITH THIS SAMPLE
}
description = new SyndContentImpl();
description.setType("text/plain");
description.setValue("Bug fixes, minor API changes and some new features"+
"<p>For details check the <a href=\"http://wiki.java.net/bin/view/Javawsxml/RomeChangesLog#RomeV02\">Changes Log for 0.2</a></p>");
entry.setDescription(description);
entries.add(entry);
entry = new SyndEntryImpl();
entry.setTitle("Rome v0.3");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome03");
try {
entry.setPublishedDate(DATE_PARSER.parse("2004-07-27"));
}
catch (ParseException ex) {
// IT CANNOT HAPPEN WITH THIS SAMPLE
}
description = new SyndContentImpl();
description.setType("text/html");
description.setValue("<p>Bug fixes, API changes, some new features and some Unit testing</p>"+
"<p>For details check the <a href=\"http://wiki.java.net/bin/view/Javawsxml/RomeChangesLog#RomeV03\">Changes Log for 0.3</a></p>");
entry.setDescription(description);
entries.add(entry);
entry = new SyndEntryImpl();
entry.setTitle("Rome v0.4");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome04");
try {
entry.setPublishedDate(DATE_PARSER.parse("2004-09-24"));
}
catch (ParseException ex) {
// IT CANNOT HAPPEN WITH THIS SAMPLE
}
description = new SyndContentImpl();
description.setType("text/html");
description.setValue("<p>Bug fixes, API changes, some new features, Unit testing completed</p>"+
"<p>For details check the <a href=\"http://wiki.java.net/bin/view/Javawsxml/RomeChangesLog#RomeV04\">Changes Log for 0.4</a></p>");
entry.setDescription(description);
entries.add(entry);
feed.setEntries(entries);
return feed;
}
}
+------+
To use the <<<FeedServlet>>> we need to create a Web Application. For the Web Application we need a deployment descriptor, the <<<web.xml>>> file:
+------+
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
<display-name>Rome Samples</display-name>
<servlet>
<servlet-name>FeedServlet</servlet-name>
<servlet-class>com.sun.syndication.samples.servlet.FeedServlet</servlet-class>
<init-param>
<param-name>default.feed.type</param-name>
<param-value>rss_2.0</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>FeedServlet</servlet-name>
<url-pattern>/feed</url-pattern>
</servlet-mapping>
</web-app>
+------+
To build the sample Web Application, just run maven war in the samples sub\-project. The WAR file, <<<rome\-samples.war>>>, will be created under the <<<target>>> directory. Deploy the WAR in a servlet container and the <<<FeedServlet>>> should be up an running. If you are using Tomcat 4 or Tomcat 5 and the WAR file was dropped in the <<<$\{TOMCAT\}/webapps>>> directory the URL for the <<<FeedServlet>>> would be {{{http://localhost:8080/rome\-samples/feed}http://localhost:8080/rome\-samples/feed}} in a default localhost Tomcat installation.

31
src/site/apt/ROMEReleases/ROME0.4Beta/RomeV0.4Tutorials/index.apt Normal file
View file

@ -0,0 +1,31 @@
-----
Rome v0.4 Tutorials
-----
mkurz
-----
2011-08-15 13:26:41.706
-----
Rome v0.4 Tutorials
The following tutorials show how to use the Rome API. They focus on the higher abstraction layer of classes offered by Rome, what we call the Synd\* classes. By using the Synd\* classes developers don't have to deal with the specifics of any syndication feed. They work with normalized feeds, the Synd\* feeds. This makes it much easier to write applications that have to deal with all the variety of syndication feed types in use today.
[[1]] {{{../../../HowRomeWorks/RomeV0.4TutorialUsingRomeToReadASyndicationFeed.html}Using Rome to read a syndication feed}}
[[1]] {{{../../../HowRomeWorks/RomeV0.4TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html}Using Rome to convert a syndication feed from one type to another}}
[[1]] {{{../../../HowRomeWorks/RomeV0.4TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html}Using Rome to aggregate many syndication feeds into a single one}}
[[1]] {{{../../../HowRomeWorks/RomeV0.4TutorialUsingRomeToCreateAndWriteASyndicationFeed.html}Using Rome to create and write a feed}}
[[1]] {{{../../../HowRomeWorks/RomeV0.4TutorialDefiningACustomModuleBeanParserAndGenerator.html}Defining a Custom Module bean, parser and generator}}
[[1]] {{{./RomeV0.4TutorialUsingRomeWithinAServletToCreateAndReturnAFeed.html}Using Rome within a Servlet to create and return a feed}} <<<(NEW)>>>
[]
For instructions on how to build and run the samples used in the tutorials {{{./RomeV0.4HowToBuildAndRunTheTutorialsSampleCode.html}click here}}.

94
src/site/apt/ROMEReleases/ROME0.4Beta/index.apt Normal file
View file

@ -0,0 +1,94 @@
-----
ROME 0.4 Beta
-----
mkurz
-----
2011-08-15 13:35:59.126
-----
ROME 0.4 Beta
*What is New, Highlights
* Changed naming convention of bean interfaces and implementations (i.e.: SyndFeedI/SyndFeed are now SyndFeed/SyndFeedImpl)
* New XmlReader that handles charset encoding as defined by the XML 1.0 specification and RFC 3023
* Support of RSS 0.91 Netscape and RSS 0.91 Userland as distinct feed types
* All feed types have Modules support
* Added checks to generators reducing the chances of generating invalid feeds
* Comprehensive Unit testing
* Bug fixes
* More documentation and samples
* Dependencies, upgraded to JDom 1.0 and removed Xerces
[]
*Dependencies
* J2SE 1.4\+
* {{{http://www.jdom.org/}JDOM 1.0}}
[]
*Downloads
* {{{./rome\-0.4\-src.zip}rome\-0.4\-src.zip}}
* {{{./rome\-0.4.tar.gz}rome\-0.4.tar.gz}}
* {{{./rome\-0.4.zip}rome\-0.4.zip}}
* {{{./rome\-0.4\-src.tar.gz}rome\-0.4\-src.tar.gz}}
* {{{./rome\-samples\-0.4\-src.tar.gz}rome\-samples\-0.4\-src.tar.gz}}
* {{{./rome\-samples\-0.4\-src.zip}rome\-samples\-0.4\-src.zip}}
[]
*Additional Information
* {{{./RomeV0.4Tutorials/index.html}Tutorials}}
* {{{../../ChangeLog.html}Changes Log}}
* Inside ROME, How Things Work
* {{{../../HowRomeWorks/index.html}How ROME Works}}, Understanding Rome (a detailed overview by Dave Johnson)
* {{{../../HowRomeWorks/UnderstandingTheRomeCommonClassesAndInterfaces.html}Rome common Package}}, bean utilities, enums, copying and clonning
* {{{../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEPluginsMechanism.html}ROME Plugins Mechanism}}, bootstrap, adding and changing parsers, generators, converters and modules
* {{{../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html}Feeds Date Elements}}, how Date data is mapped to SyndFeed and SyndEntry
* {{{../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.html}Feed and Entry URI Mapping}}, how SyndFeed and SyndEntry 'uri' properties map to concrete feed elements
* {{{../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.html}XML Charset Encoding Detection}}, how Rome helps getting the right charset encoding
[]
*Known Issues
None.

26
src/site/apt/ROMEReleases/ROME0.5Beta/ROMET-Shirt.apt Normal file
View file

@ -0,0 +1,26 @@
-----
ROME T-Shirt
-----
mkurz
-----
2011-08-15 12:34:25.248
-----
ROME T\-Shirt
I made it quickly before taking a plane, and ruined my iron when trying to press it myself on a T\-shirt, but it's better than nothing and a T\-shirt is vital to an open source project!
It's at {{{http://www.cafepress.com/chanezon.13794826}http://www.cafepress.com/chanezon.13794826}}
Else just print the design yourself and iron it on a T\-shirt (advice from P@ the practical guy: don't try to iron glossy paper photo on a T\-shirt
[http://blogs.sun.com/roller/resources/pat/_rome-t-shirt.png]
\-\- {{{http://wiki.java.net/twiki/bin/view/Main/PatrickChanezon}PatrickChanezon}} \- 10 Jan 2005

94
src/site/apt/ROMEReleases/ROME0.5Beta/index.apt Normal file
View file

@ -0,0 +1,94 @@
-----
ROME 0.5 Beta
-----
mkurz
-----
2011-08-15 12:32:36.814
-----
ROME 0.5 Beta
*What is New, Highlights
* Removed common package and classes from the public API
* Removed Enum class, using constants now
* XmlReader now has a lenient behavior for charset encoding detection
* Bug fixes
* {{{./ROMET\-Shirt.html}ROME T\-Shirt (rome)}}
[]
*Dependencies
* J2SE 1.4\+
* {{{http://www.jdom.org/}JDOM 1.0}}
[]
*Downloads
* {{{./rome\-0.5\-src.zip}rome\-0.5\-src.zip}}
* {{{./rome\-0.5.tar.gz}rome\-0.5.tar.gz}}
* {{{./rome\-0.5.zip}rome\-0.5.zip}}
* {{{./rome\-0.5\-src.tar.gz}rome\-0.5\-src.tar.gz}}
* {{{./rome\-samples\-0.5\-src.tar.gz}rome\-samples\-0.5\-src.tar.gz}}
* {{{./rome\-samples\-0.5\-src.zip}rome\-samples\-0.5\-src.zip}}
[]
*Additional Information
* {{{../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/index.html}Tutorials}}
* {{{../../ChangeLog.html}Changes Log}}
* Inside ROME, How Things Work
* {{{../../HowRomeWorks/index.html}How ROME Works}}, Understanding ROME, a detailed overview by Dave Johnson (This doc is based on ROME v0.4)
* {{{../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEPluginsMechanism.html}ROME Plugins Mechanism}}, bootstrap, adding and changing parsers, generators, converters and modules
* {{{../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html}Feeds Date Elements}}, how Date data is mapped to SyndFeed and SyndEntry
* {{{../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.html}Feed and Entry URI Mapping}}, how SyndFeed and SyndEntry 'uri' properties map to concrete feed elements
* {{{../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.html}XML Charset Encoding Detection}}, how ROME helps getting the right charset encoding
* {{{../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialDefiningACustomModuleBeanParserAndGenerator.html}Creating a custom Module}}, creating all necessary pieces, bean, parser and generator
* {{{../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/TheCopyFromInterface.html}The CopyFrom interface}}
* Implementation documents
* {{{../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/UnderstandingRssAndAtOMUtilitiEsROMEBeanUtilities.html}ROME bean utilities, equals, toString and clonning}}
[]
*Known Issues
None.

89
src/site/apt/ROMEReleases/ROME0.6Beta.apt Normal file
View file

@ -0,0 +1,89 @@
-----
ROME 0.6 Beta
-----
mkurz
-----
2011-08-15 12:36:05.599
-----
ROME 0.6 Beta
Normally each release of ROME includes a whole new set of Wiki pages with the corresponding version number. ROME 0.6 is reusing ROME 0.5 Wiki pages as most of the changes are internal and the documentation has not changed.
*What is New, Highlights
* Bug fixes
[]
*Dependencies
* J2SE 1.4\+
* {{{http://www.jdom.org/}JDOM 1.0}}
[]
*Downloads
* {{{./rome\-0.6\-src.zip}rome\-0.6\-src.zip}}
* {{{./rome\-0.6.tar.gz}rome\-0.6.tar.gz}}
* {{{./rome\-0.6.zip}rome\-0.6.zip}}
* {{{./rome\-0.6\-src.tar.gz}rome\-0.6\-src.tar.gz}}
* {{{./rome\-samples\-0.6\-src.tar.gz}rome\-samples\-0.6\-src.tar.gz}}
* {{{./rome\-samples\-0.6\-src.zip}rome\-samples\-0.6\-src.zip}}
[]
*Additional Information
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/index.html}Tutorials}}
* {{{../ChangeLog.html}Changes Log}}
* Inside ROME, How Things Work
* {{{../HowRomeWorks/index.html}How ROME Works}}, Understanding ROME, a detailed overview by Dave Johnson (This doc is based on ROME v0.4)
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEPluginsMechanism.html}ROME Plugins Mechanism}}, bootstrap, adding and changing parsers, generators, converters and modules
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html}Feeds Date Elements}}, how Date data is mapped to SyndFeed and SyndEntry
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.html}Feed and Entry URI Mapping}}, how SyndFeed and SyndEntry 'uri' properties map to concrete feed elements
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.html}XML Charset Encoding Detection}}, how ROME helps getting the right charset encoding
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialDefiningACustomModuleBeanParserAndGenerator.html}Creating a custom Module}}, creating all necessary pieces, bean, parser and generator
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/TheCopyFromInterface.html}The CopyFrom interface}}
* Implementation documents
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/UnderstandingRssAndAtOMUtilitiEsROMEBeanUtilities.html}ROME bean utilities, equals, toString and clonning}}
[]
*Known Issues
None.

91
src/site/apt/ROMEReleases/ROME0.7Beta.apt Normal file
View file

@ -0,0 +1,91 @@
-----
ROME 0.7 Beta
-----
mkurz
-----
2011-08-15 12:08:20.698
-----
ROME 0.7 Beta
Normally each release of ROME includes a whole new set of Wiki pages with the corresponding version number. ROME 0.7 is reusing ROME 0.5 Wiki pages as most of the changes are internal.
*What is New, Highlights
* We got a cool logo
* Bug fixes
* Several Date and time parsing improvements including support for custom parsing masks
[]
*Dependencies
* J2SE 1.4\+
* {{{http://www.jdom.org/}JDOM 1.0}}
[]
*Downloads
* {{{./rome\-0.7\-src.zip}rome\-0.7\-src.zip}}
* {{{./rome\-0.7.tar.gz}rome\-0.7.tar.gz}}
* {{{./rome\-0.7.zip}rome\-0.7.zip}}
* {{{./rome\-0.7\-src.tar.gz}rome\-0.7\-src.tar.gz}}
* {{{./rome\-samples\-0.7\-src.tar.gz}rome\-samples\-0.7\-src.tar.gz}}
* {{{./rome\-samples\-0.7\-src.zip}rome\-samples\-0.7\-src.zip}}
[]
*Additional Information
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/index.html}Tutorials}}
* {{{../ChangeLog.html}Changes Log}}
* Inside ROME, How Things Work
* {{{../HowRomeWorks/index.html}How ROME Works}}, Understanding ROME, a detailed overview by Dave Johnson (This doc is based on ROME v0.4)
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEPluginsMechanism.html}ROME Plugins Mechanism}}, bootstrap, adding and changing parsers, generators, converters and modules
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html}Feeds Date Elements}}, how Date data is mapped to SyndFeed and SyndEntry
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.html}Feed and Entry URI Mapping}}, how SyndFeed and SyndEntry 'uri' properties map to concrete feed elements
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.html}XML Charset Encoding Detection}}, how ROME helps getting the right charset encoding
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialDefiningACustomModuleBeanParserAndGenerator.html}Creating a custom Module}}, creating all necessary pieces, bean, parser and generator
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/TheCopyFromInterface.html}The CopyFrom interface}}
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/UnderstandingRssAndAtOMUtilitiEsROMEBeanUtilities.html}ROME bean utilities, equals, toString and clonning}}
* {{{../RssAndAtOMUtiliEsROMEV0.7DateAndTimeParsing.html}Customizing Date and time parsing}} in the rome.properties file <<NEW>>
[]
*Known Issues
None.

94
src/site/apt/ROMEReleases/ROME0.8Beta.apt Normal file
View file

@ -0,0 +1,94 @@
-----
ROME 0.8 Beta
-----
mkurz
-----
2011-08-15 12:35:29.441
-----
ROME 0.8 Beta
Normally each release of ROME includes a whole new set of Wiki pages with the corresponding version number. ROME 0.8 is reusing ROME 0.7 Wiki pages as much as possible.
*What is New, Highlights
* ROME now supports the final version of the Atom Syndication Format {{{http://www.ietf.org/rfc/rfc4287}RFC 4287}}: let's Nuke all these feeds! <<NEW>>
* Enclosure support at the Synd level, for all our podcaster friends
* Bug fixes
* details in the ChangeList
* Modules galore: Content, iTunes Podcast, Slash, Google Base, Creative Commons, MediaRSS
[]
*Dependencies
* J2SE 1.4\+
* {{{http://www.jdom.org/}JDOM 1.0}}
[]
*Downloads
* {{{./rome\-0.8\-src.zip}rome\-0.8\-src.zip}}
* {{{./rome\-0.8.tar.gz}rome\-0.8.tar.gz}}
* {{{./rome\-0.8.zip}rome\-0.8.zip}}
* {{{./rome\-0.8\-src.tar.gz}rome\-0.8\-src.tar.gz}}
[]
*Additional Information
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/index.html}Tutorials}}
* {{{../ChangeLog.html}Changes Log}}
* Inside ROME, How Things Work
* {{{../HowRomeWorks/index.html}How ROME Works}}, Understanding ROME, a detailed overview by Dave Johnson (This doc is based on ROME v0.4)
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEPluginsMechanism.html}ROME Plugins Mechanism}}, bootstrap, adding and changing parsers, generators, converters and modules
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html}Feeds Date Elements}}, how Date data is mapped to SyndFeed and SyndEntry
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.html}Feed and Entry URI Mapping}}, how SyndFeed and SyndEntry 'uri' properties map to concrete feed elements
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.html}XML Charset Encoding Detection}}, how ROME helps getting the right charset encoding
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialDefiningACustomModuleBeanParserAndGenerator.html}Creating a custom Module}}, creating all necessary pieces, bean, parser and generator
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/TheCopyFromInterface.html}The CopyFrom interface}}
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/UnderstandingRssAndAtOMUtilitiEsROMEBeanUtilities.html}ROME bean utilities, equals, toString and clonning}}
* {{{../RssAndAtOMUtiliEsROMEV0.7DateAndTimeParsing.html}Customizing Date and time parsing}} in the rome.properties file <<NEW>>
[]
*Known Issues
None.
\-\- {{{http://wiki.java.net/twiki/bin/view/Main/PatrickChanezon}PatrickChanezon}} \- 02 Feb 2006

100
src/site/apt/ROMEReleases/ROME0.9Beta.apt Normal file
View file

@ -0,0 +1,100 @@
-----
ROME 0.9 Beta
-----
mkurz
-----
2011-08-15 11:58:02.820
-----
ROME 0.9 Beta
Normally each release of ROME includes a whole new set of Wiki pages with the corresponding version number. ROME 0.9 is reusing ROME 0.8 Wiki pages as much as possible.
*What is New, Highlights
* Better support for RSS feeds that use
* Better mapping for RSS description/content and Atom summary/content
* Numerous bug fixes
* Details in the ChangeList
[]
*Dependencies
* J2SE 1.4\+
* {{{http://www.jdom.org/}JDOM 1.0}}
[]
*Downloads
* {{{./rome\-samples\-0.9.tar.gz}rome\-samples\-0.9.tar.gz}}
* {{{./rome\-0.9.tar.gz}rome\-0.9.tar.gz}}
* {{{./rome\-0.9\-src.zip}rome\-0.9\-src.zip}}
* {{{./rome\-0.9\-src.tar.gz}rome\-0.9\-src.tar.gz}}
* {{{./rome\-0.9.zip}rome\-0.9.zip}}
* {{{./rome\-samples\-0.9.zip}rome\-samples\-0.9.zip}}
* {{{./rome\-samples\-0.9\-src.tar.gz}rome\-samples\-0.9\-src.tar.gz}}
* {{{./rome\-samples\-0.9\-src.zip}rome\-samples\-0.9\-src.zip}}
[]
*Additional Information
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/index.html}Tutorials}}
* {{{../ChangeLog.html}Changes Log}}
* Inside ROME, How Things Work
* {{{../HowRomeWorks/index.html}How ROME Works}}, Understanding ROME, a detailed overview by Dave Johnson (This doc is based on ROME v0.4)
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEPluginsMechanism.html}ROME Plugins Mechanism}}, bootstrap, adding and changing parsers, generators, converters and modules
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html}Feeds Date Elements}}, how Date data is mapped to SyndFeed and SyndEntry
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.html}Feed and Entry URI Mapping}}, how SyndFeed and SyndEntry 'uri' properties map to concrete feed elements
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.html}XML Charset Encoding Detection}}, how ROME helps getting the right charset encoding
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialDefiningACustomModuleBeanParserAndGenerator.html}Creating a custom Module}}, creating all necessary pieces, bean, parser and generator
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/TheCopyFromInterface.html}The CopyFrom interface}}
* {{{../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/UnderstandingRssAndAtOMUtilitiEsROMEBeanUtilities.html}ROME bean utilities, equals, toString and clonning}}
* {{{../RssAndAtOMUtiliEsROMEV0.7DateAndTimeParsing.html}Customizing Date and time parsing}} in the rome.properties file <<NEW>>
[]
*Known Issues
None.
\-\- Main.snoopdave \- 06 Dec 2006

68
src/site/apt/ROMEReleases/ROME1.0RC1.apt Normal file
View file

@ -0,0 +1,68 @@
-----
ROME 1.0 RC1
-----
mkurz
-----
2011-08-14 17:22:56.542
-----
ROME 1.0 RC1
*Rss and atOM utiliEs (ROME) v1.0 RC1 (16 Jul 2008)
Normally each release of ROME includes a whole new set of Wiki pages with the corresponding version number. ROME 1.0 is reusing wikis from previous versions as there are not significant changes.
*What is New, Highlights
* Several XmlReader fixes
* Several Atom 1.0 bean, parser and generator fixes
* Some RSS fixes
* Removal of unused namespaces
* Details in the {{{../ChangeLog.html}change log}}
[]
*Dependencies
* J2SE 1.4\+
* {{{http://www.jdom.org/}JDOM 1.0}}
[]
*Downloads
* {{{./rome\-samples\-1.0RC1\-src.zip}rome\-samples\-1.0RC1\-src.zip}}
* {{{./rome\-1.0RC1\-src.zip}rome\-1.0RC1\-src.zip}}
* {{{./rome\-1.0RC1.tar.gz}rome\-1.0RC1.tar.gz}}
* {{{./rome\-1.0RC1.zip}rome\-1.0RC1.zip}}
* {{{./rome\-1.0RC1\-src.tar.gz}rome\-1.0RC1\-src.tar.gz}}
* {{{./rome\-samples\-1.0RC1\-src.tar.gz}rome\-samples\-1.0RC1\-src.tar.gz}}
[]
*Documentation
* {{{http://rome.dev.java.net/apidocs/1_0RC1/overview\-summary.html}Javadocs}}
[]

58
src/site/apt/ROMEReleases/ROME1.0RC2.apt Normal file
View file

@ -0,0 +1,58 @@
-----
ROME 1.0 RC2
-----
mkurz
-----
2011-08-14 17:19:36.245
-----
ROME 1.0 RC2
*What is New, Highlights
* ROME is now {{{../HowToBuildRome.html}built using Maven 2}}
* ROME jars are now available in the {{{../ROMEAndMaven2.html}java.net Maven repository}}
* More lenient handling of Number formats during parsing
* Better date parsing for Atom dates
* Complete details in the {{{../ChangeLog.html}change log}}
[]
*Dependencies
* {{{http://wiki.java.net/twiki/bin/view/Javawsxml/J2SE}J2SE}} 1.4\+
* {{{http://www.jdom.org/}JDOM 1.0}}
[]
*Downloads
* {{{./rome\-fetcher\-1.0RC2\-src.zip}rome\-fetcher\-1.0RC2\-src.zip}}
* {{{./rome\-1.0RC2.jar}rome\-1.0RC2.jar}}
* {{{./rome\-1.0RC2\-javadoc.jar}rome\-1.0RC2\-javadoc.jar}}
* {{{./rome\-1.0RC2\-sources.jar}rome\-1.0RC2\-sources.jar}}
[]
*Documentation
* {{{http://rome.dev.java.net/apidocs/1_0RC2/overview\-summary.html}Javadocs}}
[]

66
src/site/apt/ROMEReleases/ROME1.0Release.apt Normal file
View file

@ -0,0 +1,66 @@
-----
ROME 1.0 Release
-----
mkurz
-----
2011-08-15 14:48:27.959
-----
ROME 1.0 Release
<ROME 1.0 was released on March 12, 2009>
*What is New / Highlights
Normally each release of ROME includes a whole new set of Wiki pages with the corresponding version number. ROME 1.0 is reusing wikis from previous versions as there are not significant changes.
* ROME can now optionally preserve WireFeed (ie, Atom/RSS specific) data and make it available via the SyndFeed data model. See {{{../PreservingWireFeeds.html}PreservingWireFeeds}} for further details
[]
* Complete details in the {{{../ChangeLog.html}change log}}
[]
**Downloads
* {{{./rome\-1.0.jar}rome\-1.0.jar}}
* {{{./rome\-1.0\-sources.jar}rome\-1.0\-sources.jar}}
* {{{./rome\-1.0\-javadoc.jar}rome\-1.0\-javadoc.jar}}
* {{{./rome\-1.0.jar}rome\-1.0.jar}}
* {{{./rome\-1.0\-javadoc.jar}rome\-1.0\-javadoc.jar}}
* {{{./rome\-1.0\-sources.jar}rome\-1.0\-sources.jar}}
[]
**Dependencies
* J2SE 1.4\+
* {{{http://www.jdom.org/}JDOM 1.0}}\
[]
**Documentation
* {{{http://rome.dev.java.net/apidocs/1_0/overview\-summary.html}Javadocs}}
[]

38
src/site/apt/ROMEReleases/index.apt Normal file
View file

@ -0,0 +1,38 @@
-----
ROME Releases
-----
mkurz
-----
2011-08-15 14:51:42.765
-----
ROME Releases
*----+--+
||Version||Release Date|
*----+--+
|{{{./ROME1.0Release.html}ROME 1.0}}|March 12, 2009|
*----+--+
|{{{./ROME1.0RC2.html}Rome v1.0 RC2}}|Jan 9, 2009|
*----+--+
|{{{./ROME1.0RC1.html}Rome v1.0 RC1}}|Jul 16, 2007|
*----+--+
|{{{./ROME0.9Beta.html}Rome v0.9 Beta}}|Dec 11, 2006|
*----+--+
|{{{./ROME0.8Beta.html}Rome v0.8 Beta}}|Feb 01, 2006|
*----+--+
|{{{./ROME0.7Beta.html}Rome v0.7 Beta}}|Sep 09, 2005|
*----+--+
|{{{./ROME0.6Beta.html}Rome v0.6 Beta}}|Apr 01, 2005|
*----+--+
|{{{./ROME0.5Beta/index.html}Rome v0.5 Beta}}|Jan 10, 2005|
*----+--+
|{{{./ROME0.4Beta/index.html}Rome v0.4 Beta}}|Sep 27, 2004|
*----+--+
|{{{./ROME0.3Beta/index.html}Rome v0.3 Beta}}|Jul 28, 2004|
*----+--+
|{{{./ROME0.2Beta/index.html}Rome v0.2 Beta}}|Jun 16, 2004|
*----+--+
|{{{./ROME0.1Beta/index.html}Rome v0.1 Beta}}|Jun 08, 2004|
*----+--+

127
src/site/apt/RomeAPIFAQ.apt Normal file
View file

@ -0,0 +1,127 @@
-----
Rome API FAQ
-----
mkurz
-----
2011-08-14 14:37:43.201
-----
Rome API FAQ
As we were designing and implementing Rome we had discusssions, brainstorming and code reviews on the API. We've captured them in this document.
*Do SyndFeed support arbitrary Metadata?
Yes, using what we call Modules. Currently we support the 2 modules defined in RSS 1.0, {{{http://purl.org/rss/1.0/modules/dc/}Dublin Core}} and {{{http://purl.org/rss/1.0/modules/syndication/}Syndication}}. They are wired when converting from SyndFeed beans to RSS/Atom feeds beans and vice versa. We use the RSS 1.0 terminology of Modules because RSS 1.0 is the specification that defined and used extensibility the most. RSS 2.0 and Atom use XML namespaces to extend the feed.
However we will develop, and encourage developers to develop Rome specific Modules to handle future RSS 2.0 and Atom extensions.
If additional modules are defined to express metadata the converters should be modified to handle them. And the same goes for the parsers and generators or RSS/Atom feeds.
*Why those package, interfaces, classes and method names?
We've struggled (and still are struggling) with names. We renamed and moved things around until we got dizzy. If you have suggestions please let us know.
*Where are the parser, generator and converter implementations?
They are in hidden (not javadoc\-ed) packages within the Rome jar file. Their classes are loaded using declarations in a properties file. It is possible for developers to add or replace implementations of these components without modifying Rome source code, just by indicating an addition properties file to look for extra implementation classes.
*What are the interfaces and classes in the syndication.common package for? And why most bean (or interface) extend/implement them?
At first we got tired of modifying the toString() methods every time we were adding/removing a property. As we were strictly following the Bean patterns we wrote a toString() method that would traverse the properties and print them. Then we went recursively. Then we refactor that into an interface and provided an adapter.
Later we did the same to handle equals/hashcode, which is very useful when using Maps.
To complete the task we did the same for cloning, providing deep cloning support.
The ObjectBean is a base class that implements all these features. All Rome beans extend ObjectBean getting a toString, equals, hashcode and clone support for free.
*What are the property values when not set?
For Boolean is <<false>>. For numbers is 1. For String is null. For collections is an empty collection (even if you set it to null you get an empty collection). For all other objects is null.
*Are properties copied by value or by reference when set or gotten?
All properties as always handled by reference (except primitive types). If they are not immutable and you modify them you are affecting the bean/s that reference them too.
*What is with the interface and implementation names in the synd and module packages?
Interfaces have the following naming pattern: \<NAME\>I. Default implementations provided with Rome are named just \<NAME\>. For example, SyndFeedI is the interface and SyndFeed is the default implementation.
We decided to use \<NAME\> for the default implementation classes as we think they'll be the implementation of choice most of the time.
*Why the beans in the synd and module packages have interface and implementation versions of them?
We added interfaces only for the higher abstraction layer of Rome, SyndFeed (and Modules as they are used to express extensible metadata for SyndFeed instances). The reasoning behind such decoupling was to allow facading existing classes as SyndFeed beans. For example some persistent classes. This would allow to process them through components that work with SyndFeedI.
*Why the RSS and Atom beans don't have interface and implementation versions of it?
We thought about this, we dismissed the idea. The reasoning was that we expect to work with the SyndFeed and Module beans all the time and the convenience of using interface should be at that level only. We have RSS and Atom only because we have folks going and making up things without talking to each other. In short, we expect all our application processing to be done in a feed agnostic way in Java using SyndFeed and Module beans.
*How all the escaping for the description elements is handled for the different feed types as they keep changing their mind version after version?
Item description MIME type, depending on the RSS version is text/plain (0.91), text/html (0.92, 0.93, 2.0) or configurable (0.94). The thing is that when you get the value out of JDOM Element it's always XML unescaped. When putting data into a JDOM Element the data is XML escaped. This is not 100% correct but it will work in most of the cases.
Note that type in feed beans indicate what was the escaping type of the underlying feed, but if you get the value is already unescaped.
*How does Rome handle Atom content elements that support encoding (Base64, XML, plain) using the mode attribute?
The mode in feed in content indicates what was the encoding of the element in the feed, but when you get the value is already unencoded.
*What kind of input and output Rome supports?
Rome implementation currently uses JDOM for parsing and generating syndication feeds. As people tend to use the XML libraries they feel more comfortable with we have built in support for SAX, DOM, JDOM, byte streams, character streams and strings.
*What is the SyndFeedI.getSupportedFeedTypes() method for?
This method was originally a static method in the SyndFeed class. We've moved ot the SyndFeedI interface as we thought it would be useful to be able to ask a SyndFeedI instance the feed converters it handles.
*Are Rome beans Serializable? Why?
Yes, the default bean implementations of SyndFeedI provided with Rome are Serializable.
However, the \*I interfaces are not. We made that decision consciously and the reason behind it is closely related to the reason we introduced the \*I interfaces. You may want to extend some existing classes to implement SyndFeedI, and these classes you are extending may not be Serializable and cannot be (for example, they are tied to a live InputStream).
*Why all those packages?
TBD

100
src/site/apt/RomeV0.4FeedAndEntryURIMapping.apt Normal file
View file

@ -0,0 +1,100 @@
-----
Rome v0.4, Feed and Entry URI Mapping
-----
mkurz
-----
2011-08-15 06:41:03.135
-----
Rome v0.4, Feed and Entry URI Mapping
Rome Synd beans define the concept of URI at both feed and entry levels. The purpose of this URI is to help uniquely identifying feeds and entries when processed with Rome. This is particularly useful when a system is persisting feeds and when doing data manipulation where a primary key for the feeds or the entries is needed.
*The Problem
RSS 0.90, 0.91, 0.92, 0.93 and 1.0 do not define any special element for the purposes of identifying the feed or the items other than the items link element. The channel link element cannot be used to identify the feed as its semantics is to refer to the web site that has the information being published through the feed and, if web site offers more than one feed most likely both of them will have the same feed link value.
RSS 0.94 and RSS 2.0 define the guid element at item level. The guid element has an overloaded meaning. If the isPermalink attribute is true, the guid value can be used also as the URL for the item instead of the link element as well as a unique ID for the item. If the isPermalink attribute is false, the guid value can be used as a unique ID for the item. However, RSS 0.94 or RSS 2.0, do not define that the value of the guid element must be an URI.
Atom 0.3 defines an id element at feed and entry levels. The id element is defined as an URI. The Atom specification being currently designed requires the id element to contain a normalized URI as defined by RFC 2396bis.
The RSS0.94 and RSS 2.0 guid element and the Atom 0.3 id element are optional elements. Because of this, they may not be present at all in feeds.
*Rome's Solution
Because the concept of a URI it is not defined in all the feed formats, Rome makes an arbitrary design decision to provide the URI functionality regardless of the original (or target) feed type. The following behavior as been chosen based on expected and assumed usage pattern of feed and entry data.
*URI Normalization
If the uri property of a SyndFeed or SyndEntry bean is not NULL, the getter method must return a normalized URI following the rules defined in RFC2396bis.
**Converting from WireFeed (RSS or Atom) to SyndFeed
The common use case for this scenario is when consuming a feed. Because of that, for clarity purposes, when referring to the data in the WireFeed the following sections talks about elements (as in the XML feed) instead of talking of properties.
**SyndFeed
None of the RSS versions define an ID at channel level. In addition to this, Rome input classes (WireFeedInput and SyndFeedInput) do not have access to the URL (if any) used to fetch the feed. Because of this Rome does not set in the SyndFeed uri property , it is left to developer to set (if needed) a URI in the feed bean.
In the case of Atom 0.3, if the id element is present in the feed, the SyndFeed uri property will be set with the value of the id element. If it is not present, the developer must set (if needed) a URI manually.
***SyndEntry
For RSS 0.91, RSS 0.92, RSS 0.93 & RSS 1.0 if the link element is present in the item, the SyndEntry uri property will be set with the value of the link element. Otherwise the SyndEntry uri property is left as NULL and the developer must set it (if needed).
For RSS 0.94 & RSS 2.0 if the guid property is present in the item, the SyndEntry uri property will be set with the value of the guid element. If the guid element is not present, the SyndEntry uri property will be set with the value of the link element. If the link element is missing but the guid is present and it is flagged as a permalink, Rome will set set the SyndEntry link property with the value of the guid element (Rome is doing this because is a common practice to generated RSS 2.0 fees with guid elements marked as permalinks and without a link element).
For Atom 0.3 if the id element is present, the SyndEntry uri property is set with the value of the id element. If the id element is not present, the SyndEntry uri property is set with the value of the alternate link element.
**Converting from SyndFeed to WireFeed (RSS or Atom)
The common use case for this scenario is when generating a feed. Because of that, for clarity purposes, when referring to the data in the WireFeed the following sections talks about elements (as in the XML feed) instead of talking of properties.
***SyndFeed
For RSS 0.91, RSS 0.92, RSS 0.93, RSS 1.0 & RSS 2.0 the SyndFeed uri property is lost as there is not possible representation in the channel element for it.
For Atom 0.3 set the SyndFeed uri property is set as the value for the id element.
***SyndEntry
For RSS 0.91, RSS 0.92, RSS 0.93 & RSS 1.0 the SyndEntry uri property is lost as there is not possible representation in the item element for it.
For RSS 0.94 & RSS 2.0 the SyndEntry uri property is set as the value of the guid element with permalink set to false. If the SyndEntry uri property is not set, the SyndEntry link property is set as the value of the guid element with permalink set to true. Note that if the SyndFEntry linkproperty is missing the SyndEntry uri cannot be set as the value of the link element because it cannot be assumed that the uri property is an URL.
Because SyndEntry instances always return a normalized URI the value of the guid elements of a generated RSS 0.94 or RSS 2.0 may differ from the values of the guid elements of the original feed.
For Atom 0.3 the SyndEntry uri property is set as the id element.
Mosh...

43
src/site/apt/RssAndAtOMUtiliEsROMEV0.7DateAndTimeParsing.apt Normal file
View file

@ -0,0 +1,43 @@
-----
Rss and atOM utiliEs (ROME) v0.7 Date and Time Parsing
-----
mkurz
-----
2011-08-15 09:49:56.580
-----
Rss and atOM utiliEs (ROME) v0.7 Date and Time Parsing
Date and time elements seem to be error prone. RSS feeds use RFC822 datetime formats and Atom feeds use W3C datetime formats. Both RFC822 and W3C support quite a few flavors for specifying date and time. Some feeds use the wrong standard (such as some RSS feeds using W3C dates). Other feeds have an ENTER before or after the date. And another feeds use an arbitrary format altogether.
To help cope with this ROME makes a few tricks:
* It trims datetime elements before parsing them.
* It tries both RFC822 and W3C formats in all feeds.
* It uses custom format masks (if provided) when the previous steps fail.
[]
*Using Custom Format Masks
Custom format masks can be specified in the </rome.properties> file in any of the classpath elements.
The masks must be specified in the <datetime.extra.masks> property.
If more than one mask is to be specified they must be separated with '|' characters.
The syntax for the masks is the one use by by the <java.text.SimpleDateFormat> class. Always US Locale is assumed for the masks.
If datetime masks are specified in more than one </rome.properties> file in teh classpath, they are all aggregated.

97
src/site/apt/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.apt Normal file
View file

@ -0,0 +1,97 @@
-----
Feed and Entry URI Mapping, how SyndFeed and SyndEntry 'uri' properties map to RSS and Atom elements
-----
mkurz
-----
2011-08-15 09:05:43.877
-----
Feed and Entry URI Mapping, how SyndFeed and SyndEntry 'uri' properties map to RSS and Atom elements
Rss and atOM utilitiEs (ROME) Synd\* beans define the concept of URI at both feed and entry levels. The purpose of this URI is to help uniquely identifying feeds and entries when processed with ROME. This is particularly useful when a system is persisting feeds and when doing data manipulation where a primary key for the feeds or the entries is needed.
*The Problem
RSS 0.90, 0.91, 0.92, 0.93 and 1.0 do not define any special element for the purposes of identifying the feed or the items other than the items link element. The channel link element cannot be used to identify the feed as its semantics is to refer to the web site that has the information being published through the feed and, if web site offers more than one feed most likely both of them will have the same feed link value.
RSS 0.94 and RSS 2.0 define the guid element at item level. The guid element has an overloaded meaning. If the isPermalink attribute is true, the guid value can be used also as the URL for the item instead of the link element as well as a unique ID for the item. If the isPermalink attribute is false, the guid value can be used as a unique ID for the item. However, RSS 0.94 or RSS 2.0, do not define that the value of the guid element must be an URI.
Atom 0.3 defines an id element at feed and entry levels. The id element is defined as an URI. The Atom specification being currently designed requires the id element to contain a normalized URI as defined by RFC 2396bis.
The RSS0.94 and RSS 2.0 guid element and the Atom 0.3 id element are optional elements. Because of this, they may not be present at all in feeds.
*ROME's Solution
Because the concept of a URI it is not defined in all the feed formats, ROME makes an arbitrary design decision to provide the URI functionality regardless of the original (or target) feed type. The following behavior as been chosen based on expected and assumed usage pattern of feed and entry data.
*URI Normalization
If the uri property of a SyndFeed or SyndEntry bean is not NULL, the getter method must return a normalized URI following the rules defined in RFC2396bis.
**Converting from WireFeed (RSS or Atom) to SyndFeed
The common use case for this scenario is when consuming a feed. Because of that, for clarity purposes, when referring to the data in the WireFeed the following sections talks about elements (as in the XML feed) instead of talking of properties.
**SyndFeed
None of the RSS versions define an ID at channel level. In addition to this, ROME input classes (WireFeedInput and SyndFeedInput) do not have access to the URL (if any) used to fetch the feed. Because of this ROME does not set in the SyndFeed uri property , it is left to developer to set (if needed) a URI in the feed bean.
In the case of Atom 0.3, if the id element is present in the feed, the SyndFeed uri property will be set with the value of the id element. If it is not present, the developer must set (if needed) a URI manually.
***SyndEntry
For RSS 0.91, RSS 0.92, RSS 0.93 & RSS 1.0 if the link element is present in the item, the SyndEntry uri property will be set with the value of the link element. Otherwise the SyndEntry uri property is left as NULL and the developer must set it (if needed).
For RSS 0.94 & RSS 2.0 if the guid property is present in the item, the SyndEntry uri property will be set with the value of the guid element. If the guid element is not present, the SyndEntry uri property will be set with the value of the link element. If the link element is missing but the guid is present and it is flagged as a permalink, ROME will set set the SyndEntry link property with the value of the guid element (ROME is doing this because is a common practice to generated RSS 2.0 fees with guid elements marked as permalinks and without a link element).
For Atom 0.3 if the id element is present, the SyndEntry uri property is set with the value of the id element. If the id element is not present, the SyndEntry uri property is set with the value of the lternate link element.
**Converting from SyndFeed to WireFeed (RSS or Atom)
The common use case for this scenario is when generating a feed. Because of that, for clarity purposes, when referring to the data in the WireFeed the following sections talks about elements (as in the XML feed) instead of talking of properties.
***SyndFeed
For RSS 0.91, RSS 0.92, RSS 0.93, RSS 1.0 & RSS 2.0 the SyndFeed uri property is lost as there is not possible representation in the channel element for it.
For Atom 0.3 set the SyndFeed uri property is set as the value for the id element.
***SyndEntry
For RSS 0.91, RSS 0.92, RSS 0.93 & RSS 1.0 the SyndEntry uri property is lost as there is not possible representation in the item element for it.
For RSS 0.94 & RSS 2.0 the SyndEntry uri property is set as the value of the guid element with permalink set to false. If the SyndEntry uri property is not set, the SyndEntry link property is set as the value of the guid element with permalink set to true. Note that if the SyndFEntry linkproperty is missing the SyndEntry uri cannot be set as the value of the link element because it cannot be assumed that the uri property is an URL.
Because SyndEntry instances always return a normalized URI the value of the guid elements of a generated RSS 0.94 or RSS 2.0 may differ from the values of the guid elements of the original feed.
For Atom 0.3 the SyndEntry uri property is set as the id element.

88
src/site/apt/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.apt Normal file
View file

@ -0,0 +1,88 @@
-----
Feeds Date Elements Mapping to SyndFeed and SyndEntry
-----
mkurz
-----
2011-08-15 08:59:02.075
-----
Feeds Date Elements Mapping to SyndFeed and SyndEntry
The different RSS versions and Atom define different date elements at feed and entry level. Some of them also define syndication information indicating when (and when not) and how often to fetch feeds for updates. There is not always a possible mapping or conversion of this information when going from one format to another.
As this is still subject of debate ({{{http://www.tbray.org/ongoing/When/200x/2004/07/30/Dates}How About a Date}} and {{{http://www.intertwingly.net/wiki/pie/DateSurvey}Date Survey}}), for now, in Rss and atOM utilitiEs (ROME) we've taken a simplistic approach.
When handling feeds at WireFeed level, <<<rss.Channel>>> or <<<atom.Feed>>>, it is possible to access all the date elements and syndication information available in the feed.
When handling feeds at SyndFeed level, <<<synd.SyndFeed>>>, there is only one date element available, the <<<publishedDate>>>. Both, <<<SyndFeed>>> and <<<SyndEntry>>> have the <<<publisheDate>>> property. In addition, it is possible to use the Syndication Module.
The mapping of the date elements from the different feed formats to SyndFeed is as follows.
*For RSS 0.90
RSS 0.90 does not define date elements.
There is no mapping to <<<SyndFeed>>> and <<<SyndEntry>>> date properties.
*For RSS 0.91, 0.92
RSS 0.91 and 0.92 define <<<pubDate>>> and <<<lastBuildDate>>> at feed level.
The feed <<<pubDate>>> element is mapped to the <<<SyndFeed>>> <<<publishedDate>>> property. The <<<lastBuildDate>>> element is lost.
*For RSS 0.93, 0.94 and 2.0
RSS 0.93, 0.94 and 2.0 define <<<pubDate>>> and <<<lastBuildDate>>> at feed level. They also define <<<pubDate>>> and <<<expirationDate>>> at item level.
The feed <<<pubDate>>> element is mapped to the <<<SyndFeed>>> <<<publishedDate>>> property. The <<<lastBuildDate>>> element is lost.
The item <<<pubDate>>> element is mapped to the <<<SyndEntry>>> <<<publishedDate>>> property. The <<<expirationDate>>> element is lost.
*For RSS 1.0
RSS 1.0 use DC Module data at feed an item level to indicate date information about the feed and the items.
<<<SyndFeed>>> and <<<SyndEntry>>> use the DC Module <<<date>>> element for the <<<publishedDate>>> property.
*For Atom 0.3
Atom 0.3 defines a <<<modified>>> element at feed level and the <<<modified>>>, <<<created>>> & <<<issued>>> elements at entry level.
The feed <<<modified>>> element is mapped to the <<<SyndFeed>>> <<<publishedDate>>> property.
The item <<<modified>>> element is mapped to the <<<SyndEntry>>> <<<publishedDate>>> property. The entry elements, <<<created>>> and <<<issued>>>, are lost.
*For Atom 1.0
(Atom 1.0 supported in ROME since v0.8)
Atom 1.0 defines an <<<updated>>> element at the feed level, which ROME maps to <<<SyndFeed.publishedDate>>>.
Atom 1.0 defines <<<updated>>> and <<<published>>> elements at the entry level, which ROME maps to <<<SyndEntry.updatedDate>>> and <<<SyndEntry.publishedDate>>> respectively.

208
src/site/apt/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEPluginsMechanism.apt Normal file
View file

@ -0,0 +1,208 @@
-----
Rss and atOM utilitiEs (ROME) Plugins Mechanism
-----
mkurz
-----
2011-08-15 09:03:07.534
-----
Rss and atOM utilitiEs (ROME) Plugins Mechanism
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 definition files
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.sun.syndication.io.impl.PluginManager>>>. This class is an abstract class and it is extended to provide support for each type of plugin.
*Parser Plugins
Parser plugins are managed by the <<<com.sun.syndication.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.sun.syndication.io.impl.RSS090Parser \
com.sun.syndication.io.impl.RSS091NetscapeParser \
com.sun.syndication.io.impl.RSS091UserlandParser \
com.sun.syndication.io.impl.RSS092Parser \
com.sun.syndication.io.impl.RSS093Parser \
com.sun.syndication.io.impl.RSS094Parser \
com.sun.syndication.io.impl.RSS10Parser \
com.sun.syndication.io.impl.RSS20wNSParser \
com.sun.syndication.io.impl.RSS20Parser \
com.sun.syndication.io.impl.Atom03Parser
+------+
All the classes defined in this property have to implement the <<<com.sun.syndication.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
Generator plugins are managed by the <<<com.sun.syndication.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.sun.syndication.io.impl.RSS090Generator \
com.sun.syndication.io.impl.RSS091NetscapeGenerator \
com.sun.syndication.io.impl.RSS091UserlandGenerator \
com.sun.syndication.io.impl.RSS092Generator \
com.sun.syndication.io.impl.RSS093Generator \
com.sun.syndication.io.impl.RSS094Generator \
com.sun.syndication.io.impl.RSS10Generator \
com.sun.syndication.io.impl.RSS20Generator \
com.sun.syndication.io.impl.Atom03Generator
+------+
All the classes defined in this property have to implement the <<<com.sun.syndication.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
Converter plugins are managed by the <<<com.sun.syndication.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.sun.syndication.feed.synd.impl.ConverterForAtom03 \
com.sun.syndication.feed.synd.impl.ConverterForRSS090 \
com.sun.syndication.feed.synd.impl.ConverterForRSS091Netscape \
com.sun.syndication.feed.synd.impl.ConverterForRSS091Userland \
com.sun.syndication.feed.synd.impl.ConverterForRSS092 \
com.sun.syndication.feed.synd.impl.ConverterForRSS093 \
com.sun.syndication.feed.synd.impl.ConverterForRSS094 \
com.sun.syndication.feed.synd.impl.ConverterForRSS10 \
com.sun.syndication.feed.synd.impl.ConverterForRSS20
+------+
All the classes defined in this property have to implement the <<<com.sun.syndication.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.
*Module Plugins
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.sun.syndication.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.sun.syndication.io.impl.SyModuleParser \
com.sun.syndication.io.impl.DCModuleParser
# Parsers for Atom 0.3 entry modules
#
atom_0.3.item.ModuleParser.classes=com.sun.syndication.io.impl.DCModuleParser
# Parsers for RSS 1.0 feed modules
#
rss_1.0.feed.ModuleParser.classes=com.sun.syndication.io.impl.SyModuleParser \
com.sun.syndication.io.impl.DCModuleParser
# Parsers for RSS 1.0 item modules
#
rss_1.0.item.ModuleParser.classes=com.sun.syndication.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.sun.syndication.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.sun.syndication.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.sun.syndication.io.impl.SyModuleGenerator \
com.sun.syndication.io.impl.DCModuleGenerator
# Generators for Atom 0.3 entry modules
#
atom_0.3.item.ModuleGenerator.classes=com.sun.syndication.io.impl.DCModuleGenerator
# Generators for RSS 1.0 feed modules
#
rss_1.0.feed.ModuleGenerator.classes=com.sun.syndication.io.impl.SyModuleGenerator \
com.sun.syndication.io.impl.DCModuleGenerator
# Generators for RSS_1.0 entry modules
#
rss_1.0.item.ModuleGenerator.classes=com.sun.syndication.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.sun.syndication.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 {{{./RssAndAtOMUtilitiEsROMEV0.5TutorialDefiningACustomModuleBeanParserAndGenerator.html}tutorial for implementing a custom module}}.

87
src/site/apt/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5HowToBuildAndRunTheTutorialsSampleCode.apt Normal file
View file

@ -0,0 +1,87 @@
-----
Rss and atOM utilitiEs (ROME) v0.5, How to build and run the tutorials sample code
-----
mkurz
-----
2011-08-15 09:41:55.286
-----
Rss and atOM utilitiEs (ROME) v0.5, How to build and run the tutorials sample code
These instructions are outdated
*Building the samples with Maven
This is, as usual, the easiest way.
There's only one configuration step: Maven downloads dependencies from an online repository (by default ibiblio), to a local repository (on UNIX usually in \~/.maven/repository). Because the rome distribution is not yet on ibiblio, you need to add it yourself, either to your local repository, or to your own intranet maven repository if you have such a thing in your organization.
If you built ROME run maven jar:install in the rome project to install ROME's jar in your Maven repository.
If you got ROME binary distribution copy the ROME's jar file to your Maven repository (on UNIX that would be <<<cp rome\-0.5/rome\-0.5.jar \~/.maven/repository/rome/jars/>>>).
Then building the samples it's easy as a pie, just run maven jar in the samples sub\-project and you are all set.
To build the sample Web Application, just run maven war in the samples sub\-project. The WAR file, <<<rome\-samples.war>>>, will be created under the <<<target>>> directory.
*Building the samples with Ant
The targets present in the build.xml are very helpful, ant get\-deps will download from ibiblio to rome\-samples/target/lib all the jar files ROME depends on and are needed for building an application using Rome.
In order to build the samples (or any subprojects), you'll need to first ensure that rome itself is built. You can do this simply by running ant in the project root directory.
Once this is done, change to the samples directory, and just run ant. This will produce two files, rome\-samples.jar which contains the sample applications, and rome\-samples.war which will contain a deployable web application war file for the FeedServlet sample.
*Running the samples with Maven
The Maven goals for running the samples are defined in maven.xml.
* <<<maven run\-agr>>> runs the FeedAggregator sample
* <<<maven run\-conv>>> runs the FeedConverter sample
* <<<maven run\-read>>> runs the FeedReader sample
* <<<maven run\-write>>> runs the FeedWriter sample
* <<<maven run\-sampleModule>>> runs the FeedConverter sample against a file with Sample Module data (shows off custom module plugin)
[]
To run the sample Web Application you'll need to deploy the WAR file into your servlet container. If you are using Tomcat 4 or Tomcat 5 and the WAR file was dropped in the <<<$\{TOMCAT\}/webapps>>> directory the URL for the <<<FeedServlet>>> would be {{{http://localhost:8080/rome\-samples/feed}http://localhost:8080/rome\-samples/feed}} in a default localhost Tomcat installation.
*Running the samples with Ant
All ant targets for the samples generate the same file named toto: feel free to customize this build.xml to your own needs. Also today all these targets depends on the jar target, which represents some overhead if you have already built. Get rid of that once your project is well setup.
* <<<ant run\-aggr>>> runs the FeedAggregator sample
* <<<ant run\-conv>>> runs the FeedConverter sample
* <<<ant run\-read>>> runs the FeedReader sample
* <<<ant run\-write>>> runs the FeedWriter sample
* <<<ant run\-sampleModule>>> runs the FeedConverter sample against a file with Sample Module data (shows off custom module plugin)
[]

369
src/site/apt/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialDefiningACustomModuleBeanParserAndGenerator.apt Normal file
View file

@ -0,0 +1,369 @@
-----
Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Defining a Custom Module (bean, parser and generator)
-----
mkurz
-----
2011-08-15 09:29:19.297
-----
Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Defining a Custom Module (bean, parser and generator)
<<Software requirements:>> Synd J2SE 1.4\+, JDOM 1.0 and ROME 0.5.
This tutorial walks through the steps of creating a custom module for syndication feeds that support additional namespaces (such as RSS 1.0, RSS 2.0 and Atom 0.3).
To understand this tutorial you should be familiar the with ROME API and with the use of modules in syndication feeds.
Out of the box ROME parsers and generators support plug\-ability of modules for RSS 1.0, RSS 2.0 and Atom 0.3 at both feed and item/entry levels. Also support for the Dublin Core and Syndication modules is provided.
The complete source for this tutorial is in the ROME samples bundle as well as in CVS.
*What is the intended outcome of the tutorial?
The goal is to add support for a hypothetical Sample Module by defining a module bean, module parser and module generator and the necessary configuration to wire the parser and generator to an RSS 1.0 parser and RSS 1.0 generator.
The sample module defines 3 elements, 'bar', 'foo' and 'date', where 'bar' and 'date' may occur at most once and the 'foo' element may occur several times. For example, a feed with the Sample Module data would look like:
+------+
<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns="http://purl.org/rss/1.0/"
xmlns:sample="http://rome.dev.java.net/module/sample/1.0">
<channel>
<title>RSS 1.0 Feed with Sample Module</title>
<link>http://rome.dev.java.net</link>
<description>This is a feed showing how to use a custom module with ROME</description>
<items>
<rdf:Seq>
<rdf:li resource="item01" />
<rdf:li resource="item02" />
</rdf:Seq>
</items>
<sample:bar>Channel bar</sample:bar>
<sample:foo>Channel first foo</sample:foo>
<sample:foo>Channel second foo</sample:foo>
</channel>
<item rdf:about="item01">
<title>Title of Item 01</title>
<link>http://rome.dev.java.net/item01</link>
<description>Item 01 does not have Sample module data</description>
</item>
<item rdf:about="item02">
<title>Title of Item 02</title>
<link>http://rome.dev.java.net/item02</link>
<description>Item 02 has Sample module data</description>
<sample:bar>Item 02 bar</sample:bar>
<sample:foo>Item 02 only foo</sample:foo>
<sample:date>2004-07-27T00:00+00:00</sample:date>
</item>
</rdf:RDF>
+------+
*Sample Module Bean
First we must start with the bean interface, SampleModule. SampleModule must extend Module. The Module interface defines the getUri() method, which will return a URI identifying the module.
The Module interface also extends the CopyFrom interface to enable copying properties from alternate implementations of the concrete Module interface. More on this later in this page.
The SampleModule's URI is defined as a constant, accessible via the getURI() instance method. This is for convenience and good practice only.
Then the module defines 3 properties: bar (String), foos (List) and date (Date). The elements of the foos property list must be strings (wishing for Java 5 generics already?).
+------+
public interface SampleModule extends Module {
public static final String URI = "http://rome.dev.java.net/module/sample/1.0";
public String getBar();
public void setBar(String bar);
public List getFoos();
public void setFoos(List foos);
public Date getDate();
public void setDate(Date date);
}
+------+
Next we have to write the bean implementation, SampleModuleImpl.
SampleModuleImpl extends ModuleImpl. ModuleImpl is the default implementation of the \=\=Module interface. ModuleImpl automatically provides equals, hashCode, toString and clone support for the properties of the class given in the constructor (SampleModule). Also the URI of the Sample module is indicated; it will be used by the Module.getUri() method.
+------+
public class SampleModuleImpl extends ModuleImpl implements SampleModule {
...
public SampleModuleImpl() {
super(SampleModule.class,SampleModule.URI);
}
public String getBar() {
return _bar;
}
[...]
+------+
The module properties are just Java Bean properties. The only catch is to follow ROME semantics for Collection properties: in the case of a null value for the collection, an empty collection must be returned. Also, following ROME semantics, all properties are by reference, including mutable ones.
+------+
public class SampleModuleImpl extends ModuleImpl implements SampleModule {
private String _bar;
private List _foos;
private Date _date;
...
public void setBar(String bar) {
_bar = bar;
}
public List getFoos() {
return (_foos==null) ? (_foos=new ArrayList()) : _foos;
}
public void setFoos(List foos) {
_foos = foos;
}
public Date getDate() {
return _date;
}
public void setDate(Date date) {
_date = date;
}
+------+
*The CopyFrom interface
Now the weird part, the bits for the CopyFrom logic. The {{{./TheCopyFromInterface.html}The CopyFrom interface (rome)}} document fully explains the CopyFrom logic in detail. In short, the CopyFrom interface is to support copying properties from one implementation of a bean (defined through an interface) to another implementation of the same bean.
The getInterface() method returns the bean interface of the implementation (this is necessary for collections containing sub\-classes such as a list of modules).
The copyFrom() method copies all the properties from the parameter object (which must be a SampleModule implementation) into the caller bean properties. Note that the copyFrom must do a deep copy.
+------+
public class SampleModuleImpl extends ModuleImpl implements SampleModule {
...
public Class getInterface() {
return SampleModule.class;
}
public void copyFrom(Object obj) {
SampleModule sm = (SampleModule) obj;
setBar(sm.getBar());
List foos = new ArrayList(sm.getFoos()); // this is enough for the copy because the list elements are inmutable (Strings)
setFoos(foos);
setDate((Date)sm.getDate().clone()); // because Date is not inmutable.
}
}
+------+
*Sample Module Parser
The sample module parser must implement the ModuleParser interface. This interface defines 2 methods, getNamespaceUri() that returns the URI of the module and parse(Element) which extracts the module elements from the given Element.
The feed parsers will invoke the module parser with a feed element or with an item element. The module parser must look for module elements in the children of the given element. That is was the Sample parser is doing when looking for 'bar', 'foo' and 'date' children elements in the received element.
In the case of the 'foo' element it looks for all occurrences as the Sample module schema allows for more than one occurrence of the 'foo' element. A SampleModule bean is created and the found values are set into it. For the 'date' element it assumes its a date value in W3C datetime format.
If no Sample Module elements are found in the feed, the parse(Element) method returns null. This is to avoid having an empty instance of a module \-not present in the feed\- in the feed bean or in the item bean.
+------+
public class SampleModuleParser implements ModuleParser {
private static final Namespace SAMPLE_NS = Namespace.getNamespace("sample", SampleModule.URI);
public String getNamespaceUri() {
return SampleModule.URI;
}
public Module parse(Element dcRoot) {
boolean foundSomething = false;
SampleModule fm = new SampleModuleImpl();
Element e = dcRoot.getChild("bar", SAMPLE_NS);
if (e != null) {
foundSomething = true;
fm.setBar(e.getText());
}
List eList = dcRoot.getChildren("foo", SAMPLE_NS);
if (eList.size() > 0) {
foundSomething = true;
fm.setFoos(parseFoos(eList));
}
e = dcRoot.getChild("date", SAMPLE_NS);
if (e != null) {
foundSomething = true;
fm.setDate(DateParser.parseW3CDateTime(e.getText()));
}
return (foundSomething) ? fm : null;
}
private List parseFoos(List eList) {
List foos = new ArrayList();
for (int i = 0; i < eList.size(); i++) {
Element e = (Element) eList.get(i);
foos.add(e.getText());
}
return foos;
}
}
+------+
*Sample Module Generator
The sample module generator must implement the ModuleGenerator interface. This interface defines 2 methods, getNamespaceUri() that returns the URI of the module and generate(ModuleI,Element) which injects the module data into the given Element.
The feed generator will invoke the module generator with a feed element or with an item element. The module generator must inject the module properties into the given element (which is a feed or an item). This injection has to be done using the right namespace. The set of namespaces returned by the getNamespaces() method will be used to declare the namespaces used by the module in the feed root element.
If no Sample Module bean is in the feed bean the module generator is not invoked at all.
+------+
public class SampleModuleGenerator implements ModuleGenerator {
private static final Namespace SAMPLE_NS = Namespace.getNamespace("sample", SampleModule.URI);
public String getNamespaceUri() {
return SampleModule.URI;
}
private static final Set NAMESPACES;
static {
Set nss = new HashSet();
nss.add(SAMPLE_NS);
NAMESPACES = Collections.unmodifiableSet(nss);
}
public Set getNamespaces() {
return NAMESPACES;
}
public void generate(Module module, Element element) {
// this is not necessary, it is done to avoid the namespace definition in every item.
Element root = element;
while (root.getParent()!=null && root.getParent() instanceof Element) {
root = (Element) element.getParent();
}
root.addNamespaceDeclaration(SAMPLE_NS);
SampleModuleI fm = (SampleModule)module;
if (fm.getBar() != null) {
element.addContent(generateSimpleElement("bar", fm.getBar()));
}
List foos = fm.getFoos();
for (int i = 0; i < foos.size(); i++) {
element.addContent(generateSimpleElement("foo",foos.get(i).toString()));
}
if (fm.getDate() != null) {
element.addContent(generateSimpleElement("date", DateParser.formatW3CDateTime(fm.getDate())));
}
}
protected Element generateSimpleElement(String name, String value) {
Element element = new Element(name, SAMPLE_NS);
element.addContent(value);
return element;
}
}
+------+
*Configuration to make ROME process Sample Module in feeds
The last step is to setup the configuration file to indicate to ROME how and when to use the Sample Module parser and generator.
The configuration is stored in a Properties file, 'rome.properties', that has to be in the root of the classpath or JAR where the Sample Module bean, parser and generator classes are.
You must indicate the syndication feed formats (ie RSS 1.0) that must be aware of the Sample Module. You must indicate if the Sample Module is available for feed or item elements, or for both. You must indicate both the parser and the generator classes.
Following is the 'rome.properties' file for the Sample Module, it's defined for RSS 1.0 only, for both feed and item elements.
+------+
# Parsers for RSS 1.0 feed modules
#
rss_1.0.feed.ModuleParser.classes=com.sun.syndication.samples.module.SampleModuleParser
# Parsers for RSS 1.0 item modules
#
rss_1.0.item.ModuleParser.classes=com.sun.syndication.samples.module.SampleModuleParser
# Generators for RSS 1.0 feed modules
#
rss_1.0.feed.ModuleGenerator.classes=com.sun.syndication.samples.module.SampleModuleGenerator
# Generators for RSS_1.0 entry modules
#
rss_1.0.item.ModuleGenerator.classes=com.sun.syndication.samples.module.SampleModuleGenerator
+------+
If you are defining more than one module, indicate the parser and generator implementation classes separated by commas or spaces.
*Using the Sample Module from the SyndFeed beans
They will be there, just use them. You may get the SampleModule bean using the getModule(String Uri) method of the SyndFeed bean and the SyndEntry bean.
Adding or replacing a syndication feed parser, generator or converter goes along the same lines of what it has been explained in the tutorial for modules. This is explained in the {{{./RssAndAtOMUtilitiEsROMEPluginsMechanism.html}ROME Plugins Mechanism}} topic.

146
src/site/apt/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToAggregateManySyndicationFeedsIntoASingleOne.apt Normal file
View file

@ -0,0 +1,146 @@
-----
Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to aggregate many syndication feeds into a single one
-----
mkurz
-----
2011-08-15 09:12:26.866
-----
Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to aggregate many syndication feeds into a single one
<<Software requirements:>> J2SE 1.4\+, JDOM 1.0 and ROME 0.5.
ROME represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeed interface. The SyndFeed interfaces and its properties follow the Java Bean patterns. The default implementations provided with ROME are all lightweight classes.
ROME includes parsers to process syndication feeds into SyndFeed instances. The SyndFeedInput class handles the parsers using the correct one based on the syndication feed being processed. The developer does not need to worry about selecting the right parser for a syndication feed, the SyndFeedInput will take care of it by peeking at the syndication feed structure. All it takes to read a syndication feed using ROME are the following 2 lines of code:
+------+
SyndFeedInput input = new SyndFeedInput();
SyndFeed feed = input.build(new XmlReader(feedUrl));
+------+
The first line creates a SyndFeedInput instance that will work with any syndication feed type (RSS and Atom versions). The second line instructs the SyndFeedInput to read the syndication feed from the InputStream of a URL pointing to the feed. The XmlReader is a character based Reader that resolves the encoding following the HTTP MIME types and XML rules for it. The SyndFeedInput.build() method returns a SyndFeed instance that can be easily processed.
ROME also includes generators to create syndication feeds out of SyndFeed instances. The SyndFeedOutput class does this generation. The SyndFeedOutput will generate a syndication feed of the feed type indicated by the SyndFeed object being output. The following two lines of code show how to create a syndication feed output from a SyndFeed instance:
+------+
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,new PrintWriter(System.out));
+------+
The first line creates a SyndFeedOutput instance that will produce syndication feeds. It can output feeds of any type (rss_0.9, rss_0.91, rss_0.92, rss_0.93, rss_0.94, rss_1.0, rss_2.0 & atom_0.3), the SyndFeed feedType property indicates the type. The second line writes the SyndFeed as a syndication feed into the application's output.
SyndFeed instances can also be created and populated within the code. For example:
+------+
SyndFeed aggrFeed = new SyndFeedImpl();
aggrFeed.setFeedType("rss_1.0");
aggrFeed.setTitle("Aggregated Feed");
aggrFeed.setDescription("Anonymous Aggregated Feed");
aggrFeed.setAuthor("anonymous");
aggrFeed.setLink("http://www.anonymous.com");
+------+
The snipped of code above creates a SyndFeed instance using the default implementation provided by ROME, sets the feed type to RSS 1.0, sets the title, description, author and link properties of the feed.
SyndFeed properties can be modified, assigned to other SyndFeed instances, removed, etc. It's important to remember that the getters/setters semantics defined for all SyndFeed properties (and properties of its properties) is a copy by reference, not by value. In other words if you alter the property of a SyndFeed property you are altering the SyndFeed. Or, another example, if you assign the list of entries of one SyndFeed instance to another SyndFeed isntance and then you modify the list or any of the entries in the list, you are modifying the entries of both SyndFeed instances.
The following lines of code show how to copy the entries of a SyndFeed instance being read (inFeed) into a SyndFeed instance being created within the application (feed):
+------+
package com.sun.syndication.samples;
import java.net.URL;
import java.io.InputStreamReader;
import java.io.PrintWriter;
import java.util.List;
import java.util.ArrayList;
import com.sun.syndication.feed.synd.SyndFeed;
import com.sun.syndication.feed.synd.SyndFeedImpl;
import com.sun.syndication.io.SyndFeedOutput;
import com.sun.syndication.io.SyndFeedInput;
import com.sun.syndication.io.XmlReader;
/**
* It aggregates a list of RSS/Atom feeds (they can be of different types)
* into a single feed of the specified type.
* <p>
* @author Alejandro Abdelnur
*
*/
public class FeedAggregator {
public static void main(String[] args) {
boolean ok = false;
if (args.length>=2) {
try {
String outputType = args[0];
SyndFeed feed = new SyndFeedImpl();
feed.setFeedType(outputType);
feed.setTitle("Aggregated Feed");
feed.setDescription("Anonymous Aggregated Feed");
feed.setAuthor("anonymous");
feed.setLink("http://www.anonymous.com");
List entries = new ArrayList();
feed.setEntries(entries);
for (int i=1;i<args.length;i++) {
URL inputUrl = new URL(args[i]);
SyndFeedInput input = new SyndFeedInput();
SyndFeed inFeed = input.build(new XmlReader(inputUrl));
entries.addAll(inFeed.getEntries());
}
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,new PrintWriter(System.out));
ok = true;
}
catch (Exception ex) {
System.out.println("ERROR: "+ex.getMessage());
}
}
if (!ok) {
System.out.println();
System.out.println("FeedAggregator aggregates different feeds into a single one.");
System.out.println("The first parameter must be the feed type for the aggregated feed.");
System.out.println(" [valid values are: rss_0.9, rss_0.91U, rss_0.91N, rss_0.92, rss_0.93, ]");
System.out.println(" [ rss_0.94, rss_1.0, rss_2.0 & atom_0.3 ]");
System.out.println("The second to last parameters are the URLs of feeds to aggregate.");
System.out.println();
}
}
}
+------+

105
src/site/apt/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToConvertASyndicationFeedFromOneTypeToAnother.apt Normal file
View file

@ -0,0 +1,105 @@
-----
Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to convert a syndication feed from one type to another
-----
mkurz
-----
2011-08-15 09:10:23.793
-----
Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to convert a syndication feed from one type to another
<<Software requirements:>> Synd J2SE 1.4\+, JDOM 1.0 and ROME 0.5.
ROME represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeed interface. The SyndFeed interfaces and its properties follow the Java Bean patterns. The default implementations provided with ROME are all lightweight classes.
ROME includes parsers to process syndication feeds into SyndFeed instances. The SyndFeedInput class handles the parsers using the correct one based on the syndication feed being processed. The developer does not need to worry about selecting the right parser for a syndication feed, the SyndFeedInput will take care of it by peeking at the syndication feed structure. All it takes to read a syndication feed using ROME are the following 2 lines of code:
+------+
SyndFeedInput input = new SyndFeedInput();
SyndFeed feed = input.build(new XmlReader(feedUrl));
+------+
The first line creates a SyndFeedInput instance that will work with any syndication feed type (RSS and Atom versions). The second line instructs the SyndFeedInput to read the syndication feed from the InputStream of a URL pointing to the feed. The XmlReader is a character based Reader that resolves the encoding following the HTTP MIME types and XML rules for it. The SyndFeedInput.build() method returns a SyndFeed instance that can be easily processed.
ROME also includes generators to create syndication feeds out of SyndFeed instances. The SyndFeedOutput class does this generation. The SyndFeedOutput will generate a syndication feed of the feed type indicated by the SyndFeed object being output. The following two lines of code show how to create a syndication feed output from a SyndFeed instance:
+------+
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,new PrintWriter(System.out));
+------+
The first line creates a SyndFeedOutput instance that will produce syndication feeds. It can output feeds of any type (rss_0.9, rss_0.91, rss_0.92, rss_0.93, rss_0.94, rss_1.0, rss_2.0 & atom_0.3), the SyndFeed feedType property indicates the type. The second line writes the SyndFeed as a syndication feed into the application's output.
Following is the full code for a Java application that reads a syndication feed and converts it to other syndication feed type, writing the converted feed to the application's output.
+------+
package com.sun.syndication.samples;
import java.net.URL;
import java.io.InputStreamReader;
import java.io.PrintWriter;
import com.sun.syndication.feed.synd.SyndFeed;
import com.sun.syndication.io.SyndFeedInput;
import com.sun.syndication.io.SyndFeedOutput;
import com.sun.syndication.io.XmlReader;
/**
* It Converts any RSS/Atom feed type to a an RSS/Atom feed of the
* specified type.
* <p>
* @author Alejandro Abdelnur
*
*/
public class FeedConverter {
public static void main(String[] args) {
boolean ok = false;
if (args.length==2) {
try {
String outputType = args[0];
URL feedUrl = new URL(args[1]);
SyndFeedInput input = new SyndFeedInput();
SyndFeed feed = input.build(new XmlReader(feedUrl));
feed.setFeedType(outputType);
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,new PrintWriter(System.out));
ok = true;
}
catch (Exception ex) {
System.out.println("ERROR: "+ex.getMessage());
}
}
if (!ok) {
System.out.println();
System.out.println("FeedConverter converts between syndication feeds types.");
System.out.println("The first parameter must be the feed type to convert to.");
System.out.println(" [valid values are: rss_0.9, rss_0.91, rss_0.92, rss_0.93, ]");
System.out.println(" [ rss_0.94, rss_1.0, rss_2.0 & atom_0.3 ]");
System.out.println("The second parameter must be the URL of the feed to convert.");
System.out.println();
}
}
}
+------+

204
src/site/apt/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToCreateAndWriteASyndicationFeed.apt Normal file
View file

@ -0,0 +1,204 @@
-----
Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to create and write a syndication feed
-----
mkurz
-----
2011-08-15 09:20:35.352
-----
Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to create and write a syndication feed
<<Software requirements:>> J2SE 1.4\+, JDOM 1.0 and ROME 0.5.
ROME represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeed interface. The SyndFeed interfaces and its properties follow the Java Bean patterns. The default implementations provided with ROME are all lightweight classes.
Creating a feed with SyndFeed beans consists of creating beans and setting their properties. The following code fragments show how a SyndFeed bean with 3 entries is created.
First the SyndFeed instance is created, the preferred syndication format is set and the feed header info (title, link, description) is also set.
+------+
SyndFeed feed = new SyndFeedImpl();
feed.setFeedType(feedType);
feed.setTitle("Sample Feed (created with ROME)");
feed.setLink("http://rome.dev.java.net");
feed.setDescription("This feed has been created using ROME (Java syndication utilities");
+------+
Then a list for entries is created, entries are created and added to the list. Each entry is set with a title, link, published date and a description. The description for the first entry is plain test, for the third entry is HTML. After each entry is created is added to the list.
+------+
List entries = new ArrayList();
SyndEntry entry;
SyndContent description;
entry = new SyndEntryImpl();
entry.setTitle("ROME v1.0");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome01");
entry.setPublishedDate(DATE_PARSER.parse("2004-06-08"));
description = new SyndContentImpl();
description.setType("text/plain");
description.setValue("Initial release of ROME");
entry.setDescription(description);
entries.add(entry);
[...]
entry = new SyndEntryImpl();
entry.setTitle("ROME v3.0");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome03");
entry.setPublishedDate(DATE_PARSER.parse("2004-07-27"));
description = new SyndContentImpl();
description.setType("text/html");
description.setValue("<p>More Bug fixes, mor API changes, some new features and some Unit testing</p>"+
"<p>For details check the <a href=\"https://rometools.jira.com/wiki/display/ROME/Change+Log#ChangeLog-Changesmadefromv0.3tov0.4\">Changes Log</a></p>");
entry.setDescription(description);
entries.add(entry);
+------+
Finally the list with entries is added to the SyndFeed bean.
+------+
feed.setEntries(entries);
+------+
The SyndFeed bean is now ready to be written out to a syndication feed XML document. Note that any of supported syndication formats can be set in the feedType property.
ROME includes generators that allow producing syndication feed XML documents from SyndFeed instances. The SyndFeedOutput class handles the generation of the syndication feed XML documents on any of the supported feed formats (RSS and Atom). The developer does not need to worry about selecting the right generator for a syndication feed, the SyndFeedOutput will take care of it by looking at the information in the SyndFeed bean. All it takes to write a syndication feed XML document using ROME \-assuming you have a SyndFeed bean and a Writer instance\- are the following lines of code:
+------+
SyndFeed feed = ...;
Writer writer = ...;
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,writer);
+------+
First a SyndFeedOutput instance is created, this instance will work with any syndication feed type (RSS and Atom versions). Then the feed and the writer are given to the SyndFeedOutput instance, the SyndFeedOutput will write the syndication feed XML document represented by the SyndFeed bean to the Writer stream.
Following is the full code for a Java application that creates a syndication feed and writes it to a file in the specified syndication format.
+------+
package com.sun.syndication.samples;
import com.sun.syndication.feed.synd.*;
import com.sun.syndication.io.SyndFeedOutput;
import java.io.FileWriter;
import java.io.Writer;
import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.List;
/**
* It creates a feed and writes it to a file.
* <p>
*
*/
public class FeedWriter {
private static final DateFormat DATE_PARSER = new SimpleDateFormat("yyyy-MM-dd");
public static void main(String[] args) {
boolean ok = false;
if (args.length==2) {
try {
String feedType = args[0];
String fileName = args[1];
SyndFeed feed = new SyndFeedImpl();
feed.setFeedType(feedType);
feed.setTitle("Sample Feed (created with ROME)");
feed.setLink("http://rome.dev.java.net");
feed.setDescription("This feed has been created using ROME (Java syndication utilities");
List entries = new ArrayList();
SyndEntry entry;
SyndContent description;
entry = new SyndEntryImpl();
entry.setTitle("ROME v1.0");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome01");
entry.setPublishedDate(DATE_PARSER.parse("2004-06-08"));
description = new SyndContentImpl();
description.setType("text/plain");
description.setValue("Initial release of ROME");
entry.setDescription(description);
entries.add(entry);
entry = new SyndEntryImpl();
entry.setTitle("ROME v2.0");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome02");
entry.setPublishedDate(DATE_PARSER.parse("2004-06-16"));
description = new SyndContentImpl();
description.setType("text/plain");
description.setValue("Bug fixes, minor API changes and some new features");
entry.setDescription(description);
entries.add(entry);
entry = new SyndEntryImpl();
entry.setTitle("ROME v3.0");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome03");
entry.setPublishedDate(DATE_PARSER.parse("2004-07-27"));
description = new SyndContentImpl();
description.setType("text/html");
description.setValue("<p>More Bug fixes, mor API changes, some new features and some Unit testing</p>"+
"<p>For details check the <a href=\"https://rometools.jira.com/wiki/display/ROME/Change+Log#ChangeLog-Changesmadefromv0.3tov0.4\">Changes Log</a></p>");
entry.setDescription(description);
entries.add(entry);
feed.setEntries(entries);
Writer writer = new FileWriter(fileName);
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,writer);
writer.close();
System.out.println("The feed has been written to the file ["+fileName+"]");
ok = true;
}
catch (Exception ex) {
ex.printStackTrace();
System.out.println("ERROR: "+ex.getMessage());
}
}
if (!ok) {
System.out.println();
System.out.println("FeedWriter creates a RSS/Atom feed and writes it to a file.");
System.out.println("The first parameter must be the syndication format for the feed");
System.out.println(" (rss_0.90, rss_0.91, rss_0.92, rss_0.93, rss_0.94, rss_1.0 rss_2.0 or atom_0.3)");
System.out.println("The second parameter must be the file name for the feed");
System.out.println();
}
}
}
+------+

93
src/site/apt/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToReadASyndicationFeed.apt Normal file
View file

@ -0,0 +1,93 @@
-----
Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to read a syndication feed
-----
mkurz
-----
2011-08-15 09:08:56.262
-----
Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to read a syndication feed
<<Software requirements:>> J2SE 1.4\+, JDOM 1.0 and ROME 0.5.
ROME represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeed interface. The SyndFeed interfaces and its properties follow the Java Bean patterns. The default implementations provided with ROME are all lightweight classes.
ROME includes parsers to process syndication feeds into SyndFeed instances. The SyndFeedInput class handles the parsers using the correct one based on the syndication feed being processed. The developer does not need to worry about selecting the right parser for a syndication feed, the SyndFeedInput will take care of it by peeking at the syndication feed structure. All it takes to read a syndication feed using ROME are the following 2 lines of code:
+------+
SyndFeedInput input = new SyndFeedInput();
SyndFeed feed = input.build(new XmlReader(feedUrl));
+------+
The first line creates a SyndFeedInput instance that will work with any syndication feed type (RSS and Atom versions). The second line instructs the SyndFeedInput to read the syndication feed from the char based input stream of a URL pointing to the feed. The XmlReader is a character based Reader that resolves the encoding following the HTTP MIME types and XML rules for it. The SyndFeedInput.build() method returns a SyndFeed instance that can be easily processed.
The default SyndFeed implementation has a detailed and clear toString() implementation. The following line just prints it to the application's output.
+------+
System.out.println(feed);
+------+
Following is the full code for a Java application that reads a syndication feed and prints the SyndFeed bean to the application's output.
+------+
package com.sun.syndication.samples;
import java.net.URL;
import java.io.InputStreamReader;
import com.sun.syndication.feed.synd.SyndFeed;
import com.sun.syndication.io.SyndFeedInput;
import com.sun.syndication.io.XmlReader;
/**
* It Reads and prints any RSS/Atom feed type.
* <p>
* @author Alejandro Abdelnur
*
*/
public class FeedReader {
public static void main(String[] args) {
boolean ok = false;
if (args.length==1) {
try {
URL feedUrl = new URL(args[0]);
SyndFeedInput input = new SyndFeedInput();
SyndFeed feed = input.build(new XmlReader(feedUrl));
System.out.println(feed);
ok = true;
}
catch (Exception ex) {
ex.printStackTrace();
System.out.println("ERROR: "+ex.getMessage());
}
}
if (!ok) {
System.out.println();
System.out.println("FeedReader reads and prints any RSS/Atom feed type.");
System.out.println("The first parameter must be the URL of the feed to read.");
System.out.println();
}
}
}
+------+

242
src/site/apt/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEWithinAServletToCreateAndReturnAFeed.apt Normal file
View file

@ -0,0 +1,242 @@
-----
Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME within a Servlet to create and return a feed
-----
mkurz
-----
2011-08-15 09:34:50.713
-----
Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME within a Servlet to create and return a feed
<<Software requirements:>> J2SE 1.4\+, Servlet Container 2.3\+, JDOM 1.0 and ROME 0.5.
This sample consists of a servlet that serves a feed as response. The feed type (RSS in any of its variants or Atom) can be specified as a URL parameter when requesting the feed. The returned feed is hardwired in the sample and it would be straight forward to modify the sample to generate the feed dynamically (i.e. from data stored in a database).
The core logic of the <<<FeedServlet>>> is in the following fragment of code:
+------+
public class FeedServlet extends HttpServlet {
...
public void doGet(HttpServletRequest req,HttpServletResponse res) throws IOException {
...
SyndFeed feed = getFeed(req);
String feedType = req.getParameter(FEED_TYPE);
feedType = (feedType!=null) ? feedType : _defaultFeedType;
feed.setFeedType(feedType);
res.setContentType(MIME_TYPE);
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,res.getWriter());
...
}
protected SyndFeed getFeed(HttpServletRequest req) throws IOException,FeedException {
SyndFeed feed = new SyndFeedImpl();
feed = ...
return feed;
}
}
+------+
The servlet returns a feed upon HTTP GET requests with the <<<doGet()>>> method.
First the <<<SyndFeed>>> bean is obtained by invoking the <<<getFeed()>>> method, the request object is passed as it could be used to obtain request contextual information to create the feed. How to create a feed using SyndFeed bean is explained in detail in the {{{./RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToCreateAndWriteASyndicationFeed.html}Using ROME to create and write a feed}} Tutorial.
Then the feed type of the response is determined, first looking at the request parameters and falling back to a default feed type (specified by a servlet init parameter) if the type is not indicated in the request parameters. Setting the feed type in the feed bean will indicate the <<<SyndFeedOutput>>> the feed type to output.
Finally, the response is set with the proper content type (the MIME_TYPE constant is 'application/xml; charset\=UTF\-8') and the feed is written to response writer using the <<<SyndFeedOutput>>> output classes.
Following is the full code for the servlet.
+------+
package com.sun.syndication.samples.servlet;
import com.sun.syndication.feed.synd.*;
import com.sun.syndication.io.FeedException;
import com.sun.syndication.io.SyndFeedOutput;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.text.DateFormat;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.List;
/**
* Sample Servlet that serves a feed created with ROME.
* <p>
* The feed type is determined by the 'type' request parameter, if the parameter is missing it defaults
* to the 'default.feed.type' servlet init parameter, if the init parameter is missing it defaults to 'atom_0.3'
* <p>
* @author Alejandro Abdelnur
*
*/
public class FeedServlet extends HttpServlet {
private static final String DEFAULT_FEED_TYPE = "default.feed.type";
private static final String FEED_TYPE = "type";
private static final String MIME_TYPE = "application/xml; charset=UTF-8";
private static final String COULD_NOT_GENERATE_FEED_ERROR = "Could not generate feed";
private static final DateFormat DATE_PARSER = new SimpleDateFormat("yyyy-MM-dd");
private String _defaultFeedType;
public void init() {
_defaultFeedType = getServletConfig().getInitParameter(DEFAULT_FEED_TYPE);
_defaultFeedType = (_defaultFeedType!=null) ? _defaultFeedType : "atom_0.3";
}
public void doGet(HttpServletRequest req,HttpServletResponse res) throws IOException {
try {
SyndFeed feed = getFeed(req);
String feedType = req.getParameter(FEED_TYPE);
feedType = (feedType!=null) ? feedType : _defaultFeedType;
feed.setFeedType(feedType);
res.setContentType(MIME_TYPE);
SyndFeedOutput output = new SyndFeedOutput();
output.output(feed,res.getWriter());
}
catch (FeedException ex) {
String msg = COULD_NOT_GENERATE_FEED_ERROR;
log(msg,ex);
res.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR,msg);
}
}
protected SyndFeed getFeed(HttpServletRequest req) throws IOException,FeedException {
SyndFeed feed = new SyndFeedImpl();
feed.setTitle("Sample Feed (created with ROME)");
feed.setLink("http://rome.dev.java.net");
feed.setDescription("This feed has been created using ROME (Java syndication utilities");
List entries = new ArrayList();
SyndEntry entry;
SyndContent description;
entry = new SyndEntryImpl();
entry.setTitle("ROME v0.1");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/rome01");
try {
entry.setPublishedDate(DATE_PARSER.parse("2004-06-08"));
}
catch (ParseException ex) {
// IT CANNOT HAPPEN WITH THIS SAMPLE
}
description = new SyndContentImpl();
description.setType("text/plain");
description.setValue("Initial release of ROME");
entry.setDescription(description);
entries.add(entry);
entry = new SyndEntryImpl();
entry.setTitle("Rome v0.2");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/rome02");
try {
entry.setPublishedDate(DATE_PARSER.parse("2004-06-16"));
}
catch (ParseException ex) {
// IT CANNOT HAPPEN WITH THIS SAMPLE
}
description = new SyndContentImpl();
description.setType("text/plain");
description.setValue("Bug fixes, minor API changes and some new features"+
"<p>For details check the <a href=\"https://rometools.jira.com/wiki/display/ROME/Change+Log#ChangeLog-Changesmadefromv0.2tov0.3\">Changes Log for 0.2</a></p>");
entry.setDescription(description);
entries.add(entry);
entry = new SyndEntryImpl();
entry.setTitle("ROME v0.3");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/rome03");
try {
entry.setPublishedDate(DATE_PARSER.parse("2004-07-27"));
}
catch (ParseException ex) {
// IT CANNOT HAPPEN WITH THIS SAMPLE
}
description = new SyndContentImpl();
description.setType("text/html");
description.setValue("<p>Bug fixes, API changes, some new features and some Unit testing</p>"+
"<p>For details check the <a href=\"https://rometools.jira.com/wiki/display/ROME/Change+Log#ChangeLog-Changesmadefromv0.3tov0.4\">Changes Log for 0.3</a></p>");
entry.setDescription(description);
entries.add(entry);
entry = new SyndEntryImpl();
entry.setTitle("ROME v0.4");
entry.setLink("http://wiki.java.net/bin/view/Javawsxml/rome04");
try {
entry.setPublishedDate(DATE_PARSER.parse("2004-09-24"));
}
catch (ParseException ex) {
// IT CANNOT HAPPEN WITH THIS SAMPLE
}
description = new SyndContentImpl();
description.setType("text/html");
description.setValue("<p>Bug fixes, API changes, some new features, Unit testing completed</p>"+
"<p>For details check the <a href=\"https://rometools.jira.com/wiki/display/ROME/Change+Log#ChangeLog-Changesmadefromv0.4tov0.5\">Changes Log for 0.4</a></p>");
entry.setDescription(description);
entries.add(entry);
feed.setEntries(entries);
return feed;
}
}
+------+
To use the <<<FeedServlet>>> we need to create a Web Application. For the Web Application we need a deployment descriptor, the <<<web.xml>>> file:
+------+
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
<display-name>ROME Samples</display-name>
<servlet>
<servlet-name>FeedServlet</servlet-name>
<servlet-class>com.sun.syndication.samples.servlet.FeedServlet</servlet-class>
<init-param>
<param-name>default.feed.type</param-name>
<param-value>rss_2.0</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>FeedServlet</servlet-name>
<url-pattern>/feed</url-pattern>
</servlet-mapping>
</web-app>
+------+
To build the sample Web Application, just run maven war in the samples sub\-project. The WAR file, <<<rome\-samples.war>>>, will be created under the <<<target>>> directory. Deploy the WAR in a servlet container and the <<<FeedServlet>>> should be up an running. If you are using Tomcat 4 or Tomcat 5 and the WAR file was dropped in the <<<$\{TOMCAT\}/webapps>>> directory the URL for the <<<FeedServlet>>> would be {{{http://localhost:8080/rome\-samples/feed}http://localhost:8080/rome\-samples/feed}} in a default localhost Tomcat installation.

109
src/site/apt/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/TheCopyFromInterface.apt Normal file
View file

@ -0,0 +1,109 @@
-----
The CopyFrom interface
-----
mkurz
-----
2011-08-15 08:57:12.280
-----
The CopyFrom interface
The CopyFrom interface defines functionality similar to a deep cloning. The difference with the clone() method (besides the deep cloning requirements) is that the object to be the copy of the original one has to be explicitly created and it is this object the one that triggers the deep copying process. Implemetations of the CopyFrom interface should work propertly on arrays, collections, CopyFrom and basic type properties.
Using CopyFrom objects enables copying data between different implementations of a given interface without these implementation having to know about each other.
CopyFrom is unidirectional. A class implementing the CopyFrom knows how to extract properties from the given class (commonly having an interface in common).
A simple example using the CopyFrom interface is:
+------+
public interface Foo extends CopyFrom {
public void setName(String name);
public String getName();
public void setValues(Set values);
public Set getValues();
}
public class FooImplA implements Foo {
private String _name;
private Set _values;
public void setName(String name) {
_name = name;
}
public String getName() {
return _name;
}
public void setValues(Set values) {
_values = values;
}
public Set getValues() {
return _values;
}
public void copyFrom(Object obj) {
Foo other = (Foo) obj;
setName(other.getName());
setValues(new HashSet(other.getValues());
}
public Class getInterface() {
return Foo.class;
}
}
public class FooImplB implements Foo {
private Map _data;
public FooImplB() {
_data = new HashMap();
}
public void setName(String name) {
_data.put("name",name);
}
public String getName() {
return (String) _data.get("name");
}
public void setValues(Set values) {
_data.put("values",values);
}
public Set getValues() {
return (Set) _data.get("values");
}
public void copyFrom(Object obj) {
Foo other = (Foo) obj;
setName(other.getName());
setValues(new HashSet(other.getValues());
}
public Class getInterface() {
return Foo.class;
}
}
+------+
A use case for the CopyFrom functionality is a Java Bean implementation of an interface and a persistency implementation (such as Hibernate) of the the same interface that may add extra persistency related properties to the bean (ie, the 'Id' property as the persistency layer primary key).
For bean, array and collection properties the bean being invoked which copyFrom() method is invoked is responsible for those properties.
For properties implementing the CopyFrom interface, the bean must create a property instance implementing the interface returned by the getInterface() method. This allows the bean doing the copyFrom() to handle specialized subclasses of property elements propertly. This is also applicacle to array and collection properties. The 'modules' property of the SyndFeed and SyndEntry beans is a use case of this feature where the copyFrom() invocation must create different beans subclasses for each type of module, the getInteface() helps to find the right implementation.

163
src/site/apt/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/UnderstandingRssAndAtOMUtilitiEsROMEBeanUtilities.apt Normal file
View file

@ -0,0 +1,163 @@
-----
Understanding Rss and atOM utilitiEs (ROME) Bean Utilities
-----
mkurz
-----
2011-08-15 08:46:28.502
-----
Understanding Rss and atOM utilitiEs (ROME) Bean Utilities
ROME bean utilities are not part of ROME public API. They are used by the default implementation of ROME beans and it may be useful for alternate implementations as well. It is important to keep in mind that these APIs are not public and they are subject to change breaking backward compatibility.
Rome <com.sun.syndication.feed.impl> package contains a set of Java classes that provide support for all the basic features Java Beans commonly must have: toString, equals, hashcode and cloning.
By using these classes Beans don't have to hand code these functions. This greatly simplifies things when Beans have several properties, collection properties and composite properties.
The <CloneableBean>, <EqualsBean>, <ToStringBean> and <ObjectBean> classes use instrospection on the properties of the classes using them. This is done recursively on all properties. All ROME Beans default implementations leverage these classes.
*ToStringBean
Beans implementing the ToString interface must implement the toString(String prefix) method. This method must print the bean properties names and values, one per per line, separating the name and value with an '\=' sign and prefixing the name with the given prefix parameter using the same notation used in the JSP expression language used in JSTL and in JSP 2.0. This must be done recursively for all array, collection and ToString properties.
The ToStringBean class provides an implementation of the toString() method producing a detailed output of all the properties of the Bean being processed. The ToStringBean constructor takes the class definition the ToStringBean class should use for properties scanning \-using instrospection\- for printing, normally it is the class of the Bean using the ToStringBean.
*Using the ToStringBean class
+------+
public class MyBean {
public Foo getFoo() { ... }
public void setFoo(Foo foo) { ... }
public String getName() { ... }
public void setName(String name) { ... }
public List getValues() { ... }
public void setValues(List values) { ... }
public String toString(String prefix) {
ToStringBean tsBean = new ToStringBean(MyBean.class,this);
return tsBean.toString(prefix);
}
public String toString() {
return toString("myBean");
}
}
+------+
*EqualBean
The EqualsBean class provides a recursive introspetion\-based implementation of the equals() and hashCode() methods working on the Bean properties. The EqualsBean constructor takes the class definition that should be properties scanned (using introspection) by the equals() and thehashCode() methods. The EqualsBean class works on array, collection, bean and basic type properties.
**Using the EqualsBean class
+------+
public class MyBean {
public Foo getFoo() { ... }
public void setFoo(Foo foo) { ... }
public String getName() { ... }
public void setName(String name) { ... }
public List getValues() { ... }
public void setValues(List values) { ... }
public boolean equals(Object obj) {
EqualsBean eBean = new EqualsBean(MyBean.class,this);
return eBean.beanEquals(obj);
}
public int hashCode() {
EqualsBean equals = new EqualsBean(MyBean.class,this);
return equals.beanHashCode();
}
}
+------+
*CloneableBean
The CloneableBean class provides a recursive introspetion\-based implementation of the clone() method working on the Bean properties. The CloneableBean class works on array, collection, bean and basic type properties.
**Using the CloneableBean class
+------+
public class MyBean implements Cloneable {
public Foo getFoo() { ... }
public void setFoo(Foo foo) { ... }
public String getName() { ... }
public void setName(String name) { ... }
public List getValues() { ... }
public void setValues(List values) { ... }
public Object clone() {
CloneableBean cBean = new CloneableBean(this);
return cBean.beanClone();
}
}
+------+
By default, the CloneableBean copies all properties of the given object. It also supports an ignore\-properties set, the property names in this set will not be copied to the cloned instance. This is useful for cases where the Bean has convenience properties (properties that are actually references to other properties or properties of properties). For example SyndFeed and SyndEntry beans have convenience properties, publishedDate, author, copyright and categories all of them mapped to properties in the DC Module.
*ObjectBean
The ObjectBean is a convenience bean providing ToStringBean, EqualsBean and CloneableBean functionality support. Also, ObjectBeans implements the Serializable interface making the beans serializable if all its properties are. Beans extending ObjectBean get toString(), equals(),hashCode() and clone() support as defined above.
And example of using the ObjectBean class is:
+------+
public class MyBean extends ObjectBean {
public MyBean() {
super(MyBean.class);
}
public Foo getFoo() { ... }
public void setFoo(Foo foo) { ... }
public String getName() { ... }
public void setName(String name) { ... }
public List getValues() { ... }
public void setValues(List values) { ... }
}
+------+
It can also be used in delegation mode instead as some of the previous examples.

172
src/site/apt/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.apt Normal file
View file

@ -0,0 +1,172 @@
-----
XML Charset Encoding detection, how Rss and atOM utilitiEs (ROME) helps getting the right charset encoding
-----
mkurz
-----
2011-08-15 08:55:25.019
-----
XML Charset Encoding detection, how Rss and atOM utilitiEs (ROME) helps getting the right charset encoding
Determining the charset set encoding of an XML document it may prove not as easy as it seems, and when the XML document is served over HTTP things get a little more hairy.
Current Java libraries or utilities don't do this by default, A JAXP SAX parser may detect the charset encoding of a XML document looking at the first bytes of the stream as defined Section 4.3.3 and Appendix F.1 of the in {{{http://www.w3.org/TR/2004/REC\-xml\-20040204/}XML 1.0 (Third Edition)}} specification. But Appendix F.1 is non\-normative and not all Java XML parsers do it right now. For example the JAXP SAX parser implementation in {{{http://java.sun.com/j2se/1.4.2}J2SE 1.4.2}} does not handle Appendix F.1 and {{{http://xml.apache.org/xerces2\-j/}Xerces 2.6.2}} just added support for it. But still this does not solve the whole problem. JAXP SAX parsers are not aware of the HTTP transport rules for charset encoding resolution as defined by {{{http://www.ietf.org/rfc/rfc3023.txt}RFC 3023}}. They are not because they operate on a byte stream or a char stream without any knowledge of the stream transport protocol, HTTP in this case.
{{{http://diveintomark.org/}Mark Pilgrim}} did a very good job explaining how the charset encoding should be determined, {{{http://diveintomark.org/archives/2004/02/13/xml\-media\-types}Determining the character encoding of a feed}} and {{{http://www.xml.com/pub/a/2004/07/21/dive.html}XML on the Web Has Failed}}.
To isolate developers from this issue ROME has a special character stream class, the <XmlReader>. The <XmlReader> class is a subclass of the <java.io.Reader> that detects the charset encoding of XML documents read from files, input streams, URLs and input streams obtained over HTTP. Ideally this should be built into the JAXP SAX classes, most likely in the InputSource class.
*Default Lenient Behavior
It is very common for many sites, due to improper configuration or lack of knowledge, to declare an invalid charset encoding. Invalid according to the XML 1.0 specification and the RFC 3023. For example a mismatch between the implicit charset encoding in the HTTP content\-type and the explicit charset encoding in the XML prolog.
Because of this, ROME XmlReader by default has a lenient detection. This lenient detection works in the following order:
* A strict charset encoding detection, as specified by the Algorithms below is attempted
* If the content type was 'text/html' it replaces it with 'text/xml' and tries strict charset encoding detection again
* If the XML prolog had a charset encoding that encoding is used
* If the content type had a charset encoding that encoding is used
* 'UTF\-8' is used
[]
The XmlReader class has 2 constructors that allow a strict (non\-lenient) charset encoding detection to be performed. This constructors take a lenient boolean flag, the flag should be set to <false> for a strict detection.
*The Algorithms per XML 1.0 and RFC 3023 specifications
Following it's a detailed explanation on the algorithms the <XmlReader> uses to determine the charset encoding. These algorithms first appeared in {{{http://blogs.sun.com/roller/page/tucu/Weblog}Tucu's Weblog}}.
*Raw XML charset encoding detection
Detection of the charset encoding of a XML document without external information (i.e. reading a XML document from a file). Following {{{http://www.w3.org/TR/2004/REC\-xml\-20040204/#charencoding}Section 4.3.3}} and {{{http://www.w3.org/TR/REC\-xml/#sec\-guessing\-no\-ext\-info}Appendix F.1}} of the XML 1.0 specification the charset encoding of an XML document is determined as follows:
+------+
BOMEnc : byte order mark. Possible values: 'UTF-8', 'UTF-16BE', 'UTF-16LE' or NULL
XMLGuessEnc: best guess using the byte representation of the first bytes of XML declaration
('<?xml...?>') if present. Possible values: 'UTF-8', 'UTF-16BE', 'UTF-16LE' or NULL
XMLEnc : encoding in the XML declaration ('<?xml encoding="..."?>'). Possible values: anything or NULL
if BOMEnc is NULL
if XMLGuessEnc is NULL or XMLEnc is NULL
encoding is 'UTF-8' [1.0]
else
if XMLEnc is 'UTF-16' and (XMLGuessEnc is 'UTF-16BE' or XMLGuessEnc is 'UTF-16LE')
encoding is XMLGuessEnc [1.1]
else
encoding is XMLEnc [1.2]
else
if BOMEnc is 'UTF-8'
if XMLGuessEnc is not NULL and XMLGuessEnc is not 'UTF-8'
ERROR, encoding mismatch [1.3]
if XMLEnc is not NULL and XMLEnc is not 'UTF-8'
ERROR, encoding mismatch [1.4]
encoding is 'UTF-8'
else
if BOMEnc is 'UTF-16BE' or BOMEnc is 'UTF-16LE'
if XMLGuessEnc is not NULL and XMLGuessEnc is not BOMEnc
ERROR, encoding mismatch [1.5]
if XMLEnc is not NULL and XMLEnc is not 'UTF-16' and XMLEnc is not BOMEnc
ERROR, encoding mismatch [1.6]
encoding is BOMEnc
else
ERROR, cannot happen given BOMEnc possible values (see above) [1.7]
+------+
Byte Order Mark encoding and XML guessed encoding detection rules are clearly explained in the {{{http://www.w3.org/TR/REC\-xml/#sec\-guessing\-no\-ext\-info}XML 1.0 Third Edition Appendix F.1}}. Note that in this algorithm BOMEnc and XMLGuessEnc are restricted to UTF\-8 and UTF\-16\* encodings.
* <<#1.0.>> There is no BOM, an encoding or encoding family cannot be guessed from the first bytes in the stream, defaulting to UTF\-8.
* <<#1.1.>> Strictly following {{{http://www.w3.org/TR/2004/REC\-xml\-20040204/#charencoding}XML 1.0 Third Edition Section 4.3.3 Charset Encoding in Entities}} (2nd paragraph) no BOM and UTF\-16 XML declaration encoding is an error. The BOM is required to identify if the encoding is BE or LE. But if XMLEnc was read it means that the encoding byte order of the stream was guessed from the first bytes in the stream, note that this is possible only if the document starts with a XML declaration. The logic verifies that there is no conflicting encoding information and relaxes the BOM requirement if a XML declaration (that allows guessing the byte order) is present.
* <<#1.2.>> XMLEnc is present, it is not UTF\-16 (although it can be UTF\-16BE or UTF\-16LE), the guessed encoding is used to read the XML declaration encoding. Detecting encoding mismatches here it would require awareness of charset families, instead the algorithm relies on the charset encoding routines that will process the stream to discover and report mismatches. <IMPORTANT:> To handle other encodings (i.e. USC\-4 or EBCDIC encoding families) the algorithm should be extended here.
* <<#1.3, #1.4, #1.5, #1.6>> There is an explicit encoding mismatch.
* <<#1.7.>> Given the currently assumed BOMEnc values this case cannot happen. <IMPORTANT:> To handle other encodings (i.e. USC\-4 or EBCDIC encoding families) the algorithm should be extended here.
[]
**XML over HTTP charset encoding detection
Detection of the charset encoding of a XML document with external information (provided by HTTP). Following {{{http://www.w3.org/TR/2004/REC\-xml\-20040204/#charencoding}Section 4.3.3}}, {{{http://www.w3.org/TR/REC\-xml/#sec\-guessing\-no\-ext\-info}Appendix F.1}} and {{{http://www.w3.org/TR/2004/REC\-xml\-20040204/#sec\-guessing\-with\-ext\-info}Appendix F.2}} of the XML 1.0 specification, plus {{{http://www.ietf.org/rfc/rfc3023.txt}RFC 3023}} the charset encoding of an XML document served over HTTP is determined as follows:
+------+
ContentType: Content-Type HTTP header
CTMime : MIME type defined in the ContentType
CTEnc : charset encoding defined in the ContentType, NULL otherwise
BOMEnc : byte order mark. Possible values: 'UTF-8', 'UTF-16BE', 'UTF-16LE' or NULL
XMLGuessEnc: best guess using the byte representation of the first bytes of XML declaration
('<?xml...?>') if present. Possible values: 'UTF-8', 'UTF-16BE', 'UTF-16LE' or NULL
XMLEnc : encoding in the XML declaration ('<?xml encoding="..."?>'). Possible values: anything or NULL
APP-XML : RFC 3023 defined 'application/*xml' types
TEXT-XML : RFC 3023 defined 'text/*xml' types
if CTMime is APP-XML or CTMime is TEXT-XML
if CTEnc is NULL
if CTMime is APP-XML
encoding is determined using the Raw XML charset encoding detection algorithm [2.0]
else
if CTMime is TEXT-XML
encoding is 'US-ASCII' [2.1]
else
if (CTEnc is 'UTF-16BE' or CTEnc is 'UTF-16LE') and BOMEnc is not NULL
ERROR, RFC 3023 explicitly forbids this [2.2]
else
if CTEnc is 'UTF-16'
if BOMEnc is 'UTF-16BE' or BOMEnc is 'UTF-16LE'
encoding is BOMEnc [2.3]
else
ERROR, missing BOM or encoding mismatch [2.4]
else
encoding is CTEnc [2.5]
else
ERROR, handling for other MIME types is undefined [2.6]
+------+
Byte Order Mark encoding and XML guessed encoding detection rules are clearly explained in the {{{http://www.w3.org/TR/REC\-xml/#sec\-guessing\-no\-ext\-info}XML 1.0 Third Edition Appendix F.1}}. Note that in this algorithm BOMEnc and XMLGuessEnc are restricted to UTF\-8 and UTF\-16\* encodings.
* <<#2.0.>> HTTP content type declares a MIME of application type and XML sub\-type. There is not HTTP Content\-type charset encoding information. The charset encoding is determined using the Raw XML charset encoding detection algorithm. Refer to {{{http://www.ietf.org/rfc/rfc3023.txt}RFC 3023}} Section <3.2. Application/xml Registration>.
* <<#2.1.>> HTTP content type declares a MIME of text type and XML sub\-type. There is not HTTP Content\-type charset encoding information. The charset encoding is US\-ASCII. Refer to {{{http://www.ietf.org/rfc/rfc3023.txt}RFC 3023}} Section <3.1. Text/xml Registration>.
* <<#2.2.>> For text\-XML and application\-XML MIME types if the HTTP content type declares 'UTF\-16BE' or 'UTF\-16LE' as the charset encoding, a BOM is prohibited. Refer to {{{http://www.ietf.org/rfc/rfc3023.txt}RFC 3023}} Section <4. The Byte Order Mark (BOM) and Conversions to/from the UTF\-16 Charset>.
* <<#2.3.>> For text\-XML and application\-XML MIME types if the HTTP content type declares 'UTF\-16' as the charset encoding, a BOM is required and it must be used to determine the byte order. Refer to {{{http://www.ietf.org/rfc/rfc3023.txt}RFC 3023}} Section <4. The Byte Order Mark (BOM) and Conversions to/from the UTF\-16 Charset>.
* <<#2.4.>> For text\-XML and application\-XML MIME types if the HTTP content type declares 'UTF\-16' as the charset encoding, a BOM must be present and it must be 'UTF\-16BE' or 'UTF\-16LE'. Refer to {{{http://www.ietf.org/rfc/rfc3023.txt}RFC 3023}} Section <4. The Byte Order Mark (BOM) and Conversions to/from the UTF\-16 Charset>.
* <<#2.5.>> For text\-XML and application\-XML MIME types if the HTTP content type declares a charset encoding other than the UTF\-16 variants, that charset encoding is used, no other special handling is required.
* <<#2.6.>> There is not defined logic to determine the charset encoding based on the MIME type given by the HTTP content type.
[]

67
src/site/apt/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/index.apt Normal file
View file

@ -0,0 +1,67 @@
-----
Rss and atOM utilitiEs (ROME) v0.5 and above Tutorials and Articles
-----
mkurz
-----
2011-08-15 09:06:56.262
-----
Rss and atOM utilitiEs (ROME) v0.5 and above Tutorials and Articles
*Tutorials
The following tutorials show how to use the ROME API. They focus on the higher abstraction layer of classes offered by ROME, what we call the Synd\* classes. By using the Synd\* classes developers don't have to deal with the specifics of any syndication feed. They work with normalized feeds, the Synd\* feeds. This makes it much easier to write applications that have to deal with all the variety of syndication feed types in use today.
[[1]] {{{./RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToReadASyndicationFeed.html}Using ROME to read a syndication feed}}
[[1]] {{{./RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToConvertASyndicationFeedFromOneTypeToAnother.html}Using ROME to convert a syndication feed from one type to another}}
[[1]] {{{./RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToAggregateManySyndicationFeedsIntoASingleOne.html}Using ROME to aggregate many syndication feeds into a single one}}
[[1]] {{{./RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToCreateAndWriteASyndicationFeed.html}Using ROME to create and write a feed}}
[[1]] {{{./RssAndAtOMUtilitiEsROMEV0.5TutorialDefiningACustomModuleBeanParserAndGenerator.html}Defining a Custom Module bean, parser and generator}}
[[1]] {{{./RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEWithinAServletToCreateAndReturnAFeed.html}Using ROME within a Servlet to create and return a feed}}
[]
For instructions on how to build and run the samples used in the tutorials {{{./RssAndAtOMUtilitiEsROMEV0.5HowToBuildAndRunTheTutorialsSampleCode.html}click here}}.
*Additional Information
* {{{./UnderstandingRssAndAtOMUtilitiEsROMEBeanUtilities.html}Bean Utilities}}
* {{{./XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.html}XML Charset Encoding detection}}
* {{{./TheCopyFromInterface.html}The CopyFrom interface (rome)}}
* {{{./FeedsDateElementsMappingToSyndFeedAndSyndEntry.html}Date Elements Mapping}}
* {{{./RssAndAtOMUtilitiEsROMEPluginsMechanism.html}Plugins Mechanism}}
* {{{./FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.html}URI Mapping}}
[]
*Articles
* {{{http://www.xml.com/pub/a/2006/02/22/rome\-parse\-publish\-rss\-atom\-feeds\-java.html}O'Reilly \- ROME in a Day: Parse and Publish Feeds in Java}} by {{{http://markwoodman.com/}Mark Woodman}} (February 22, 2006).\
<A hands\-on tutorial that shows you how to act like your own FeedBurner and add a footer to existing feed items.>
* {{{http://today.java.net/pub/a/today/2006/02/02/tour\-of\-rome.html}java.net \- Taking a Tour of ROME}} by {{{http://www.rjray.org/}Randy J. Ray}} (February 2, 2006).\
<Working with web syndication? Your development path may lead you to ROME\-\-not the city, but the syndication framework, which makes working with RSS and Atom a breeze for both server\-and client\-side code. Randy J. Ray has an introduction to this project.>
* {{{http://inkblots.markwoodman.com/rss\-diaries/patrick\-chanezon}inkBlots \- Interview with Patrick Chanezon}} by {{{http://markwoodman.com/}Mark Woodman}} (July 13, 2005).\
<Why and how we started this project.>
[]

441
src/site/apt/SitesToMoveFromJava.net.apt Normal file
View file

@ -0,0 +1,441 @@
-----
sites to move from java.net
-----
mkurz
-----
2011-08-16 03:51:15.314
-----
sites to move from java.net
*----+--+--+
| |
source
||
target
||
state
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/HowToBuild}http://wiki.java.net/twiki/bin/view/Javawsxml/HowToBuild}}
|
{{{./HowToBuildRome.html}How to build Rome?}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/PoweredByRome}http://wiki.java.net/twiki/bin/view/Javawsxml/PoweredByRome}}
|
{{{./ProductsOrSitesPoweredByROME.html}Products or sites powered by ROME (rome)}}
|
missing images
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/PreservingWireFeeds}http://wiki.java.net/twiki/bin/view/Javawsxml/PreservingWireFeeds}}
|
{{{./PreservingWireFeeds.html}Preserving WireFeeds (rome)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/ProjectMotivation}http://wiki.java.net/twiki/bin/view/Javawsxml/ProjectMotivation}}
|
{{{./WhyThisProject.html}Why this project?}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04Common}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04Common}}
|
{{{./HowRomeWorks/UnderstandingTheRomeCommonClassesAndInterfaces.html}Understanding the Rome common classes and interfaces (rome)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04HowRomeWorks}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04HowRomeWorks}}
|
{{{./HowRomeWorks/index.html}How Rome works (rome)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04TutorialFeedAggregator}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04TutorialFeedAggregator}}
|
{{{./HowRomeWorks/RomeV0.4TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html}Rome v0.4 Tutorial, Using Rome to aggregate many syndication feeds into a single one (rome)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04TutorialFeedConverter}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04TutorialFeedConverter}}
|
{{{./HowRomeWorks/RomeV0.4TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html}Rome v0.4 Tutorial, Using Rome to convert a syndication feed from one type to another (rome)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04TutorialFeedReader}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04TutorialFeedReader}}
|
{{{./HowRomeWorks/RomeV0.4TutorialUsingRomeToReadASyndicationFeed.html}Rome v0.4 Tutorial, Using Rome to read a syndication feed (rome)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04TutorialFeedWriter}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04TutorialFeedWriter}}
|
{{{./HowRomeWorks/RomeV0.4TutorialUsingRomeToCreateAndWriteASyndicationFeed.html}Rome v0.4 Tutorial, Using Rome to create and write a syndication feed (rome)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04TutorialSampleModule}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04TutorialSampleModule}}
|
{{{./HowRomeWorks/RomeV0.4TutorialDefiningACustomModuleBeanParserAndGenerator.html}Rome v0.4 Tutorial, Defining a Custom Module (bean, parser and generator)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04Tutorials}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04Tutorials}}
|
{{{./ROMEReleases/ROME0.4Beta/RomeV0.4Tutorials/index.html}Rome v0.4 Tutorials (rome)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04URIMapping}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04URIMapping}}
|
{{{./RomeV0.4FeedAndEntryURIMapping.html}Rome v0.4, Feed and Entry URI Mapping (rome)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05BeanUtils}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05BeanUtils}}
|
{{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/UnderstandingRssAndAtOMUtilitiEsROMEBeanUtilities.html}Understanding Rss and atOM utilitiEs (ROME) Bean Utilities}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05CharsetEncoding}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05CharsetEncoding}}
|
{{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.html}XML Charset Encoding detection, how Rss and atOM utilitiEs (ROME) helps getting the right charset encoding}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05CopyFrom}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05CopyFrom}}
|
{{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/TheCopyFromInterface.html}The CopyFrom interface (rome)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05DateMapping}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05DateMapping}}
|
{{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html}Feeds Date Elements Mapping to SyndFeed and SyndEntry (rome)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05Plugins}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05Plugins}}
|
{{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEPluginsMechanism.html}Rss and atOM utilitiEs (ROME) Plugins Mechanism}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05SamplesHowTo}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05SamplesHowTo}}
|
{{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5HowToBuildAndRunTheTutorialsSampleCode.html}Rss and atOM utilitiEs (ROME) v0.5, How to build and run the tutorials sample code}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05TutorialFeedAggregator}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05TutorialFeedAggregator}}
|
{{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToAggregateManySyndicationFeedsIntoASingleOne.html}Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to aggregate many syndication feeds into a single one}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05TutorialFeedConverter}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05TutorialFeedConverter}}
|
{{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToConvertASyndicationFeedFromOneTypeToAnother.html}Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to convert a syndication feed from one type to another}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05TutorialFeedReader}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05TutorialFeedReader}}
|
{{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToReadASyndicationFeed.html}Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to read a syndication feed}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05TutorialFeedServlet}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05TutorialFeedServlet}}
|
{{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEWithinAServletToCreateAndReturnAFeed.html}Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME within a Servlet to create and return a feed}}
|
links in code examples messed up
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05TutorialFeedWriter}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05TutorialFeedWriter}}
|
{{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToCreateAndWriteASyndicationFeed.html}Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to create and write a syndication feed}}
|
links in code examples messed up
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05TutorialSampleModule}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05TutorialSampleModule}}
|
{{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialDefiningACustomModuleBeanParserAndGenerator.html}Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Defining a Custom Module (bean, parser and generator)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05Tutorials}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05Tutorials}}
|
{{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/index.html}Rss and atOM utilitiEs (ROME) v0.5 and above Tutorials and Articles}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05URIMapping}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome05URIMapping}}
|
{{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.html}Feed and Entry URI Mapping, how SyndFeed and SyndEntry 'uri' properties map to RSS and Atom elements (rome)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/Rome07DateParsing}http://wiki.java.net/twiki/bin/view/Javawsxml/Rome07DateParsing}}
|
{{{./RssAndAtOMUtiliEsROMEV0.7DateAndTimeParsing.html}Rss and atOM utiliEs (ROME) v0.7 Date and Time Parsing}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/ROME2Proposal2}http://wiki.java.net/twiki/bin/view/Javawsxml/ROME2Proposal2}}
|
{{{./ROMEDevelopmentProposals/ROME22ndProposalJuly18th2006CURRENT.html}ROME2 2nd Proposal (July 18th 2006) CURRENT}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/ROME2Proposal}http://wiki.java.net/twiki/bin/view/Javawsxml/ROME2Proposal}}
|
{{{./ROMEDevelopmentProposals/ROME21stProposalJune10th2006NOTCURRENT.html}ROME2 1st Proposal (June 10th 2006) NOT CURRENT}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/RomeAndMaven2}http://wiki.java.net/twiki/bin/view/Javawsxml/RomeAndMaven2}}
|
{{{./ROMEAndMaven2.html}ROME and Maven 2 (rome)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/RomeAndOSGi}http://wiki.java.net/twiki/bin/view/Javawsxml/RomeAndOSGi}}
|
{{{./ROMEAndOSGI.html}ROME and OSGI (rome)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/RomeAPIFAQ}http://wiki.java.net/twiki/bin/view/Javawsxml/RomeAPIFAQ}}
|
{{{./RomeAPIFAQ.html}Rome API FAQ (rome)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/RomeComparisonOtherLibs}http://wiki.java.net/twiki/bin/view/Javawsxml/RomeComparisonOtherLibs}}
|
{{{./WhatSWrongWithOtherExistingRSSParsingLibraries.html}What's wrong with other existing RSS parsing libraries?}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/RomeDevelopmentProcess}http://wiki.java.net/twiki/bin/view/Javawsxml/RomeDevelopmentProcess}}
|
{{{./ROMEDevelopmentProcess.html}ROME Development Process (rome)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/RomeFeatureRequests}http://wiki.java.net/twiki/bin/view/Javawsxml/RomeFeatureRequests}}
|
{{{./ROMEDevelopmentProposals/ROMEFeatureRequests.html}ROME Feature Requests (rome)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/RomeProposals}http://wiki.java.net/twiki/bin/view/Javawsxml/RomeProposals}}
|
{{{./ROMEDevelopmentProposals/index.html}ROME Development Proposals (rome)}}
|
|
*----+--+--+
|
{{{http://wiki.java.net/twiki/bin/view/Javawsxml/RomeWhatAPIToUse}http://wiki.java.net/twiki/bin/view/Javawsxml/RomeWhatAPIToUse}}
|
{{{./WhatPartOfTheAPIYouShouldBeUsing.html}What part of the API you should be using (rome)}}
|
|
*----+--+--+

125
src/site/apt/TutorialsAndArticles.apt Normal file
View file

@ -0,0 +1,125 @@
-----
Tutorials and Articles
-----
mkurz
-----
2011-08-15 15:03:00.951
-----
Tutorials and Articles
*Tutorials and documentation
* Inside ROME, How Things Work
* {{{./HowRomeWorks/index.html}How ROME Works}}, Understanding Rome (a detailed overview by Dave Johnson)
* {{{./HowRomeWorks/UnderstandingTheRomeCommonClassesAndInterfaces.html}Rome common Package}}, bean utilities, enums, copying and clonning
* {{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEPluginsMechanism.html}ROME Plugins Mechanism}}, bootstrap, adding and changing parsers, generators, converters and modules
* {{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html}Feeds Date Elements}}, how Date data is mapped to SyndFeed and SyndEntry
* {{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.html}Feed and Entry URI Mapping}}, how SyndFeed and SyndEntry 'uri' properties map to concrete feed elements
* {{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.html}XML Charset Encoding Detection}}, how Rome helps getting the right charset encoding
* {{{./RssAndAtOMUtiliEsROMEV0.7DateAndTimeParsing.html}Rss and atOM utiliEs (ROME) v0.7 Date and Time Parsing (rome)}}
* {{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/index.html}Rss and atOM utilitiEs (ROME) v0.5 and above Tutorials and Articles (rome)}}
* {{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToReadASyndicationFeed.html}Using ROME to read a syndication feed}}
* {{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToConvertASyndicationFeedFromOneTypeToAnother.html}Using ROME to convert a syndication feed from one type to another}}
* {{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToAggregateManySyndicationFeedsIntoASingleOne.html}Using ROME to aggregate many syndication feeds into a single one}}
* {{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToCreateAndWriteASyndicationFeed.html}Using ROME to create and write a feed}}
* {{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialDefiningACustomModuleBeanParserAndGenerator.html}Defining a Custom Module bean, parser and generator}}
* {{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEWithinAServletToCreateAndReturnAFeed.html}Using ROME within a Servlet to create and return a feed}}
* {{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5HowToBuildAndRunTheTutorialsSampleCode.html}instructions on how to build and run the samples used in the tutorials}}
* {{{./ROMEReleases/ROME0.4Beta/RomeV0.4Tutorials/index.html}Rome v0.4 Tutorials (rome)}}
* {{{./HowRomeWorks/RomeV0.4TutorialUsingRomeToReadASyndicationFeed.html}Using Rome to read a syndication feed}}
* {{{./HowRomeWorks/RomeV0.4TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html}Using Rome to convert a syndication feed from one type to another}}
* {{{./HowRomeWorks/RomeV0.4TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html}Using Rome to aggregate many syndication feeds into a single one}}
* {{{./HowRomeWorks/RomeV0.4TutorialUsingRomeToCreateAndWriteASyndicationFeed.html}Using Rome to create and write a feed}}
* {{{./HowRomeWorks/RomeV0.4TutorialDefiningACustomModuleBeanParserAndGenerator.html}Defining a Custom Module bean, parser and generator}}
* {{{./ROMEReleases/ROME0.4Beta/RomeV0.4Tutorials/RomeV0.4TutorialUsingRomeWithinAServletToCreateAndReturnAFeed.html}Using Rome within a Servlet to create and return a feed}}
* {{{./ROMEReleases/ROME0.4Beta/RomeV0.4Tutorials/RomeV0.4HowToBuildAndRunTheTutorialsSampleCode.html}instructions on how to build and run the samples used in the tutorials}}
* {{{./ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/index.html}Rome v0.3 Tutorials (rome)}}
* {{{./ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToReadASyndicationFeed.html}Using Rome to read a syndication feed}}
* {{{./ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html}Using Rome to convert a syndication feed from one type to another}}
* {{{./ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html}Using Rome to aggregate many syndication feeds into a single one}}
* {{{./ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToCreateAndWriteASyndicationFeed.html}Using Rome to create and write a feed}}
* {{{./ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialDefiningACustomModuleBeanParserAndGenerator.html}Defining a Custom Module bean, parser and generator}}
* {{{./ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3HowToBuildAndRunTheTutorialsSampleCode.html}instructions on how to build and run the samples used in the tutorials}}
* {{{./ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/index.html}Rome v0.2 Tutorials (rome)}}
* {{{./ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/RomeV0.2TutorialUsingRomeToReadASyndicationFeed.html}Using Rome to read a syndication feed}}
* {{{./ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/RomeV0.2TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html}Using Rome to convert a syndication feed from one type to another}}
* {{{./ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/RomeV0.2TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html}Using Rome to aggregate many syndication feeds into a single one}}
* {{{./ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1HowToBuildAndRunTheTutorialsSampleCode.html}instructions on how to build and run the samples used in the tutorials}}
* {{{./ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/index.html}Rome v0.1 Tutorials (rome)}}
* {{{./ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1TutorialUsingRomeToReadASyndicationFeed.html}Using Rome to read a syndication feed}}
* {{{./ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html}Using Rome to convert a syndication feed from one type to another}}
* {{{./ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html}Using Rome to aggregate many syndication feeds into a single one}}
* {{{./ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1HowToBuildAndRunTheTutorialsSampleCode.html}instructions on how to build and run the samples used in the tutorials}}
[]
*Articles
* {{{http://www.xml.com/pub/a/2006/02/22/rome\-parse\-publish\-rss\-atom\-feeds\-java.html}O'Reilly \- ROME in a Day: Parse and Publish Feeds in Java}} by {{{http://markwoodman.com/}Mark Woodman}} (February 22, 2006).\
<A hands\-on tutorial that shows you how to act like your own FeedBurner and add a footer to existing feed items.>
* {{{http://today.java.net/pub/a/today/2006/02/02/tour\-of\-rome.html}java.net \- Taking a Tour of ROME}} by {{{http://www.rjray.org/}Randy J. Ray}} (February 2, 2006).\
<Working with web syndication? Your development path may lead you to ROME\-\-not the city, but the syndication framework, which makes working with RSS and Atom a breeze for both server\-and client\-side code. Randy J. Ray has an introduction to this project.>
* {{{http://inkblots.markwoodman.com/rss\-diaries/patrick\-chanezon}inkBlots \- Interview with Patrick Chanezon}} by {{{http://markwoodman.com/}Mark Woodman}} (July 13, 2005).\
<Why and how we started this project.>
[]

16
src/site/apt/WhatPartOfTheAPIYouShouldBeUsing.apt Normal file
View file

@ -0,0 +1,16 @@
-----
What part of the API you should be using
-----
mkurz
-----
2011-08-14 14:12:52.930
-----
What part of the API you should be using
Rome API allows developers to work with classes that closely resemble a particular syndication feed type. For example, the Channel class for RSS feeds and the Feed class for Atom feeds. All the Synd\* classes, which leverage the RSS and Atom specific classes, are the bridge to go from one syndication type to another.
For day to day coding, we found ourselves using the <<Synd\*>> classes (in <<com.sun.syndication.feed.synd>>, <<com.sun.syndication.feed.module>> and <<com.sun.syndication.io>> packages) as we need to do applications that understand the different syndication feed types. And it is much simpler to work with a higher and independent abstraction.

85
src/site/apt/WhatSWrongWithOtherExistingRSSParsingLibraries.apt Normal file
View file

@ -0,0 +1,85 @@
-----
What's wrong with other existing RSS parsing libraries?
-----
mkurz
-----
2011-08-14 14:34:42.032
-----
What's wrong with other existing RSS parsing libraries?
Before we started with Rome we've evaluated other Java syndication management libraries to see if they'd fit our criteria. Feel free to update this evaluation if we forgot or mischaracterized your favorite library: this is a wiki after all:\-)
*Informa
The {{{http://informa.sourceforge.net/}Informa: RSS Library for Java}} which exists since 2002 is too complicated to grasp and use. As of this writing it has {{{http://informa.sourceforge.net/apidocs/de/nava/informa/core/package\-summary.html}19 interfaces and 12 marker interfaces}}. It supports all RSS flavors in input, and only 1.0 and 0.91 in output.
No RSS 2.0 output.
No support for Atom at all.
They have some interesting features such as Hibernate and Castor based database serialization, and JSP taglibs, which are useful paraphernalia for server side application development. This seems to be their main focus of development today.
But we prefer to focus on our ESCAPE design criteria, so that our library does one thing really well: syndication parsing, abstract representation and conversion from/to all formats.
Thus our library will be useful for both client and server side developers.
We will develop the server side add\-on later when the basics will be well oiled.
**RSS4J
{{{http://www.churchillobjects.com/c/13005.html}RSS4J}} was released in version 0.92 in april 2002. It did not evolve since then.
The web site explains:
<This toolkit supports the three most commonly used RSS standards \- 0.90 (the original), 0.91 and 1.0. RSS 0.92 and 0.93 are not supported due to the dramatic changes it makes to the format and the fact that 1.0 is already finalized.>
No need to say more: it seems to be a dead project and doesn't even start to address our requirements.
**RSS Utilities
{{{http://java.sun.com/developer/technicalArticles/javaserverpages/rss_utilities/}RSS Utilities}} seems like a one\-shot project from Rodrigo Oliveira, released in august 2003. It is a taglib to display RSS in JSPs, and includes a small parser for RSS 0.91, 0.92 and 2.0.
It does not seem to be maintained, does not address RSS 1.0 and Atom.
I would encourage Rodrigo to rewrite his taglibs using Rome as the parser, and eventually to contribute them to Rome.
**RSSLibJ
{{{http://enigmastation.com/rsslibj}RSSLibJ}} is a full\-Java RSS generation and consumption library, primarily centering on generating RSS feeds but able to consume them as well. It's maintained, but undergoing a refactoring to change a rather undesirable dependency.
(This isn't a review \- this was added by one of RSSLibJ 's authors.)
**Sandler
Sandler is yet another parser except that it only supports Atom feeds. I can't say more than that because I haven't used it. And now I won't have to.
**Conclusion
These are the only RSS or Syndication management libraries we found in Java when we reviewed what was available and wether it was worth starting a new project. Feel free to add to it if we forgot something.

37
src/site/apt/WhyThisProject.apt Normal file
View file

@ -0,0 +1,37 @@
-----
Why this project?
-----
mkurz
-----
2011-08-14 14:35:51.661
-----
Why this project?
Various flavors of RSS and Atom syndication formats were reaching a tipping point in 2004. At Sun we started various projects involving these Syndication formats, but when looking around for Java libraries to take care of the parsing and generation of RSS we were not satisfied with what we found. {{{https://rometools.jira.com/}Project ROME}} was started out of this frustration.
Our requirements are to <<ESCAPE>> from {{{http://blogs.sun.com/tucu/entry/syndication_feeds_hell}Syndication Feeds Hell}}. In order to allow that the library must be:
* \*E\*asy to use: given a url, get back a feed object independent of the underlying format, and serialize the feed object to the format I want.
* \*S\*imple: RSS initially stood for "Really Simple Syndication"\*, and this simplicity is what made the format successful. Specifications wars have made the current situation much more complicated. The goal of the library is to give that simplicity back to developers: each API we use force on us a mental model of the domain and we are using more and more libraries on each project we implement. This library tries to ease the cognitive load of developers and provides a very simple model for feeds and entries, abstarcting out the details of the various underlying formats.
* \*C\*omplete: must handle all versions of RSS and Atom
* \*A\*bstract: provides a Java\-friendly abstraction layer on top of the various syndication specifications, that maps the commonalities of the various feed formats into a single simple JavaBeans Data Model.
* \*P\*owerful: lets me access all the metadata of the feeds regardless of their format. If I need them, lets me access optional metadata expressed in extensions accepted by various formats (RSS 1.0 modules, other namespaces in Atom).
* \*E\*xtensible: It needs to define a simple pluggable architecture to provide support for future extensions of the formats.
[]
\* \- not so, it was originally "RDF Site Summary", see: {{{http://goatee.net/2003/rss\-history.html}RSS History}}
We set out to create this library in the same spirit as the {{{http://www.jdom.org/mission/index.html}JDOM}} library for XML manipulation in Java, incorporating XOM's {{{http://www.artima.com/intv/jdom.html}Elliotte Rusty Harold's pearls of wisdom about API design and refactoring}} (see {{{http://www.artima.com/intv/airbags.html}Air Bags and Other Design Principles}} which links his 6 interviews with Bill Venners). ROME implementation uses JDOM.

102
src/site/apt/index.apt Normal file
View file

@ -0,0 +1,102 @@
-----
Home
-----
msmithi33
-----
2013-08-18 11:12:40.194
-----
Welcome to ROME
<"...ending syndication feed confusion by supporting all of 'em. "> <{{{http://blogs.sun.com/roller/page/webmink/20040616#rome_wasn_t_built_in}\*}}>
<<ROME is a set of>> <<R>><<SS and At>><<om>> <<Utiliti>><<e>><<s for Java that is open source under the Apache 2.0 license.>>
RSS 0.90, RSS 0.91 Netscape, RSS 0.91 Userland, RSS 0.92, RSS 0.93, RSS 0.94, RSS 1.0, RSS 2.0, Atom 0.3, Atom 1.0
ROME includes a set of parsers and generators for the various flavors of syndication feeds, as well as converters to convert from one format to another.
The parsers can give you back Java objects that are either specific for the format you want to work with, or a generic normalized SyndFeed class that
lets you work on with the data without bothering about the incoming or outgoing feed type.
If you use ROME for your site or software, please add it to the wiki page {{{./ProductsOrSitesPoweredByROME.html}PoweredByRome}}, or drop us an email
Some of the links in the Navigation are out of date. This is because no one can edit them at present. However any registered user can edit the content
of the pages and you'll find most of the links updated there, notably the Tutorials and Articles.
*ROME Subprojects
*----+--+--+
||Subproject||Purpose||Latest Release|
*----+--+--+
|{{{http://rometools.github.io/rome-fetcher/index.html}ROME Fetcher}}|A caching feed fetcher that supports retrieval of feeds via {{{http://fishbowl.pastiche.org/2002/10/21/http_conditional_get_for_rss_hackers}HTTP conditional GET}}. Supports ETags, GZip compression, and {{{http://bobwyman.pubsub.com/main/2004/09/using_rfc3229_w.html}RFC3229 Delta encoding}}.|{{{../fetcher/Releases/ROMEFetcher1.0.html}ROME Fetcher}} v1.0 (Mar 11 2009)|
*----+--+--+
|{{{http://rometools.github.io/rome-modules/index.html}Rome Modules}}|Provide support for feed extensions such as GeoRSS, iTunes, Microsoft SSE and SLE, Google GData and others.|{{{./index.html}ROME Modules 1.0}} (Feb 24 2011)|
*----+--+--+
|{{{http://rometools.github.io/rome-propono/index.html}ROME Propono}}|Supports publishing protocols, specifically the Atom Publishing Protocol and the legacy MetaWeblog API. Propono includes an Atom client library, an Atom server framework and a Blog client that supports both Atom protocol and the MetaWeblog API.|{{{../propono/ROMEProponoVersion0.6.html}ROME Propono v0.6}}.|
*----+--+--+
|{{{http://rometools.github.io/rome-mano/index.html}ROME Mano}}|A servlet pipeline framework for RSS and Atom feeds.| |
*----+--+--+
|{{{http://rometools.github.io/rome-opml/index.html}OPML for ROME}}|Outline Processor Markup Language (OPML) parser and tools.| |
*----+--+--+
*Further information
* {{{./ROMEReleases/index.html}ROME Releases (rome)}}
* Working with ROME
* {{{./WhatPartOfTheAPIYouShouldBeUsing.html}What part of the API you should be using (rome)}}
* {{{./TutorialsAndArticles.html}Tutorials and Articles (rome)}}
* Articles about ROME
* {{{./WhyThisProject.html}Project Motivation}} \- why we started ROME
* {{{./RomeAPIFAQ.html}API FAQ}}, why things are like they are
* {{{./WhatSWrongWithOtherExistingRSSParsingLibraries.html}Evaluation of existing RSS parsing libraries}}
* Inside ROME, How Things Work
* {{{./HowRomeWorks/index.html}How ROME Works}}, Understanding ROME, a detailed overview by Dave Johnson (This doc is based on ROME v0.4)
* {{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEPluginsMechanism.html}ROME Plugins Mechanism}},
bootstrap, adding and changing parsers, generators, converters and modules
* {{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html}Feeds Date Elements}},
how Date data is mapped to SyndFeed and SyndEntry
* {{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.html}Feed and Entry URI Mapping}},
how SyndFeed and SyndEntry 'uri' properties map to concrete feed elements
* {{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.html}XML Charset Encoding Detection}},
how ROME helps getting the right charset encoding
* {{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialDefiningACustomModuleBeanParserAndGenerator.html}Creating a custom Module}},
creating all necessary pieces, bean, parser and generator
* {{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/TheCopyFromInterface.html}The CopyFrom interface (rome)}}
* {{{./RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/UnderstandingRssAndAtOMUtilitiEsROMEBeanUtilities.html}ROME bean utilities, equals, toString and cloning}}
* {{{./RssAndAtOMUtiliEsROMEV0.7DateAndTimeParsing.html}Customizing Date and time parsing}} in the rome.properties file
* {{{./ROMEAndMaven2.html}Using ROME from Maven2}}
* {{{./ROMEAndOSGI.html}Using ROME with OSGi}}
* {{{./PreservingWireFeeds.html}Preserving Wire Feeds to obtain access to Atom/RSS specific fields}}
* ROME development
* {{{./HowToBuildRome.html}How to build ROME}} (ROME uses {{{http://maven.apache.org/}Maven}})
* {{{./ChangeLog.html}Changes Log}}, what and when
* {{{./ROMEDevelopmentProcess.html}ROME Development Process (rome)}}
* {{{./ROMEDevelopmentProposals/index.html}ROME Development Proposals (rome)}} \- proposals for new ROME features and releases
[]
 

0
src/site/resources/.nojekyll Normal file
View file

BIN
src/site/resources/HowRomeWorks/HowRomeWorks.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 66 KiB

275
src/site/resources/ROMEDevelopmentProposals/rome2proto.zip Normal file
View file

@ -0,0 +1,275 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Java.net &mdash; 404 - Not Found</title>
<link href="http://asset-3.java.net/stylesheets/print_packaged.css?20110729.62b47ea" media="print" rel="stylesheet" type="text/css" />
<script src="http://asset-1.java.net/javascripts/head_packaged.js?20110729.62b47ea" type="text/javascript"></script>
<script type="text/javascript" src="http://w.sharethis.com/button/buttons.js"></script>
<script type="text/javascript">
stLight.options({
publisher:'bcd30425-1749-43d6-a311-18a82f89771a'
});
</script>
<script type="text/javascript">
//<![CDATA[
var page={};
//]]>
</script>
<script type="text/javascript" charset="utf-8">
function debug(m){}
</script>
<link href="http://asset-2.java.net/theme/stylesheets/java_net.css?20110729.62b47ea" media="screen" rel="stylesheet" type="text/css" />
<link href="http://asset-1.java.net/theme/stylesheets/layout.css?20110729.62b47ea" media="screen" rel="stylesheet" type="text/css" />
<!--[if IE]><style type="text/css" media="all">@import "/theme/stylesheets/ie.css";</style><![endif]-->
<!--[if lte IE 6]><style type="text/css" media="all">@import "/theme/stylesheets/ie6.css";</style><![endif]-->
<!--[if IE 7]><style type="text/css" media="all">@import "/theme/stylesheets/ie7.css";</style><![endif]-->
<!--[if IE 8]><style type="text/css" media="all">@import "/theme/stylesheets/ie8.css";</style><![endif]-->
<meta name="keywords" content="" />
</head>
<body class="front not-logged-in article-type-page one-sidebar">
<div id="container">
<div id="skip-nav" class="element-invisible">
<!-- To adjust the display of the skip link see the Advanced theme settings
(General settings), and never use display:none! -->
<a href="#main-content">Skip to main content</a>
</div>
<div id="leaderboard">
<div id="block-block-31" class="block">
<div class="block-inner">
<div class="content">
<a href="/people/new">Create Account</a>
<span class="separator"></span>
<a href="/people/login" rel="nofollow">Login</a>
<span class="separator"></span>
<a href="/projects/help/pages/Home" target="_blank">Help</a>
</div>
</div>
</div>
</div>
<div id="header" class="clearfix">
<div id="branding">
<div class="logo-site-name">
<strong>
<span id="logo">
<a href="http://www.java.net/" rel="home" class="active">
<img alt="java.net - Go to Homepage" border="0" class="logo-link" src="http://asset-0.java.net/theme/images/logo.png?20110729.62b47ea" title="Java.net - Go to the Homepage" />
</a>
</span>
</strong>
</div>
<div id="site-slogan">The Source for Java Technology Collaboration</div>
</div>
<div id="search-box" class="hide-label">
<form action="http://www.java.net/search/node" method="post" id="search-theme-form">
<div id="search">
<input type="hidden" value="search_form" id="edit-search-form" name="form_id" />
<div style="margin-left: -10px;" class="checks">
<span><input type="checkbox" name="type[forum]" id="edit-forums" value="forum" /> Forums</span>
<span><input type="checkbox" name="type[blog]" id="edit-blogs" value="blog" /> Blogs</span>
<span><input type="checkbox" name="projects" id="edit-projects" value="project" /> Projects</span>
<span><input type="checkbox" name="people" id="edit-people" value="people" /> People</span>
</div>
<input type="text" class="form-text" id="edit-search-theme-form-1" value="Search All" size="15" onclick="this.value = ''" onblur="if (!this.value) this.value = ''" name="keys" />
<input type="submit" value="" name="op" title="Search" class="form-submit" alt="Search" />
</div>
</form>
</div>
</div>
<div id="primary" class="nav">
<div id="primary-inner">
<h2 class="element-invisible">Main Menu</h2>
<ul class="primary-links clearfix">
<li class=""><a href="http://www.java.net/" title="Return to the java.net homepage" class="active">Home</a></li>
<li class=""><a href="http://www.java.net/projects" title="View the projects hosted on java.net">Projects</a></li>
<li class=""><a href="http://www.java.net/forums" title="Participate in the java.net forums">Forums</a></li>
<li class=""><a href="/people" title="View all the people involved with java.net">People</a></li>
<li class=""><a href="http://www.java.net/jugs/java-user-groups" title="Get involved in your local Java User Group (JUG)">Java User Groups</a></li>
</ul>
</div>
</div>
<div id="columns">
<div class="columns-inner clearfix">
<div id="content-column">
<div class="content-inner">
<div id="navig-breadcrumbs">
<a href="/">java.net</a><span>></span>
</div>
<div id="block-quicktabs-2" class="block">
<div class="block-inner">
<div class="content">
<!-- BEGIN CONTENT AREA -->
<div class="contentPadding">
<h2 class="pageTitle">Not Found</h2>
<!-- This file lives in public/404.html -->
<div style="padding: 10px 0 10px 0;">
The page you were looking for doesn't exist.<br/>
You may have mistyped the address or the page may have moved.
</div>
<a href="#" onclick="history.back(); return false;"><span class="bullet">&laquo;</span>&nbsp;back</a>
&nbsp;|&nbsp;
<a href="/">home&nbsp;<span class="bullet">&raquo;</span></a>
</div>
<!--END CONTENT AREA-->
</div>
</div>
</div>
</div>
</div>
<div id="sidebar-first" class="sidebar">
<div id="block-menu-menu-get-involved" class="block">
<div class="block-inner">
<h2>Get Involved</h2>
<div class="content">
<ul class="menu">
<li class="leaf">
<a href="http://about.java.net/" title="About Java.net">About Java.net</a>
</li>
<li class="leaf">
<a href="http://www.java.net/request-project" title="Create a Project">Create a Project</a>
</li>
<li class="leaf">
<a href="http://www.java.net/enhancements" title="">Java.net Enhancements</a>
</li>
</ul>
</div>
</div>
</div>
<div id="block-menu-menu-get-informed" class="block">
<div class="block-inner">
<h2>Get Informed</h2>
<div class="content">
<ul class="menu">
<li class="leaf">
<a href="http://www.java.net/articles" title="">Articles</a>
</li>
<li class="leaf">
<a href="http://www.java.net/blogfront" title="">Blogs</a>
</li>
<li class="leaf">
<a href="http://www.java.net/events" title="">Events</a>
</li>
<li class="leaf">
<a href="http://www.java.net/today/archive" title="Archive">java.net Archives</a>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
<div id="tertiary-content">
<div id="block-menu-menu-footer-menu" class="block">
<div class="block-inner">
<div class="content">
<ul class="menu">
<li class="leaf first">
<a href="http://www.java.net/contact" title="">Feedback</a>
</li>
<li class="leaf">
<a href="http://www.java.net/javanet-faq" title="">FAQ</a>
</li>
<li class="leaf">
<a href="http://www.java.net/javanet-web-site-terms-use" title="">Terms of Use</a>
</li>
<li class="leaf">
<a href="http://www.oracle.com/us/legal/privacy/index.html" title="">Privacy</a>
</li>
<li class="leaf last">
<a href="http://www.oracle.com/us/legal/third-party-trademarks/index.html" title="">Trademarks</a>
</li>
</ul>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-region">
<div class="block">
<div class="block-inner">
<div class="content">
<div style="width: 59%; float: left;">
<p>
Your use of this web site or any of its content or software indicates
your agreement to be bound by these
<a href="http://www.java.net/javanet-web-site-terms-use">Terms of Participation</a>.
</p>
<p>
Copyright © 2011, Oracle and/or its affiliates. All rights reserved.
Oracle and Java are registered trademarks of Oracle and/or its affiliates.
Other names may be trademarks of their respective owners.
</p>
<p>(<a href="/projects/help/pages/ReleaseNotes">revision 20110729.62b47ea</a>)</p>
</div>
<div style="width: 310px; float: right; text-align: right; margin-right: 10px">
<div style="float: right;">
<a href="http://www.oracle.com" title="Oracle"><img alt="" src="http://asset-2.java.net/theme/images/oracle.png?20110729.62b47ea" /></a>
<a href="http://kenai.com" title="Kenai.com"><img alt="" src="http://asset-2.java.net/theme/images/kenai.png?20110729.62b47ea" /></a>
<a href="http://www.cognisync.com" title="Cognisync"><img alt="" src="http://asset-0.java.net/theme/images/cognisync.png?20110729.62b47ea" /></a>
<br />
<div class="powered-by">
Powered by Oracle, Project Kenai and Cognisync
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<!-- popups that are anchored to specific elements -->
<div class="popupMenuShadow" id="contextMenuShadow"></div>
<div class="popupMenuContainer" id="contextMenu">
<div class="popupMenu inline">
<div class="upArrow"></div>
<div class="header"></div>
<div class="contextMenuBody" id="contextMenuBody">&nbsp;</div>
</div>
</div>
<!-- large content loaded via ajax. Faded but not modal. -->
<div class="jqmWindow" id="jqm_large_overlay">
<div class="jqmHeader">
<div class="jqmTitle">&nbsp;</div>
<img alt="Close" class="jqmClose" src="http://asset-2.java.net/images/close.gif?20110729.62b47ea" />
</div>
<div class="jqmTarget">
<img alt="loading" src="http://asset-2.java.net/images/activity.gif?20110729.62b47ea" />
</div>
<div class="jqmFooter">
<div class="jqmClose functionButtonContainer"><button class="functionButton" title="Done"> Done </button></div>
</div>
</div>
<!-- confirmation dialogs with buttons. Faded and modal. -->
<div class="jqmWindow" id="jqm_dialog">
<div class="jqmHeader">
<div class="jqmTitle">Please Confirm</div>
<img alt="Close" class="jqmClose" src="http://asset-2.java.net/images/close.gif?20110729.62b47ea" />
</div>
<div class="jqmTarget">&nbsp;</div>
<div class="jqmFooter">
<div class="jqmClose functionButtonContainer"><button class="functionButton" id="jq_no_button" title="No" onclick="Modal.no()"> No </button></div>
<div class="jqmClose functionButtonContainer"><button class="functionButton" id="jq_yes_button" title="Yes" onclick="Modal.yes();"> Yes </button></div>
</div>
</div>
<div id="jq-ui-autocomplete-parent"></div>
</body>
<script src="http://asset-0.java.net/javascripts/body_packaged.js?20110729.62b47ea" type="text/javascript"></script>
<script src="http://asset-3.java.net/theme/javascript/java_custom.js?20110729.62b47ea" type="text/javascript"></script>
</html>

275
src/site/resources/ROMEDevelopmentProposals/rome2proto2.zip Normal file
View file

@ -0,0 +1,275 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Java.net &mdash; 404 - Not Found</title>
<link href="http://asset-3.java.net/stylesheets/print_packaged.css?20110729.62b47ea" media="print" rel="stylesheet" type="text/css" />
<script src="http://asset-1.java.net/javascripts/head_packaged.js?20110729.62b47ea" type="text/javascript"></script>
<script type="text/javascript" src="http://w.sharethis.com/button/buttons.js"></script>
<script type="text/javascript">
stLight.options({
publisher:'bcd30425-1749-43d6-a311-18a82f89771a'
});
</script>
<script type="text/javascript">
//<![CDATA[
var page={};
//]]>
</script>
<script type="text/javascript" charset="utf-8">
function debug(m){}
</script>
<link href="http://asset-2.java.net/theme/stylesheets/java_net.css?20110729.62b47ea" media="screen" rel="stylesheet" type="text/css" />
<link href="http://asset-1.java.net/theme/stylesheets/layout.css?20110729.62b47ea" media="screen" rel="stylesheet" type="text/css" />
<!--[if IE]><style type="text/css" media="all">@import "/theme/stylesheets/ie.css";</style><![endif]-->
<!--[if lte IE 6]><style type="text/css" media="all">@import "/theme/stylesheets/ie6.css";</style><![endif]-->
<!--[if IE 7]><style type="text/css" media="all">@import "/theme/stylesheets/ie7.css";</style><![endif]-->
<!--[if IE 8]><style type="text/css" media="all">@import "/theme/stylesheets/ie8.css";</style><![endif]-->
<meta name="keywords" content="" />
</head>
<body class="front not-logged-in article-type-page one-sidebar">
<div id="container">
<div id="skip-nav" class="element-invisible">
<!-- To adjust the display of the skip link see the Advanced theme settings
(General settings), and never use display:none! -->
<a href="#main-content">Skip to main content</a>
</div>
<div id="leaderboard">
<div id="block-block-31" class="block">
<div class="block-inner">
<div class="content">
<a href="/people/new">Create Account</a>
<span class="separator"></span>
<a href="/people/login" rel="nofollow">Login</a>
<span class="separator"></span>
<a href="/projects/help/pages/Home" target="_blank">Help</a>
</div>
</div>
</div>
</div>
<div id="header" class="clearfix">
<div id="branding">
<div class="logo-site-name">
<strong>
<span id="logo">
<a href="http://www.java.net/" rel="home" class="active">
<img alt="java.net - Go to Homepage" border="0" class="logo-link" src="http://asset-0.java.net/theme/images/logo.png?20110729.62b47ea" title="Java.net - Go to the Homepage" />
</a>
</span>
</strong>
</div>
<div id="site-slogan">The Source for Java Technology Collaboration</div>
</div>
<div id="search-box" class="hide-label">
<form action="http://www.java.net/search/node" method="post" id="search-theme-form">
<div id="search">
<input type="hidden" value="search_form" id="edit-search-form" name="form_id" />
<div style="margin-left: -10px;" class="checks">
<span><input type="checkbox" name="type[forum]" id="edit-forums" value="forum" /> Forums</span>
<span><input type="checkbox" name="type[blog]" id="edit-blogs" value="blog" /> Blogs</span>
<span><input type="checkbox" name="projects" id="edit-projects" value="project" /> Projects</span>
<span><input type="checkbox" name="people" id="edit-people" value="people" /> People</span>
</div>
<input type="text" class="form-text" id="edit-search-theme-form-1" value="Search All" size="15" onclick="this.value = ''" onblur="if (!this.value) this.value = ''" name="keys" />
<input type="submit" value="" name="op" title="Search" class="form-submit" alt="Search" />
</div>
</form>
</div>
</div>
<div id="primary" class="nav">
<div id="primary-inner">
<h2 class="element-invisible">Main Menu</h2>
<ul class="primary-links clearfix">
<li class=""><a href="http://www.java.net/" title="Return to the java.net homepage" class="active">Home</a></li>
<li class=""><a href="http://www.java.net/projects" title="View the projects hosted on java.net">Projects</a></li>
<li class=""><a href="http://www.java.net/forums" title="Participate in the java.net forums">Forums</a></li>
<li class=""><a href="/people" title="View all the people involved with java.net">People</a></li>
<li class=""><a href="http://www.java.net/jugs/java-user-groups" title="Get involved in your local Java User Group (JUG)">Java User Groups</a></li>
</ul>
</div>
</div>
<div id="columns">
<div class="columns-inner clearfix">
<div id="content-column">
<div class="content-inner">
<div id="navig-breadcrumbs">
<a href="/">java.net</a><span>></span>
</div>
<div id="block-quicktabs-2" class="block">
<div class="block-inner">
<div class="content">
<!-- BEGIN CONTENT AREA -->
<div class="contentPadding">
<h2 class="pageTitle">Not Found</h2>
<!-- This file lives in public/404.html -->
<div style="padding: 10px 0 10px 0;">
The page you were looking for doesn't exist.<br/>
You may have mistyped the address or the page may have moved.
</div>
<a href="#" onclick="history.back(); return false;"><span class="bullet">&laquo;</span>&nbsp;back</a>
&nbsp;|&nbsp;
<a href="/">home&nbsp;<span class="bullet">&raquo;</span></a>
</div>
<!--END CONTENT AREA-->
</div>
</div>
</div>
</div>
</div>
<div id="sidebar-first" class="sidebar">
<div id="block-menu-menu-get-involved" class="block">
<div class="block-inner">
<h2>Get Involved</h2>
<div class="content">
<ul class="menu">
<li class="leaf">
<a href="http://about.java.net/" title="About Java.net">About Java.net</a>
</li>
<li class="leaf">
<a href="http://www.java.net/request-project" title="Create a Project">Create a Project</a>
</li>
<li class="leaf">
<a href="http://www.java.net/enhancements" title="">Java.net Enhancements</a>
</li>
</ul>
</div>
</div>
</div>
<div id="block-menu-menu-get-informed" class="block">
<div class="block-inner">
<h2>Get Informed</h2>
<div class="content">
<ul class="menu">
<li class="leaf">
<a href="http://www.java.net/articles" title="">Articles</a>
</li>
<li class="leaf">
<a href="http://www.java.net/blogfront" title="">Blogs</a>
</li>
<li class="leaf">
<a href="http://www.java.net/events" title="">Events</a>
</li>
<li class="leaf">
<a href="http://www.java.net/today/archive" title="Archive">java.net Archives</a>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
<div id="tertiary-content">
<div id="block-menu-menu-footer-menu" class="block">
<div class="block-inner">
<div class="content">
<ul class="menu">
<li class="leaf first">
<a href="http://www.java.net/contact" title="">Feedback</a>
</li>
<li class="leaf">
<a href="http://www.java.net/javanet-faq" title="">FAQ</a>
</li>
<li class="leaf">
<a href="http://www.java.net/javanet-web-site-terms-use" title="">Terms of Use</a>
</li>
<li class="leaf">
<a href="http://www.oracle.com/us/legal/privacy/index.html" title="">Privacy</a>
</li>
<li class="leaf last">
<a href="http://www.oracle.com/us/legal/third-party-trademarks/index.html" title="">Trademarks</a>
</li>
</ul>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-region">
<div class="block">
<div class="block-inner">
<div class="content">
<div style="width: 59%; float: left;">
<p>
Your use of this web site or any of its content or software indicates
your agreement to be bound by these
<a href="http://www.java.net/javanet-web-site-terms-use">Terms of Participation</a>.
</p>
<p>
Copyright © 2011, Oracle and/or its affiliates. All rights reserved.
Oracle and Java are registered trademarks of Oracle and/or its affiliates.
Other names may be trademarks of their respective owners.
</p>
<p>(<a href="/projects/help/pages/ReleaseNotes">revision 20110729.62b47ea</a>)</p>
</div>
<div style="width: 310px; float: right; text-align: right; margin-right: 10px">
<div style="float: right;">
<a href="http://www.oracle.com" title="Oracle"><img alt="" src="http://asset-2.java.net/theme/images/oracle.png?20110729.62b47ea" /></a>
<a href="http://kenai.com" title="Kenai.com"><img alt="" src="http://asset-2.java.net/theme/images/kenai.png?20110729.62b47ea" /></a>
<a href="http://www.cognisync.com" title="Cognisync"><img alt="" src="http://asset-0.java.net/theme/images/cognisync.png?20110729.62b47ea" /></a>
<br />
<div class="powered-by">
Powered by Oracle, Project Kenai and Cognisync
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<!-- popups that are anchored to specific elements -->
<div class="popupMenuShadow" id="contextMenuShadow"></div>
<div class="popupMenuContainer" id="contextMenu">
<div class="popupMenu inline">
<div class="upArrow"></div>
<div class="header"></div>
<div class="contextMenuBody" id="contextMenuBody">&nbsp;</div>
</div>
</div>
<!-- large content loaded via ajax. Faded but not modal. -->
<div class="jqmWindow" id="jqm_large_overlay">
<div class="jqmHeader">
<div class="jqmTitle">&nbsp;</div>
<img alt="Close" class="jqmClose" src="http://asset-2.java.net/images/close.gif?20110729.62b47ea" />
</div>
<div class="jqmTarget">
<img alt="loading" src="http://asset-2.java.net/images/activity.gif?20110729.62b47ea" />
</div>
<div class="jqmFooter">
<div class="jqmClose functionButtonContainer"><button class="functionButton" title="Done"> Done </button></div>
</div>
</div>
<!-- confirmation dialogs with buttons. Faded and modal. -->
<div class="jqmWindow" id="jqm_dialog">
<div class="jqmHeader">
<div class="jqmTitle">Please Confirm</div>
<img alt="Close" class="jqmClose" src="http://asset-2.java.net/images/close.gif?20110729.62b47ea" />
</div>
<div class="jqmTarget">&nbsp;</div>
<div class="jqmFooter">
<div class="jqmClose functionButtonContainer"><button class="functionButton" id="jq_no_button" title="No" onclick="Modal.no()"> No </button></div>
<div class="jqmClose functionButtonContainer"><button class="functionButton" id="jq_yes_button" title="Yes" onclick="Modal.yes();"> Yes </button></div>
</div>
</div>
<div id="jq-ui-autocomplete-parent"></div>
</body>
<script src="http://asset-0.java.net/javascripts/body_packaged.js?20110729.62b47ea" type="text/javascript"></script>
<script src="http://asset-3.java.net/theme/javascript/java_custom.js?20110729.62b47ea" type="text/javascript"></script>
</html>

BIN
src/site/resources/ROMEReleases/ROME0.1Beta/rome-0.1-src.tar.gz Normal file
View file

Binary file not shown.

BIN
src/site/resources/ROMEReleases/ROME0.1Beta/rome-0.1-src.zip Normal file
View file

Binary file not shown.

BIN
src/site/resources/ROMEReleases/ROME0.1Beta/rome-0.1.tar.gz Normal file
View file

Binary file not shown.

BIN
src/site/resources/ROMEReleases/ROME0.1Beta/rome-0.1.zip Normal file
View file

Binary file not shown.

BIN
src/site/resources/ROMEReleases/ROME0.1Beta/rome-samples-0.1-src.tar.gz Normal file
View file

Binary file not shown.

BIN
src/site/resources/ROMEReleases/ROME0.1Beta/rome-samples-0.1-src.zip Normal file
View file

Binary file not shown.

BIN
src/site/resources/ROMEReleases/ROME0.1Beta/rome-samples-0.1.tar.gz Normal file
View file

Binary file not shown.

BIN
src/site/resources/ROMEReleases/ROME0.1Beta/rome-samples-0.1.zip Normal file
View file

Binary file not shown.

BIN
src/site/resources/ROMEReleases/ROME0.2Beta/rome-0.2-src.tar.gz Normal file
View file

Binary file not shown.

BIN
src/site/resources/ROMEReleases/ROME0.2Beta/rome-0.2-src.zip Normal file
View file

Binary file not shown.

BIN
src/site/resources/ROMEReleases/ROME0.2Beta/rome-0.2.tar.gz Normal file
View file

Binary file not shown.

BIN
src/site/resources/ROMEReleases/ROME0.2Beta/rome-0.2.zip Normal file
View file

Binary file not shown.

BIN
src/site/resources/ROMEReleases/ROME0.2Beta/rome-samples-0.2-src.tar.gz Normal file
View file

Binary file not shown.

BIN
src/site/resources/ROMEReleases/ROME0.2Beta/rome-samples-0.2-src.zip Normal file
View file

Binary file not shown.

BIN
src/site/resources/ROMEReleases/ROME0.2Beta/rome-samples-0.2.tar.gz Normal file
View file

Binary file not shown.

BIN
src/site/resources/ROMEReleases/ROME0.2Beta/rome-samples-0.2.zip Normal file
View file

Binary file not shown.

BIN
src/site/resources/ROMEReleases/ROME0.3Beta/rome-0.3-src.tar.gz Normal file
View file

Binary file not shown.

BIN
src/site/resources/ROMEReleases/ROME0.3Beta/rome-0.3-src.zip Normal file
View file

Binary file not shown.

Some files were not shown because too many files have changed in this diff Show more