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

merged site, maven site config from test repo and some urls fixed

Browse source
This commit is contained in:
Martin Kurz 2013-09-25 22:00:14 +02:00
parent f0c8f60c9e
commit e6bc803b0c
123 changed files with 12578 additions and 16 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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://imk.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
underlying format.
</description>
<url>https://rome.dev.java.net/</url>
<url>https://github.com/rometools/rome/</url>
<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>
<ciManagement>
<notifiers>
@ -32,15 +32,9 @@
<mailingLists>
<mailingList>
<name>dev@rome.dev.java.net</name>
<subscribe>
https://rome.dev.java.net/servlets/ProjectMailingListList
</subscribe>
<unsubscribe>
https://rome.dev.java.net/servlets/ProjectMailingListList
</unsubscribe>
<archive>
https://rome.dev.java.net/servlets/SummarizeList?listName=dev
</archive>
<subscribe>https://rome.dev.java.net/servlets/ProjectMailingListList</subscribe>
<unsubscribe>https://rome.dev.java.net/servlets/ProjectMailingListList</unsubscribe>
<archive>https://rome.dev.java.net/servlets/SummarizeList?listName=dev</archive>
</mailingList>
</mailingLists>
<developers>
@ -66,9 +60,9 @@
</developer>
</developers>
<scm>
<connection>scm:svn:https://rometools.jira.com/svn/ROME/trunk</connection>
<developerConnection>scm:svn:https://rometools.jira.com/svn/ROME/trunk</developerConnection>
<url>https://rometools.jira.com/source/browse/ROME</url>
<connection>scm:git:git@github.com:rometools/rome.git</connection>
<developerConnection>scm:git:git@github.com:rometools/rome.git</developerConnection>
<url>https://github.com/rometools/rome</url>
</scm>
<licenses>
<license>
@ -123,11 +117,42 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
<version>2.2</version>
<version>2.6</version>
<configuration>
<encoding>${project.build.sourceEncoding}</encoding>
</configuration>
</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:imk/rome.git</pubScmUrl>
<content>${project.build.directory}/site</content>
</configuration>
</plugin>
</plugins>
</build>
<profiles>
@ -197,5 +222,33 @@
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</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>

5
src/site/markdown/fetcher/BuildingTheRomeFetcher.md Normal file
View file

@ -0,0 +1,5 @@
# Building the Rome Fetcher
The Rome Fetcher can build using Maven 2.

109
src/site/markdown/fetcher/ChangeLog.md Normal file
View file

@ -0,0 +1,109 @@
# Change Log
## Prior to first release (on the way to v0.3)
1. Updated to handle removal of IO methods using byte streams
Byte Stream IO was removed from Rome itself. The Rome Fetcher is now updated to support this
1. Add FeedFetcherI interface and FeedFetcherFactory class
There is now a FeedFetcherI interface, which FeedFetcher implements. Use FeedFetcherFactory to create instances of FeedFetcher (as suggested by Joseph Ottinger) (FeedFetcherFactory was later removed)
1. Event Support Added to FeedFetcherI
The FeedFetcherI interface now supports feed polled, feed retrieved and feed unchanged events
1. Samples added
Samples are now included with the Rome Fetcher
1. Unit Tests Added
JUnit based tests which invoke the Rome Fetcher against an embedded Jetty webserver are now included
1. Bug fixes in the FeedFetcher event model
The JUnit test suite uncovered some bugs in the event model used by the FeedFetcher. These bugs are now fixed.
1. Refactored the SyndFeedInfo class
SyndFeedInfo now extends ObjectBean
1. Removed FeedFetcherFactory
The benefit of the FeedFetcherFactory was arguable. Now the client code will need to manage the creation of specific implementations of the FeedFetcher
## Prior to second release (on the way to v0.4)
1. Refectored to match Rome naming standards
FeedFetcherI renamed to FeedFetcher
#. New FeedFetcher Implementation
HttpClientFeedFetcher uses the Apache Commons HTTP Client
1. Abstract test classes excluded in project.xml
Tests now run correctly under Maven
1. Added GZip support to HttpClientFeedFetcher
HttpClientFeedFetcher now supports GZip compression. Tests have been added.
## Prior to third release (on the way to v0.5)
1. SyndFeedInfo implements Serializable
SyndFeedInfo implements Serializable to make it easier to store
1. Support for rfc3229 delta encoding
The Fetcher now supports rfc3229 delta encoding. See [http://www.ietf.org/rfc/rfc3229.txt](http://www.ietf.org/rfc/rfc3229.txt) and [http://bobwyman.pubsub.com/main/2004/09/using\_rfc3229\_w.html](http://bobwyman.pubsub.com/main/2004/09/using_rfc3229_w.html). Note that this is support is experimental and disabled by default
## Prior to 0.6
1. Feed passed to FetcherEvents
When a feed is retrieved it is now passed to the Fetcher Event. This makes it easier to code applications using an event oriented style.
## Prior to 0.7
1. Fix for URL Connection leak
In some circumstances URLConnection objects were not closed. This could cause problems in long\-running application.
## 0.8 was never released
## Prior to 0.9
1. Fix for potential synchronization issue
There was the possibility of synchronization issues in the FeedFetcher. Fixed, thanks to suggestions from Javier Kohen.
1. New LinkedHashMapFeedInfoCache FeedFetcherCache implementation
The new LinkedHashMapFeedInfoCache has the advantage that it will not grow unbound
## Prior to 1.0RC2
1. BeanInfo class added for AbstractFeedFetcher
com.sun.syndication.fetcher.impl.AbstractFeedFetcherBeanInfo was created to allow introspection to correctly find the events
1. Callback to allow access to HttpClient HttpMethod object
Add a HttpClientMethodCallbackIntf to allow the calling code to modify the HttpClient HttpMethod used to make the request (eg, add additinal headers, etc.) Also fixes a reported bug where the user agent wasn't being set properly
1. Support for clearing cache
See [http://java.net/jira/browse/ROME\-119](http://java.net/jira/browse/ROME-119) for details
## Prior to 1.0
1. Support for preserving wire feed data.
The fetcher now has a setPreserveWireFeed() method which will setup ROME to preserve WireFeed data. See [PreservingWireFeeds](../rome/PreservingWireFeeds.html) for further information.

5
src/site/markdown/fetcher/Dependencies/HttpClientFeedFetcher.md Normal file
View file

@ -0,0 +1,5 @@
# HttpClientFeedFetcher
An implementation of the `FeedFetcher` which uses the Jakarta HTTP Client. This HTTP client has many benefits over the standard Java implementation.

39
src/site/markdown/fetcher/Dependencies/index.md Normal file
View file

@ -0,0 +1,39 @@
# Dependencies
The Rome Fetcher aims to introduce the absolute minimum number of extra dependencies. Currently (30\-June\-2004) no extra dependencies over those required by Rome are required to use the fetcher.
The current dependencies required to use the Rome Fetcher are:
* JDK 1.4\+
* Current version of Rome
* JDom v 1.0
To build the Rome Fetcher the [Jakarta HTTP Client](http://jakarta.apache.org/commons/httpclient/) is required.
If the [HttpClientFeedFetcher.html](HttpClientFeedFetcher.html) fetcher implementation is used then the Jakarta HTTP Client and Jakarta Commons Logging is required.
To build and run the unit tests for the Rome Fetcher the following additional dependencies are required:
* servletapi version 2.3
* jetty 4.2.12
Note that Maven will automatically download the correct versions of all dependancies.

35
src/site/markdown/fetcher/KnownIssues.md Normal file
View file

@ -0,0 +1,35 @@
# Known Issues
## Version 0.3
* The Maven build does not run the jetty tests because of a bug in Maven
* Version 0.3 does not have Xerces included in the project.xml (it is required to run the samples). Either get the latest project.xml from CVS, or [patch it yourself](https://rome.dev.java.net/source/browse/rome/subprojects/fetcher/project.xml?r1=1.1&amp;r2=1.2)
* 0.3 had a bug that caused it to overwite system properties.
## Version 0.4
* No known issues (yet!)
## Version 0.5
* When listening to feed events using FetcherListener, there is no way to get to the retrieved content, because it is set after firing the event. \-\- [jawe](http://wiki.java.net/twiki/bin/view/Javawsxml/Jawe)
* When listening to feed events using FetcherListener, the feed URLs returned by the FetcherEvent are prepended with "sun.net.www.protocol.http.HttpURLConnection:" \-\- [jawe](http://wiki.java.net/twiki/bin/view/Javawsxml/Jawe)
## Version 0.7
* HashMapFeedInfoCache doesn't work quite right because URL.hashCode() does hostname resolution and treats virtual hosts with the same IP as equal, so e.g. all RSS feeds from blogspot.com collide in the cache. Also, it's really slow. Fix is to use URL.toExternalForm() as the hash key instead of the URL itself.

43
src/site/markdown/fetcher/Releases/ROMEFetcher0.6.md Normal file
View file

@ -0,0 +1,43 @@
# ROME Fetcher 0.6
## Downloads
## Tutorials
* [../BuildingTheRomeFetcher.html](../BuildingTheRomeFetcher.html)
* [../UsingTheRomeFetcherModuleToRetrieveFeeds.html](../UsingTheRomeFetcherModuleToRetrieveFeeds.html)
* [../SampleProgramsIncluded.html](../SampleProgramsIncluded.html)
## API Docs
* [Fetcher API Docs](https://rome.dev.java.net/apidocs/subprojects/fetcher/0.6/overview-summary.html)
## Todo list
* [../TodoList.html](../TodoList.html)
## Issues
* [../KnownIssues.html](../KnownIssues.html)
## Change Log
* [../ChangeLog.html](../ChangeLog.html)

43
src/site/markdown/fetcher/Releases/ROMEFetcher0.7.md Normal file
View file

@ -0,0 +1,43 @@
# ROME Fetcher 0.7
## Downloads
## Tutorials
* [../BuildingTheRomeFetcher.html](../BuildingTheRomeFetcher.html)
* [../UsingTheRomeFetcherModuleToRetrieveFeeds.html](../UsingTheRomeFetcherModuleToRetrieveFeeds.html)
* [../SampleProgramsIncluded.html](../SampleProgramsIncluded.html)
## API Docs
* [Fetcher API Docs](https://rome.dev.java.net/apidocs/subprojects/fetcher/0.7/overview-summary.html)
## Todo list
* [../TodoList.html](../TodoList.html)
## Issues
* [../KnownIssues.html](../KnownIssues.html)
## Change Log
* [../ChangeLog.html](../ChangeLog.html)

47
src/site/markdown/fetcher/Releases/ROMEFetcher0.9.md Normal file
View file

@ -0,0 +1,47 @@
# ROME Fetcher 0.9
Note that there was no 0.8 Fetcher release
## Downloads
## Tutorials
* [../BuildingTheRomeFetcher.html](../BuildingTheRomeFetcher.html)
* [../UsingTheRomeFetcherModuleToRetrieveFeeds.html](../UsingTheRomeFetcherModuleToRetrieveFeeds.html)
* [../SampleProgramsIncluded.html](../SampleProgramsIncluded.html)
## API Docs
* [Fetcher API Docs](https://rome.dev.java.net/apidocs/subprojects/fetcher/0.9/overview-summary.html)
## Todo list
* [../TodoList.html](../TodoList.html)
## Issues
* [../KnownIssues.html](../KnownIssues.html)
## Change Log
* [../ChangeLog.html](../ChangeLog.html)

43
src/site/markdown/fetcher/Releases/ROMEFetcher1.0.md Normal file
View file

@ -0,0 +1,43 @@
# ROME Fetcher 1.0
## Downloads
## Tutorials
* [../BuildingTheRomeFetcher.html](../BuildingTheRomeFetcher.html)
* [../UsingTheRomeFetcherModuleToRetrieveFeeds.html](../UsingTheRomeFetcherModuleToRetrieveFeeds.html)
* [../SampleProgramsIncluded.html](../SampleProgramsIncluded.html)
## API Docs
* [Fetcher API Docs](https://rome.dev.java.net/apidocs/subprojects/fetcher/1.0/overview-summary.html)
## Todo list
* [../TodoList.html](../TodoList.html)
## Issues
* [../KnownIssues.html](../KnownIssues.html)
## Change Log
* [../ChangeLog.html](../ChangeLog.html)

47
src/site/markdown/fetcher/Releases/ROMEFetcher1.0RC2.md Normal file
View file

@ -0,0 +1,47 @@
# ROME Fetcher 1.0 RC2
Note that there was no 1.0 RC1 Fetcher release
## Downloads
## Tutorials
* [../BuildingTheRomeFetcher.html](../BuildingTheRomeFetcher.html)
* [../UsingTheRomeFetcherModuleToRetrieveFeeds.html](../UsingTheRomeFetcherModuleToRetrieveFeeds.html)
* [../SampleProgramsIncluded.html](../SampleProgramsIncluded.html)
## API Docs
* [Fetcher API Docs](https://rome.dev.java.net/apidocs/subprojects/fetcher/1.0RC2/overview-summary.html)
## Todo list
* [../TodoList.html](../TodoList.html)
## Issues
* [../KnownIssues.html](../KnownIssues.html)
## Change Log
* [../ChangeLog.html](../ChangeLog.html)

47
src/site/markdown/fetcher/Releases/RomeFetcher0.3.md Normal file
View file

@ -0,0 +1,47 @@
# Rome Fetcher 0.3
Rome Fetcher version 0.3 is inital release of the Rome Fetcher. It is released as version 0.3 to synchronize with the version number of the core Rome project release.
## Downloads
## Tutorials
* [../BuildingTheRomeFetcher.html](../BuildingTheRomeFetcher.html)
* [../UsingTheRomeFetcherModuleToRetrieveFeeds.html](../UsingTheRomeFetcherModuleToRetrieveFeeds.html)
* [../SampleProgramsIncluded.html](../SampleProgramsIncluded.html)
## API Docs
* [Fetcher API Docs](https://rome.dev.java.net/apidocs/subprojects/fetcher/0.3/overview-summary.html)
## Todo list
* [../TodoList.html](../TodoList.html)
## Issues
* [../KnownIssues.html](../KnownIssues.html)
## Change Log
* [../ChangeLog.html](../ChangeLog.html)

43
src/site/markdown/fetcher/Releases/RomeFetcher0.4.md Normal file
View file

@ -0,0 +1,43 @@
# Rome Fetcher 0.4
## Downloads
## Tutorials
* [../BuildingTheRomeFetcher.html](../BuildingTheRomeFetcher.html)
* [../UsingTheRomeFetcherModuleToRetrieveFeeds.html](../UsingTheRomeFetcherModuleToRetrieveFeeds.html)
* [../SampleProgramsIncluded.html](../SampleProgramsIncluded.html)
## API Docs
* [Fetcher API Docs](https://rome.dev.java.net/apidocs/subprojects/fetcher/0.4/overview-summary.html)
## Todo list
* [../TodoList.html](../TodoList.html)
## Issues
* [../KnownIssues.html](../KnownIssues.html)
## Change Log
* [../ChangeLog.html](../ChangeLog.html)

47
src/site/markdown/fetcher/Releases/RomeFetcher0.5.md Normal file
View file

@ -0,0 +1,47 @@
# Rome Fetcher 0.5
The ROME Fetcher v 0.6 is now released. This page exists for historical purposes only.
## Downloads
## Tutorials
* [../BuildingTheRomeFetcher.html](../BuildingTheRomeFetcher.html)
* [../UsingTheRomeFetcherModuleToRetrieveFeeds.html](../UsingTheRomeFetcherModuleToRetrieveFeeds.html)
* [../SampleProgramsIncluded.html](../SampleProgramsIncluded.html)
## API Docs
* [Fetcher API Docs](https://rome.dev.java.net/apidocs/subprojects/fetcher/0.5/overview-summary.html)
## Todo list
* [../TodoList.html](../TodoList.html)
## Issues
* [../KnownIssues.html](../KnownIssues.html)
## Change Log
* [../ChangeLog.html](../ChangeLog.html)

1
src/site/markdown/fetcher/Releases/index.md Normal file
View file

@ -0,0 +1 @@
# Releases

17
src/site/markdown/fetcher/SampleProgramsIncluded.md Normal file
View file

@ -0,0 +1,17 @@
# Sample programs included
There are two sample programs included with Rome Fetcher.
[FeedReader](https://rometools.jira.com/source/browse/FETCHER/trunk/src/java/com/sun/syndication/fetcher/samples/FeedReader.java) is a program which demonstrates the use of the Fetcher to retrieve a feed and then to use the conditional get support to retrieve it again only if it has changed. It also shows how to use the event API in the Fetcher. It can be run using the `maven run\-read` target.
[FeedAggregator](https://rometools.jira.com/source/browse/FETCHER/trunk/src/java/com/sun/syndication/fetcher/samples/FeedAggregator.java) is a program which aggregates a number of feeds together into a single feed. It can be run using the `maven run\-aggr` target.
(Note that in verision 0.3 the Maven build does not include Xerces in the classpath \- which is required to use Rome. This is [easy to fix](https://rome.dev.java.net/source/browse/rome/subprojects/fetcher/project.xml?r1=1.1&amp;r2=1.2).)

19
src/site/markdown/fetcher/TodoList.md Normal file
View file

@ -0,0 +1,19 @@
# Todo list
Please discuss items here on the rome dev mailing list
* Automatically update the \-[default User\-Agent version number](https://rometools.jira.com/source/browse/FETCHER/trunk/src/java/com/sun/syndication/fetcher/FeedFetcher.java) via the build\- Done: 23\-June\-2004
* Listener Architecture (for URL changes via 3xx redirection etc) Done: 30\-June\-2004
* [RSS Redirection](http://radio.userland.com/userGuide/reference/howToRedirectRss)
* Unit Tests: smart unit tests along the lines of Mark Pilgrim's tests, in his \-[Python Universal Feed Parser](http://diveintomark.org/projects/feed_parser/). He instantiates a web server to a local directory where the samples live, and then fetches the feeds from the server, which allows him to test in depth the behavior of gzip compression and etags handling.\- Done 30\-June\-2004
* Better character encoding handling \- See [http://diveintomark.org/archives/2004/02/13/xml\-media\-types](http://diveintomark.org/archives/2004/02/13/xml-media-types)
* A caching feed fetcher

42
src/site/markdown/fetcher/UsingTheRomeFetcherModuleToRetrieveFeeds.md Normal file
View file

@ -0,0 +1,42 @@
# Using the Rome Fetcher module to retrieve feeds
The HttpURLFeedFetcher class does the actual HTTP request. It relies on the FeedInfoCacheI interface which stores information about each feed required for conditional gets. Currently there is a single implementation of FeedInfoCacheI supplied: `HashMapFeedInfoCache`.
The basic usage of FeedFetcher is as follows:
```
FeedFetcherCache feedInfoCache = HashMapFeedInfoCache.getInstance();
FeedFetcher feedFetcher = new HttpURLFeedFetcher(feedInfoCache);
SyndFeed feed = feedFetcher.retrieveFeed(new URL("http://blogs.sun.com/roller/rss/pat"));
System.out.println(feed);
```
Any subsequent fetches of [http://blogs.sun.com/roller/rss/pat](http://blogs.sun.com/roller/rss/pat) by any FeedFetcher using feedInfoCache will now only retrieve the feed if it has changed.
FeedFetcher can be used without a cache if required. Simply create it using the zero\-parameter constructor:
```
FeedFetcher feedFetcher = new HttpURLFeedFetcher();
```
A more complete sample (including the use of listener on Fetcher events) [is included in the Rome Fetcher project](https://rometools.jira.com/source/browse/FETCHER/trunk/src/java/com/sun/syndication/fetcher/samples/FeedReader.java)
Note that there has been considerable discussion on the rome\-dev list about the best way to manage the creation of the feed fetcher. Currently the client code needs to be responsible for creating specific implementations of the FeedFetcherI interface.

9
src/site/markdown/fetcher/WishList.md Normal file
View file

@ -0,0 +1,9 @@
# Wish list
* [RSS Autodiscovery](http://diveintomark.org/archives/2002/05/31)
* [Atom Autodiscovery](http://www.intertwingly.net/wiki/pie/PaceAutoDisco)
* Connection timeout and read settings.

78
src/site/markdown/fetcher/index.md Normal file
View file

@ -0,0 +1,78 @@
# Home
# Rome Fetcher
The Rome Fetcher (see modules/fetcher) allows the retrieval of feeds via HTTP. It supports [HTTP conditional gets](http://fishbowl.pastiche.org/2002/10/21/http_conditional_get_for_rss_hackers) (ie: last modified and ETag handling) and GZip encoded feeds. It should enable user to write aggregators that follow the [Atom aggregator behaviour recommendations](http://diveintomark.org/archives/2003/07/21/atom_aggregator_behavior_http_level)
As with the rest of Rome, the Fetcher subproject is ultra\-lean \- it requires [no new dependencies](Dependencies/index.html) over the requirements for Rome.
# Tutorials
* [BuildingTheRomeFetcher.html](BuildingTheRomeFetcher.html)
* [UsingTheRomeFetcherModuleToRetrieveFeeds.html](UsingTheRomeFetcherModuleToRetrieveFeeds.html)
* [SampleProgramsIncluded.html](SampleProgramsIncluded.html)
# Todo list
* [TodoList.html](TodoList.html)
# Wish list
* [WishList.html](WishList.html)
# Issues
* [KnownIssues.html](KnownIssues.html)
# Releases
* [Releases/RomeFetcher0.3.html](Releases/RomeFetcher0.3.html)
* [Releases/RomeFetcher0.4.html](Releases/RomeFetcher0.4.html)
* [Releases/RomeFetcher0.5.html](Releases/RomeFetcher0.5.html)
* [Releases/ROMEFetcher0.6.html](Releases/ROMEFetcher0.6.html)
* [Releases/ROMEFetcher0.7.html](Releases/ROMEFetcher0.7.html)
* [Releases/ROMEFetcher0.9.html](Releases/ROMEFetcher0.9.html)
* [Releases/ROMEFetcher1.0RC2.html](Releases/ROMEFetcher1.0RC2.html)
* [Releases/ROMEFetcher1.0.html](Releases/ROMEFetcher1.0.html)
# Change Log
* [ChangeLog.html](ChangeLog.html)

72
src/site/markdown/incubator/Certiorem.md Normal file
View file

@ -0,0 +1,72 @@
# certiorem
Certiorem is an implementation of the [PubSubHubub ](http://pubsubhubbub.googlecode.com/svn/trunk/pubsubhubbub-core-0.3.html)protocol for ROME.
It is dependent on ROME and ROME\-Fetcher for the base implementations, and will provide standard plugins for Propono to allow for publish eventing, where applicable.
## Primary Components
### Hub Implementation and Scaffolding (Done)
The first part of Certiorem is a basic set of scaffolding classes that can be used to create a PSH notification hub. Initially, this will include a non\-guaranteed delivery hub, with standard implementations suitable for deployment on most JavaEE application servers or Google App Engine. It is intended that there should be at least one simple, drop in WAR file, utilizing JavaEE classes that can work in a default configuration for various standard web containers. Subsequently,  each of the classes in the PSH implementation up through the primary Controller class use constructor\-time composition/configuration so that the user/developer can easily construct a custom configuration of the Hub.
### Client Implementation Integrated with ROME\-Fetcher (Done)
For web\-based applications that use ROME\-Fetcher, an extended push\-notified store wrapper that will update based on callbacks from a Hub of change notifications. This will include a highly configurable callback servlet to write into the Fetcher cache as changes are made. Additionally, the system should support (semi\-)real time notifications of changes in the form of a listener that exectutes in a TBD thread state relative to the callback servlet. This should be packaged as a simple JAR with no more deps than fetcher that defines the callback servlet, and automagically does subscribes where link\=rel appropriate.
### Notification Implementation for Propono based and JAX\-RS based Servers (In Progress)
This should be a simple API call to notify a Hub of changes to topics. Again, this should provide real\-time notifications either synchronously or asynchronously. Importantly for Asynchronous notifications, they should block subsequent change notifications pending a notification to the Hub.
References: 
[https://github.com/nlothian/RTUpdates/blob/master/src/com/nicklothian/pubsubhub/PubSubHubSubscriptionServlet.java](https://github.com/nlothian/RTUpdates/blob/master/src/com/nicklothian/pubsubhub/PubSubHubSubscriptionServlet.java)
[http://grack.com/blog/2009/09/09/parsing\-the\-pubsubhubbub\-notifications/](http://grack.com/blog/2009/09/09/parsing-the-pubsubhubbub-notifications/)
# Notes on the Code
It is still mostly a rough sketch, but the big outlines are there:
There are three main packages: pub, sub and hub.
The pub package is basically just a single utility class for pushing notifications to a hub.
The hub package contains the Hub class. This is a general business controller that is intended to allow you to build a servlet around it with a very, very thin veneer, but you could also use it to drive an XMPP or JMS version too. It is basically built by composition of a number of classes, for which there are some default implementations: A Verifier, which makes the callback to verify new subscriptions, the HubDAO which stores the current subscriptions and subscriber statistics, and a Notifier which actually sends notifications to the subscribers. There are a couple of implementations of each of these (though the JPA HubDAO is still in process). Mostly the implementations for the Verifier and Notifier support threadpooling or no\-threads (for App Engine use).
I have just started sketching out the sub package, but it basically has a "Subscriptions" class that will take in notifications (using the same "thin veneer" pattern that the Hub class uses). It is also constructed with some impls: A SubscriptionDAO that stores you current subscription information, a FeedFetcherCache that holds the received data, and a Requester that makes the subscription requests to hubs.
I am hoping to have a basic end to end example working sometime in the next week or so, but if anyone wants to look over what is there, feel free.

174
src/site/markdown/incubator/CertioremTutorial.md Normal file
View file

@ -0,0 +1,174 @@
# Certiorem Tutorial
Certiorem is a PubSubHubub (PSH) implementation for ROME. It isn't an application, but an API for building each of the three components (Publisher, Subscriber and Hub) into your web apps.
You can see an [example webapp here](https://rometools.jira.com/source/browse/INCUBATOR/trunk/pubsubhubub/webapp).
# Creating a Hub
Hubs take notifications, or "Pings" that tell it the content of a feed has been updated, fetch the feed, then notify each of the subscribers of the change. As you will begin to see, Certiorem is very much about "Composition" of classes. The Hub class is a prime example of this.
Looking at the example webapp we see:
```
@Provides
@Singleton
public Hub buildHub() {
FeedFetcher fetcher = new HttpURLFeedFetcher(new DeltaFeedInfoCache());
    Hub hub = new Hub(new InMemoryHubDAO(), new UnthreadedVerifier(), new UnthreadedNotifier(), fetcher);
    return hub;
}
```
First we construct an instance of FeedFetcher, from the Fetcher subproject. This will be used to fetch feeds from remote hosts. There are a number of implementations for FeedFetcher and FeedInfoCache in the Fetcher project. Please look there for info on what is what.
Next we need a HubDAO implementation. This is a DAO for managing Subscriber and SubscriptionSummary classes. Here we are using an in\-memory DAO, which like the HashMapFeedInfoCache will evaporate if we restart our web application. A JPA implementation for persistence is also available, but incomplete at time of writing.
Next we need two implementations of network client interfaces: a Verifier, and a Notifier. The Verifier calls back to the Subscribers and verifies their subscribe/unsubscribe operations. A Notifier is used to send updates to to the clients. There are two basic implementations of these provided: A ThreadPool\* and Unthreaded\* version of each. The thread pool version uses a ThreadPoolExecutor to run queues of outbound calls. The Unthreaded version of each, makes the network calls in\-line with the request to the hub. These are suitable for environments like Google App Engine where spawning threads from servlets is absolutely verboten.
There are other constructors that contain lists of restrictions for what the hub will support: acceptable topic feeds, ports, protocols, etc.
The hub here is just a business logic class. In order to have a functioning hub, we need a servlet exposing the Hub. In the "web" package, there is an abstract servlet you can use to do just this. In the Guice wired example, we simply create a servlet with an injected Hub implementation.
```
@Singleton
public class HubServlet extends AbstractHubServlet {
@Inject
public HubServlet(final Hub hub){
super(hub);
}
}
//... in the ServerModule...
serve("/hub*").with(HubServlet.class);
```
We can now include a \<link rel\="hub"\> value in our feeds and publish notifications of changes. 
# Publishing Ping Notifications
This is perhaps the easiest thing to do. The Publisher class will take various combinations of URLs and SyndFeeds and send the appropriate notification. If your SyndFeed contains a \<link rel\='sel' /\> and \<link rel\='hub' /\> you can just pass the SyndFeed object. Otherwise, you can use the URL strings where appropriate.
The example couldn't be simpler:
```
Publisher pub = new Publisher();
try {
pub.sendUpdateNotification("http://localhost/webapp/hub", "http://localhost/webapp/research-atom.xml");
} catch (NotificationException ex) {
Logger.getLogger(NotifyTest.class.getName()).log(Level.SEVERE, null, ex);
throw new ServletException(ex);
}
```
Once this notification is sent, the hub will make a request to the feed and notify the clients of new entries.
# Subscribing to Feeds
To set up a feed subscriber, you need to go through a process very much like setting up a Hub. First, create the Subscriptions class by composition:
```
@Provides
@Singleton
public Subscriptions buildSubs(){
    Subscriptions subs = new Subscriptions(new HashMapFeedInfoCache(), new AsyncRequester(),
            "http://localhost/webapp/subscriptions/", new InMemorySubDAO());
    return subs;
}
```
First we need a FeedInfoCache implementation. This will be updated as notifications come in, so in your web app, you want to make sure this is shared with the FeedFetcher implementation you are using to read feeds. Next you need a Requester, this is a network class that makes subscription requests to remote hubs. Next, a URL prefix for where the callbacks will live. This really means the URL to the SubServlet that is resolvable externally. Finally, a DAO for storing and retrieving Subscription objects.
As in the Hub, we need a wrapper servlet to call into the Subscriptions class
```
@Singleton
public class SubServlet extends AbstractSubServlet {
@Inject
public SubServlet(final Subscriptions subscriptions){
super(subscriptions);
}
}
// In the ServerModule...
serve("/subscriptions/*").with(SubServlet.class)
```
Now if we want to subscribe to a feed, we get a reference to the Subscriptions object, and pass in either the SyndFeed (with appropriate rel\="hub" and rel\="self" links) or simply a couple of URLs:
```
 subs.subscribe("http://localhost/webapp/hub", "http://localhost/webapp/research-atom.xml", true, -1, null, new SubscriptionCallback(){
public void onFailure(Exception e) {
e.printStackTrace();
}
public void onSubscribe(Subscription subscribed) {
System.out.println("Subscribed "+subscribed.getId() +" "+subscribed.getSourceUrl());
}
});
```
Here we pass in the URL of the Hub, the URL of the feed, a boolean indicating we want to make the subscription request synchronously, the lease seconds we want to keep the subscription for, a null cryptographic secret, and a Callback invoked when the subscribe request completes.

19
src/site/markdown/incubator/index.md Normal file
View file

@ -0,0 +1,19 @@
# Home
This is the home of the Incubator space.
To help you on your way, we've inserted some of our favourite macros on this home page. As you start creating pages, blogging and commenting you'll see the macros below fill up with all the activity in your space.
[Certiorem.html](Certiorem.html) The Certiorem project – A PubSubHubub implementation for ROME
Navigate space

577
src/site/markdown/mano/index.md Normal file
View file

@ -0,0 +1,577 @@
# Home
# ROME.Mano v0.0 pre\-Alpha
Mano (_to flow_ in Latin) is a pipeline framework for RSS and Atom feeds.
* [The Concept](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#The_Concept)
* [Being More Concrete](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#Being_More_Concrete)
* [What Is in the Box?](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#What_Is_in_the_Box)
* [The FeedHandler Public API](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#The_FeedHandler_Public_API)
* [The Mano Servlet](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#The_Mano_Servlet)
* [The FeedHandler Deployment Descriptor](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#The_FeedHandler_Deployment_Descr)
* [The Handler Toolbox](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#The_Handler_Toolbox)
* [Fetch Handler](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#Fetch_Handler)
* [Convert Handler](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#Convert_Handler)
* [Branding Handler](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#Branding_Handler)
* [File Handler](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#File_Handler)
* [Clone Handler](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#Clone_Handler)
* [Paginate Handler](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#Paginate_Handler)
* [Multi Handler](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#Multi_Handler)
* [Tracking Handler & Servlet](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#Tracking_Handler_Servlet)
* [Echo Handler (alias the Uploader)](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#Echo_Handler_alias_the_Uploader)
* [Null Handler](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#Null_Handler)
* [Sort Handler](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#Sort_Handler)
* [Building ROME.Mano](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#Building_ROME_Mano)
* [Sample ROME.Mano URLs](http://wiki.java.net/bin/view/Javawsxml/RomeMano?skin=print#Sample_ROME_Mano_URLs)
## The Concept
Mano has been modeled after a widely accepted pattern, Java servlet filters.
A request for a feed flows out through a chain of handlers until a feed is synthesized then the feed flows back through the chain in reverse order.
As the request flows out handlers can modify the request, and when the request is flowing back with the feed the same handlers can them modify the feed.
```
|| Mano framework ||
|| ||
|| +\-------\-+ +\-------\-+ ||
feed URL \--> \|\| \| \| \--> ... \--> \| \| \|\|
|| | handler 1 | | handler N | ||
feed <-\- \|\| \| \| <-\- ... <-\- \| \| \|\|
|| +\-------\-+ +\-------\-+ ||
|| ||
```
## Being More Concrete
The Mano framework is a Java Web Application that has a servlet serving feeds.
Upon an HTTP request for a feed a Mano servlet based on the information in the request builds a handler sequence and invokes it, the response is a feed that is returned by the Mano servlet to the requester user\-agent.
A feed reader user\-agent requests a feed to a server running the Mano framework WebApp.
Based on information in the request the Mano servlet determines that the handlers to invoke are the convert and the fetch handlers and creates the corresponding handler chain.
```
public class ManoFeedServlet extends HttpServlet {
protected void doGet(HttpServletRequest req,HttpServletResponse res)
throws ServletException, IOException {
FeedHandlerRequest handlerReq = createRequest(req);
FeedHandlerResponseImpl handlerRes = createResponse(req);
List handlerList = createHandlerList(req);
FeedHandlerChainImpl chain =
new FeedHandlerChainImpl(handlerReq, handlerRes, handlerList);
chain.execute();
...
}
}
```
When flowing out the convert handler does nothing but chaining the request for the next handler (handlers do not know anything about earlier and later handlers in the chain, that is managed by the Mano framework).
```
public class ConvertFeedHandler extends BaseFeedHandler {
public void handle(FeedHandlerRequest handlerRequest,
FeedHandlerResponse handlerResponse, FeedHandlerChain handlerChain)
throws FeedHandlerException, IOException {
handlerChain.chain(handlerRequest, handlerResponse);
...
}
}
```
Then fetch handler receives the request, obtains the feed URL from a request parameter and using ROME Fetcher it fetches the feed. The resulting SyndFeed bean is set into the response by the fetch handler. The fetch handler is the end of the chain, it does not chain any further handlers.
```
public class FetchFeedHandler extends BaseFeedHandler {
public void handle(FeedHandlerRequest handlerRequest,
FeedHandlerResponse handlerResponse, FeedHandlerChain handlerChain)
throws FeedHandlerException, IOException {
String url = handlerRequest.getParameter("fetch.url");
SyndFeed feed = fetcher.retrieveFeed(new URL(url));
handlerResponse.setSyndFeed(feed);
}
}
```
At this point the Mano framework start the flow back of the request and the convert handler will regain control of the invocation, it will obtain the SyndFeed bean from the response and it will set the feed type of the bean to the type indicated in a request parameter.
```
public class ConvertFeedHandler extends BaseFeedHandler {
public void handle(FeedHandlerRequest handlerRequest,
FeedHandlerResponse handlerResponse, FeedHandlerChain handlerChain)
throws FeedHandlerException, IOException {
handlerChain.chain(handlerRequest, handlerResponse);
SyndFeed feed = handlerResponse.getSyndFeed();
String toType = handlerRequest.getParameter("convert.to");
feed.setFeedType(toType);
}
}
```
The handler chain finishes, the control comes back to the Mano servlet, the Mano servlet gets the feed bean from the response (the handler response autoconverts from SyndFeed to WireFeed). The Mano servlet writes the feed bean to the servlet response.
```
public class ManoFeedServlet extends HttpServlet {
protected void doGet(HttpServletRequest req,HttpServletResponse res)
throws ServletException, IOException {
...
chain.execute();
WireFeed feed = handlerRes.getWireFeed();
WireFeedOutput feedOutput = new WireFeedOutput();
feedOutput.output(feed, res.getWriter());
}
}
```
The conversion from the original feed type to the feed type indicated in the convert.to parameter is done automatically by ROME when converting from SyndFeed to WireFeed just by setting the feed type in the SyndFeed bean.
## What Is in the Box?
ROME.Mano includes the handler API, a Mano servlet, a handler manager that uses a handler Deployment Descriptor and a toolbox with handlers (convert, fetch, branding, paginate, multi, clone and file).
### The FeedHandler Public API
* FeedHandler, methods: init(), handle() & destroy().
* FeedHandlerChain, method: chain().
* FeedHandlerConfig, methods: init parameters and context.
* FeedHandlerRequest, methods: to handle parameters, headers, attributes and principal.
* FeedHandlerResponse, methods: to set and retrieve WireFeed bean or SyndFeed bean, to set HTTP status, to set HTTP headers.
* BaseFeedHandler, convenience base class implementation of the FeedHandler.
* FeedHandlerException exception when something goes wrong.
### The Mano Servlet
The Mano Servlet must be mapped to a path ending with '/\*'. The handlers and their invocation order must be indicated in the extra path, handler names must be separated by a '/'.
Parameters in the query\-string are passed to the handlers, by convention the parameters should be namespaced with the name of the target handler. For example, for the **fetch** handler the **url** parameter should be named **fetch.url**.
### The FeedHandler Deployment Descriptor
The handler deployment descriptor, by default at /WEB\-INF/feedhandler.xml defines all the available handlers. A handler manager controls the lifecycle of the handlers behinds the scenes. For example:
```
<feed-handlers>
<handler>
<name>fetch</name>
<class>com.sun.syndication.handler.toolbox.FetchFeedHandler</class>
</handler>
<handler>
<name>convert</name>
<class>com.sun.syndication.handler.toolbox.ConvertFeedHandler</class>
<init-parameter>
<name>to.default</name>
<value>rss_1.0</value>
</init-parameter>
</handler>
...
<feed-handlers>
```
### The Handler Toolbox
A collection of handlers is provided with the Mano framework.
#### Fetch Handler
It fetches a Feed URL.
It fetches the feed URL indicated in the namespaced **url** parameter. It uses ROME Fetcher \=HttpURLFeedFetcher to fetch the feed. This handler stops the handler chain.
#### Convert Handler
It converts a feed to the specified feed type.
After invoking the handler chain for further processing it sets the feed type to the value of the namespaced **to** parameter or to a default feed type if the parameter is not specified.
#### Branding Handler
It brands the description of the entries with the feed image (or the site favicon if there is not feed image) and the title.
#### File Handler
It reads or writes a feed from disk.
If the namespaced **read** parameter is present and there is a file with the value of the parameter (the value of the parameter does not have to be the URL of the feed, it can be any valid file name) the feed is read from the file and the handler stops the chain from continuing further out. If there is not file for the given ID then the handler lets the chain to continue further down.
If the namespaced **write** parameter is present after the filter chain returns the feed is written to a file with the value of the parameter as name.
If both **read** and **write** parameters are specified the handler acts a cache, if the read succeeds then read feed is returned, if the read fails then the chain continues and the obtained feed is written. A subsequent request will return the stored feed.
#### Clone Handler
It does a deep clone of the returned feed and sets the clone in the response.
Because feed beans are passed by reference between handlers, if a handler caches or stores feeds to be served to multiple users, it may be necessary to put a clone handler before it so earlier handlers modifying the feed do not affect the cached/stored feed.
#### Paginate Handler
It paginates the entries of a feed.
The namespaced **offset** (base 0)and **size** parameters indicate the range of entries to return. If **offset** is not present 0 is used. If **size** is not present a default value of 50 is used.
#### Multi Handler
It invokes the handler chain multiple times and consolidates the entries of all invocations into a single feed.
It is useful for merging feeds. For example, fetching N feeds and returning a single feed with all their entries.
The namespaced **param** indicates the name of the multivalue parameter to iterate for the multiple invocations. Each one of the multiple invocations sets the parameter indicated in the **param** parameter to a single value corresponding to the current iteration. For example, the request URL:
**http ://foo.com/mano/feed/multi/fetch?multi.param\=fetch.url&fetch.url\=A&fetch.url\=B&fetch.url\=C**
It will result in 3 forked chain requests each one with a single value for the **fetch.url** parameter.
* fetch.url\=A
* fetch.url\=B
* fetch.url\=C
All the entries for the 3 chain requests will be aggregated in the feed bean returned by the MultiFeedHandler.
If the **param** parameter is multivalue then the Multi handler will iterate over all those parameters. For example if **param** values are **fetch.url** and **file.write**:
**http ://foo.com/mano/feed/multi/fetch?multi.param\=fetch.url&multi.param\=file.write&fetch.url\=A&fetch.url\=B&fetch.url\=C&file.write\=X&file.write\=Y&file.write\=Z**
It will result in 3 forked chain request each one with single values for the **fetch.url** and **file.write** parameters:
* fetch.url\=A&file.write\=X
* fetch.url\=B&file.write\=Y
* fetch.url\=C&file.write\=Z
#### Tracking Handler & Servlet
Together the Tracking handler and servlet enable feed usage tracking, clicked links (feed site and entries) and viewed entries.
The Tracking handler rewriting URLs within the feed to point to the Tracking servlet and adds an image URL (also pointing to the tracking servlet) to the entries descriptions.
The Tracking servlet logs the ID, URL and type of usage (VIEW or CLICK). When a client clicks on a link or displays the description of an entry the Tracking servlet is invoked, it tracks the request using and ID in the URL and redirects to the original request or render a 1 pixel transparent image.
The 'tracking.url' init parameter in the Tracking handler defines the URL of the Tracking servlet.
The createTrackingId() method in the Tracking handler creating a dummy ID. For serious usage this method should be overriden.
The track() method in the Tracking servlet is using a Logger to log tracking information.
#### Echo Handler (alias the Uploader)
The Echo handler echoes (returns back) the feed POSTed to the Mano servlet.
This handler, as opposed to the others in the toolbox, it requires running in a servlet container and it has to be fronted by a servlet that supports POST requests as the ManoServlet does.
The POST request must have the handler parameters in the query\-string the content\-type header should be 'application/xml', the payload of the POST request must be a feed XML document and it's charset encoding it is assumed to be same as the one defined in the request.
The curl command can be used to test this handler, for example:
```
curl http://localhost:8080/mano/feed/echo \
--data-binary @~/myfeed.xml --header "content-type: application/xml
```
An interesting use of the Echo handler is that together with the File handler it can be use o upload and store feeds, for example:
```
curl http://localhost:8080/mano/feed/file/echo?file.write=myfeed \
--data-binary @~/myfeed.xml --header "content-type: application/xml
```
#### Null Handler
The Null handler discards the feed from the response and returns no content. If the response had a feed it is discarded and the repose status code is set to NO CONTENT (204). If the response had an error code the error code is returned.
#### Sort Handler
The Sort handler sorts entries by title or published date, in ascendent (default) or descendent order.
The namespaced parameter by must be title (default) or date. The namespaced parameter order must be asc (default) or desc.
NULL values are considered \-infinite for the purposes of ordering.
## Building ROME.Mano
ROME.Mano is a ROME sub\-project, rome/subprojects/mano.
It dependencies are ROME v0.8, JDOM v1.0, ROME Fetcher v0.8 and Servlet API v2.3\+.
It uses Maven 1.0.2 to build, maven war.
## Sample ROME.Mano URLs
Fetching a feed:
* [http://localhost:8080/mano/feed/fetch?fetch.url\=http://wired.com/rss/index.xml](http://localhost:8080/mano/feed/fetch?fetch.url=http://wired.com/rss/index.xml)
Fetching and converting a feed:
* [http://localhost:8080/mano/feed/convert/fetch?convert.to\=atom\_0.3&fetch.url\=http://wired.com/rss/index.xml](http://localhost:8080/mano/feed/convert/fetch?convert.to=atom_0.3&amp;fetch.url=http://wired.com/rss/index.xml)
Fetching, converting and storing 3 feeds (one at the time):
* [http://localhost:8080/mano/feed/file/convert/fetch?file.write\=a&convert.to\=atom\_1.0&fetch.url\=http://wired.com/rss/index.xml](http://localhost:8080/mano/feed/file/convert/fetch?file.write=a&amp;convert.to=atom_1.0&amp;fetch.url=http://wired.com/rss/index.xml)
* [http://localhost:8080/mano/feed/file/convert/fetch?file.write\=b&convert.to\=atom\_1.0&fetch.url\=http://www.tbray.org/ongoing/ongoing.rss](http://localhost:8080/mano/feed/file/convert/fetch?file.write=b&amp;convert.to=atom_1.0&amp;fetch.url=http://www.tbray.org/ongoing/ongoing.rss)
* [http://localhost:8080/mano/feed/file/convert/fetch?file.write\=acconvert.to\=atom\_1.0&fetch.url\=http://hotdeals.apple.com/newarrivals/rss/newarrivals.xml](http://localhost:8080/mano/feed/file/convert/fetch?file.write=acconvert.to=atom_1.0&amp;fetch.url=http://hotdeals.apple.com/newarrivals/rss/newarrivals.xml)
Fetching, converting and storing 3 feeds (all at once) and returning a merged feed with all their entries:
* [http://localhost:8080/mano/feed/multi/file/convert/fetch?multi.param\=file.write&multi.param\=fetch.url&file.write\=wired&fetch.url\=http://wired.com/rss/index.xml&file.write\=cnn\-top&fetch.url\=http://rss.cnn.com/rss/cnn\_topstories.rss&file.write\=cnn\-world&fetch.url\=http://rss.cnn.com/rss/cnn\_world.rss&file.write\=salon\-sports&fetch.url\=http://salon.com/rss/sports.rss&convert.to\=atom\_1.0](http://localhost:8080/mano/feed/multi/file/convert/fetch?multi.param=file.write&amp;multi.param=fetch.url&amp;file.write=wired&amp;fetch.url=http://wired.com/rss/index.xml&amp;file.write=cnn-top&amp;fetch.url=http://rss.cnn.com/rss/cnn_topstories.rss&amp;file.write=cnn-world&amp;fetch.url=http://rss.cnn.com/rss/cnn_world.rss&amp;file.write=salon-sports&amp;fetch.url=http://salon.com/rss/sports.rss&amp;convert.to=atom_1.0)
Reading 3 feeds previously written to disk, merging their entries and paginating the feed:
* [http://localhost:8080/mano/feed/multi/branding/file?&multi.param\=file.read&file.read\=wired&file.read\=cnn\-top&file.read\=cnn\-world&file.read\=salon\-sports](http://localhost:8080/mano/feed/multi/branding/file?&amp;multi.param=file.read&amp;file.read=wired&amp;file.read=cnn-top&amp;file.read=cnn-world&amp;file.read=salon-sports)
Same as previous feed but with tracking, pagination and sorted:
* [http://localhost:8080/mano/feed/tracking/sort/paginate/multi/branding/file?paginate.offset\=10&paginate.size\=20&multi.param\=file.read&file.read\=wired&file.read\=cnn\-top&file.read\=cnn\-world&file.read\=salon\-sports&sort.by\=title&sort.order\=desc](http://localhost:8080/mano/feed/tracking/sort/paginate/multi/branding/file?paginate.offset=10&amp;paginate.size=20&amp;multi.param=file.read&amp;file.read=wired&amp;file.read=cnn-top&amp;file.read=cnn-world&amp;file.read=salon-sports&amp;sort.by=title&amp;sort.order=desc)

55
src/site/markdown/modules/A9OpenSearch.md Normal file
View file

@ -0,0 +1,55 @@
# A9 OpenSearch
This plug in is for use with [OpenSearch.org](http://www.opensearch.org/) results.
The latest version is 0.1 available.
## Sample Usage
```
SyndFeed feed = new SyndFeedImpl();
feed.setFeedType(feedType);
// Add the opensearch module, you would get information like totalResults from the
// return results of your search
List mods = feed.getModules();
OpenSearchModule osm = new OpenSearchModuleImpl();
osm.setItemsPerPage(1);
osm.setStartIndex(1);
osm.setTotalResults(1024);
osm.setItemsPerPage(50);
OSQuery query = new OSQuery();
query.setRole("superset");
query.setSearchTerms("Java Syndication");
query.setStartPage(1);
osm.addQuery(query);
Link link = new Link();
link.setHref("http://www.bargainstriker.com/opensearch-description.xml");
link.setType("application/opensearchdescription+xml");
osm.setLink(link);
mods.add(osm);
feed.setModules(mods);
// end add module
```
## Changes
### 0.1
Initial move to the ROME project.

36
src/site/markdown/modules/Content.md Normal file
View file

@ -0,0 +1,36 @@
# Content
This plug in is for use content:encoded in feeds.
The latest version is 0.4 available.
## Sample Usage
```
SyndFeedInput input = new SyndFeedInput();
SyndFeed syndfeed = input.build(new XmlReader(feed.toURL()));
Module module = syndfeed.getModule("http://purl.org/rss/1.0/modules/content/");
ContentModule content = (ContentModule) module;
Iterator it = content.getEncodeds().iterator();
System.out.println( it.next() );
```
## Changes
### 0.4
Initial move to the ROME project.

42
src/site/markdown/modules/CreativeCommons.md Normal file
View file

@ -0,0 +1,42 @@
# Creative Commons
This plug in is for use with feeds from Creative Commons license.
This module provides a unified rights and license system for both the RSS2/Atom and RSS/RDF namespace. However, if you wish to **generate** RDF/RSS feeds, you need to use a CVS build of ROME (or a version higher than 0.8).
The latest version is 0.2 available.
## Sample Usage
```
CreativeCommons commons = new CreativeCommonsImpl();
commons.setLicense( new License[]{ License.NONCOMMERCIAL } );
// Note, you do not have to setAllLicenses right now. When the RSS1 functionality is
// added, this will be required at the Feed level only.
ArrayList modules = new ArrayList()
modules.add( commons );
syndEntry.setModules( commons );
//Alternately, to get the module:
CreativeCommons commons = (CreativeCommons) syndFeed.getModule( CreativeCommons.URI );
```
## Changes
### 0.2
Initial release from ROME.

52
src/site/markdown/modules/GeoRSS.md Normal file
View file

@ -0,0 +1,52 @@
# GeoRSS
This Rome plugin is for adding location information to RSS/Atom.
The latest version is 0.1 available.
## Sample Usage
```
SyndFeedInput input = new SyndFeedInput();
SyndFeed feed = input.build(new XmlReader(new URL("http://www.geonames.org/recent-changes.xml")));
List<SyndEntry>; entries = feed.getEntries();
for (SyndEntry entry : entries) {
GeoRSSModule geoRSSModule = GeoRSSUtils.getGeoRSS(entry);
System.out.println(entry.getTitle() + " : lat="
+ geoRSSModule.getLatitude() + ",lng="
+ geoRSSModule.getLongitude() + ", desc="
+ entry.getDescription().getValue() + "; time="
+ entry.getPublishedDate());
}
//to generate a GeoRSS item
GeoRSSModule geoRSSModule = new W3CGeoModuleImpl();
//GeoRSSModule geoRSSModule = new SimpleModuleImpl();
geoRSSModule.setLatitude(47.0);
geoRSSModule.setLongitude(9.0);
entry.getModules().add(geoRSSModule);
```
More information here: [http://georss.geonames.org/](http://georss.geonames.org/)
## Changes
### 0.1
Initial Releas from ROME

41
src/site/markdown/modules/GoogleBase.md Normal file
View file

@ -0,0 +1,41 @@
# Google Base
This plug in is for use with Google Base RSS/Atom Extensions
The latest version is 0.2 available.
## Sample Usage
```
SyndEntry entry = new SyndEntryImpl();
// set up the entry...
Vehicle vehicle = new GoogleBaseImpl();
vehicle.setMake("Honda");
vehicle.setModel("Insight");
vehicle.setYear( new Year("2000"));
List modules = new ArrayList();
modules.add( vehicle );
entry.setModules( modules );
//Optionally, to get Google Base information from a Feed:
Article article = entry.getModule( "http://base.google.com/ns/1.0" );
System.out.println( article.getPages() );
```
## Changes
### 0.2
Initial release from ROME project.

52
src/site/markdown/modules/IPhotoPhotocasting.md Normal file
View file

@ -0,0 +1,52 @@
# iPhoto Photocasting
This plug in is for use with iPhoto Photocast listings.
This module will read and write photocast feeds "properly". Be advised, however, that an iPhoto photocast feed will not pass a FeedValidator test as they are not properly namespaced. If you are wanting to publish, rather than read, consider using the [MediaRSS.html](MediaRSS.html) plug in instead. iPhoto will also read [MediaRSS.html](MediaRSS.html) (Flickr Photostream) feeds as well.
The latest version is 0.2 available.
## Sample Usage
```
SyndFeed feed = input.build( new File( "/foo.rss" ) ) );
List entries = feed.getEntries();
for( int i =0; i < entries.size() ; i++ ){
System.out.println( ((SyndEntry)entries.get(i)).getModule( PhotocastModule.URI ) );
}
// or to create a photocast module:
SyndFeed myFeed = new SyndFeedImpl();
myFeed.getModules().add( new PhotocastModuleImpl() );
// you need this as a placeholder so the version gets in the feed.
SyndEntry myEntry = new SyndEntryImpl();
PhotocastModule pm = new PhotocastModuleImpl();
pm.setUrl( new URL("http://foo.com/img.jpg" ) );
pm.setThumnail( new URL("http://foo.com/img-small.jpg" ) );
pm.setCropDate( new Date() );
pm.setPhotoDate( new Date() );
pm.setMetaData( new PhotoDate(), "Some comments that I think always get ignored." );
myEntry.getModules().add( pm );
```
## Changes:
### 0.2
Initial move to the ROME project.

53
src/site/markdown/modules/ITunesPodcasting.md Normal file
View file

@ -0,0 +1,53 @@
# iTunes Podcasting
This plug in is for use with iTunes Music Service podcast listings.
The latest version is 0.4 available.
## Sample Usage
```
SyndFeedInput input = new SyndFeedInput();
SyndFeed syndfeed = input.build(new XmlReader(feed.toURL()));
Module module = syndfeed.getModule("http://www.itunes.com/dtds/podcast-1.0.dtd");
FeedInformation feedInfo = (FeedInformation) module;
System.out.println( feedInfo.getImage() );
System.out.println( feedInfo.getCategory() );
// Or to create a feed..
ArrayList modules = new ArrayList();
EntryInformation e = new EntryInformationImpl();
e.setDuration( new Duration( 10000 ) );
modules.add( e );
syndEntry.setModules( modules );
```
## Changes
### 0.4
* Corrected some Feed vs Item attribute issue.
* Keywords now comma separated instead of space.
### 0.3
Added support for the "other" case of podcasts. It will now correctly parse all lowercase URIs as wells as the original mixed case URIs All generated feeds use the lowercase URI. Fixed some entity problems related to the apple summary tag.

55
src/site/markdown/modules/MediaRSS.md Normal file
View file

@ -0,0 +1,55 @@
# MediaRSS
This plugin is for use with Yahoo! MediaRSS/Flickr Photostreams
The latest version is 0.1 available.
## Sample Usage
```
SyndFeed feed = input.build( myRSSFile );
List entries = feed.getEntries();
for( int i = 0; i < entries.size(); i++ ){
System.out.println( ((SyndEntry) entries.get(i)).getModule( MediaModule.URI ) );
}
//Alternatively, to add a media item to an entry:
MediaContent[] contents = new MediaContent[1];
MediaContent myItem = new MediaContent( new UrlReference("http://me.com/movie.mpg") );
contents[0] = myItem();
Metadata md = new Metadata();
Thumbnail[] thumbs = new Thumbnail[2];
thumbs[0] = new Thumbnail( new URL("http://me.com/movie1.jpg") );
thumbs[1] = new Thumbnail( new URL("http://me.com/movie2.jpg") );
md.setThumbnail( thumbs );
myItem.setMetadata( md );
MediaEntryModuleImpl module = new MediaEntryModuleImpl();
module.setMediaContents( contents );
mySyndEntry.getModules().add( module );
```
## Changes
### 0.2.1
Bugfix for metadata on MediaGroups.
### 0.1
Initial release from ROME.

52
src/site/markdown/modules/MicrosoftSimpleListExtensions.md Normal file
View file

@ -0,0 +1,52 @@
# Microsoft Simple List Extensions
This plug in is for use with feeds ith Microsoft Simple List Extensions.
Note you need to use the current CVS version of ROME or 0.9 when available.
The latest version is 0.1 available.
## Sample Usage
```
SimpleListExtension sle = (SimpleListExtension) feed.getModule( SimpleListExtension.URI );
System.out.println( sle );
Group[] groups = sle.getGroupFields();
System.out.println( groups[0].getLabel() );
//You can use the SleUtility class to do sorting and grouping:
List sortedEntries = SleUtility.sort( feed.getEntries(), sle.getSortFields()[1], true );
SyndEntry entry = (SyndEntry) sortedEntries.get( 0 );
//You can also Group or Sort and Group
List sortedAndGroupedEntries = SleUtility.sortAndGroup( feed.getEntries, sle.getGroupFields(), sle.getSortFields()[0], false );
// If you change, for instance, module values on a feed and want to reinitialize it for
// grouping and sorting...
SleUtility.initializeForSorting( feed );
// Be aware, this is a VERY heavy operation and should not be used frequently.
```
## Changes
### 0.1
Initial release from ROME.

37
src/site/markdown/modules/MicrosoftSimpleSharingExtensions.md Normal file
View file

@ -0,0 +1,37 @@
# Microsoft Simple Sharing Extensions
This ROME module supports Microsoft Simple Sharing Extensions, an RSS and [OPML](../opml/index.html) extension designed to support data synchronization between bi\-directional feeds.
The latest version is 0.1 available.
## Sample Usage
```
SyndFeedInput input = new SyndFeedInput();
SyndFeed syndfeed = input.build(new XmlReader(feed.toURL()));
List entries = syndfeed.getEntries();
Iterator it = entries.iterator();
for (int id = 101; it.hasNext() && id <= 113; id++) {
SyndEntry entry = (SyndEntry) it.next();
Sync sync = (Sync) entry.getModule(SSEModule.SSE_SCHEMA_URI);
assertEquals(String.valueOf(id), sync.getId());
History history = sync.getHistory();
assertNotNull(history);
Date when = history.getWhen();
assertNotNull(when);
Date testDate = DateParser.parseRFC822("Fri, 6 Jan 2006 19:24:09 GMT");
assertEquals(testDate, when);
}
```

42
src/site/markdown/modules/Slash.md Normal file
View file

@ -0,0 +1,42 @@
# Slash
This plug in is for use with feeds from Slash\-based weblogs.
The latest version is 0.2 available.
## Sample Usage
```
SyndEntry entry = new SyndEntryImpl();
// set up the entry...
Slash slash = new SlashImpl();
slash.setComments( new Integer( 12 ) );
slash.setDepartment( "look-another-rome-plugin" );
slash.setSection("code");
slash.setHitParade( new Integer[] { new Integer(12), new Integer(0) } );
List modules = new ArrayList();
modules.add( slash );
entry.setModules( modules );
//Optionally, to get Slash information from a Feed:
Slash slash = entry.getModule( Slash.URI );
System.out.println( slash.getComments() );
```
## Changes
### 0.2
Initial release from ROME.

40
src/site/markdown/modules/Weather.md Normal file
View file

@ -0,0 +1,40 @@
# Weather
This plug in is for use the [Yahoo! Weather service](http://developer.yahoo.com/weather/).
The latest version is 0.1 available.
## Sample Usage
```
SyndFeed feed = input.build( ... );
YWeatherFeedModule yfeed = (YWeatherFeedModule) feed.getModule( YWeatherFeedModule.URI );
System.out.println( yfeed.getLocation().getCity() );
SyndEntry entry = (SyndEntry) feed.getEntries().get(0);
YWeatherEntryModule yentry = (YWeatherEntryModule) entry.getModule( YWeatherEntryModule.URI );
System.out.println( yentry.getForecasts()[0].getHigh() );
//Optionally, to add Weather information to a feed:
SyndEntry entry = new SyndEntryImpl();
YWeatherEntryModule yentry = new YWeatherModuleImpl();
yentry.setCondition( Condition("Partly Cloudy", ConditionCode.PARTLY_CLOUDY, 65, new Date() ) );
entry.getModules.add(yentry);
```
## Changes
### 0.1
Initial release from ROME.

92
src/site/markdown/modules/index.md Normal file
View file

@ -0,0 +1,92 @@
# Home
## The ROME Modules Subproject.
The ROME Modules project is an effort to roll up contributed module support into a single distribution for users.
## Current modules in the subproject include:
* [ITunesPodcasting.html](ITunesPodcasting.html) – Apples extensions for listing in the iTunes podcast directory.
* [GeoRSS.html](GeoRSS.html) – For adding location information to RSS/Atom.
* [Slash.html](Slash.html) – Used by Slash\-based blogs.
* [GoogleBase.html](GoogleBase.html) – For working with the Google Base types and custom tagsets.
* [Content.html](Content.html) – For using content:encoded tags.
* [CreativeCommons.html](CreativeCommons.html) – A unified module for working with the RDF and RSS/Atom Creative Commons License information.
* [Yahoo! MediaRSS](MediaRSS.html) – For working with Yahoo! MediaRSS feeds (and Flickr Photostreams)
* [IPhotoPhotocasting.html](IPhotoPhotocasting.html) – For working with Apple iPhoto Photocasts
* [A9OpenSearch.html](A9OpenSearch.html) – For working with Amazon/OpenSearch.org results.
* [MicrosoftSimpleListExtensions.html](MicrosoftSimpleListExtensions.html) – for sorting and grouping entries.
* [MicrosoftSimpleSharingExtensions.html](MicrosoftSimpleSharingExtensions.html) – for synchronizing across bi\-directional RSS and [OPML](index.html) feeds.
* [Yahoo! Weather](Weather.html) – For use with the Yahoo Weather API
## Get it.
The 0.3.2 release of modules.jar (which contains all the above modules) is available.
### Downloads
Please don't use modules\-0.3.jar. It had errors in the packaging which have been fixed in modules\-0.3.1.jar and subsequent releases
See individual module sites for information.
## Changes
### 1.0 \- released 24 February 2011
Finalized 1.0 release.
### 0.3.2 \- released 30 Jan 2009
* [http://java.net/jira/browse/ROME\-122](http://java.net/jira/browse/ROME-122)
## General Guidelines for modules:
This is intended to serve as a guide for contributions as well as a hint for users working with the modules.
* Modules are packaged in com.sun.syndication.feed.module.\[Module Name\].
* Modules contain a com.sun.syndication.feed.module.\[Module Name\].Module.URI reference for retrieval from ROME Synd\* classes.
* Modules contain a com.sun.syndication.feed.module.\[Module Name\].ModuleImpl that is a concrete implementation.
* Modules contain a com.sun.syndication.feed.module.\[Module Name\].types package that holds any other datatypes needed for the module. Many of these are simple immutable types to simplify clone() and copyFrom()
* Modules contain a com.sun.syndication.feed.module.\[Module Name\].io package with parsers and generators.

145
src/site/markdown/opml/index.md Normal file
View file

@ -0,0 +1,145 @@
# Home
This project provides support for [OPML](http://www.opml.org/) in ROME.
## Downloads
* [Binaries](https://rome.dev.java.net/servlets/ProjectDocumentList?folderID=5198)
* [JavaDocs](https://rome.dev.java.net/nonav/apidocs/subprojects/opml/0.1/apidocs/index.html)
## Sample Usage
To use this parser, simply include the jar file in your classpath as you are using ROME. Be sure it exists at the same level as ROME, such that, if ROME is in the common classpath of an application server, don't include this jar in your webapps WEB\-INF/lib.
```
WireFeedInput input = new WireFeedInput();
Opml feed = (Opml) input.build( new File("myOpml.xml") );
List<Outline> outlines = (List<Outline>) feed.getOutlines();
```
## Hierarchy vs Flat
Since OPML is a hierarchical format, some magic is required to preserve this information when they feed is moved to a Synd\* structure. This is accomplished by adding categories indicating the tree structure to the [SyndEntries](http://wiki.java.net/bin/edit/Javawsxml/SyndEntries?topicparent=Javawsxml.OPML;nowysiwyg=0) ...
For example:
```
<opml version="1.0">
<head>
<title>Top Ten Sources for podcasting</title>
<ownerName>Newsilike Media Group</ownerName>
<ownerEmail>opml@TopTenSources.com</ownerEmail>
</head>
<body>
<outline type="link" text="TopTenSources: podcasting"
url="http://podcasting.TopTenSources.com/TopTenSources/" />
<outline text="CBS Technology News Podcast - Larry Magid' Tech Report">
<outline type="link" text="Larry Magid's Tech Report" url="http://www.cbsnews.com" />
</outline>
<outline text="Adam Curry: Daily Source Code">
<outline type="link" text="#374 Daily Source Code for Tuesday April 25th 2006"
url="http://radio.weblogs.com/0001014/2006/04/26.html#a7304" />
<outline type="link" text="#373 Daily Source Code for Monday April 24th 2006"
url="http://radio.weblogs.com/0001014/2006/04/24.html#a7303" />
<outline type="link" text="#372 Daily Source Code for Friday April 21st 2006"
url="http://radio.weblogs.com/0001014/2006/04/21.html#a7302" />
<outline type="link" text="#371 Daily Source Code for Thursday April 20th 2006"
url="http://radio.weblogs.com/0001014/2006/04/20.html#a7301" />
<outline type="link" text="#370 Daily Source Code for Wednesday April 19th 2006"
url="http://radio.weblogs.com/0001014/2006/04/19.html#a7300" />
</outline>
<outline text="Gillmor Gang">
<outline type="link" text="Syndicate Gang Part I" url="http://gillmorgang.podshow.com/?p=44" />
<outline type="link" text="HughTrain Gang" url="http://gillmorgang.podshow.com/?p=43" />
<outline type="link" text="Phlegm at 11 Gang" url="http://gillmorgang.podshow.com/?p=42" />
<outline type="link" text="NDA Gang" url="http://gillmorgang.podshow.com/?p=41" />
<outline type="link" text="When the Music?s Over Gang" url="http://gillmorgang.podshow.com/?p=40" />
</outline>
```
...
When converted to RSS2 becomes:
```
<channel>
<title>Top Ten Sources for podcasting</title>
<link>http://foo.com</link>
<description />
<managingEditor>Newsilike Media Group</managingEditor>
<item>
<title>TopTenSources: podcasting</title>
<link>http://podcasting.TopTenSources.com/TopTenSources/</link>
<category domain="urn:rome.tree">node.-1732517202</category>
<category domain="urn:rome.attribute#url">
http://podcasting.TopTenSources.com/TopTenSources/</category>
<guid>http://podcasting.TopTenSources.com/TopTenSources/</guid>
</item>
<item>
<title>CBS Technology News Podcast - Larry Magid' Tech Report</title>
<category domain="urn:rome.tree">node.1353657827</category>
</item>
<item>
<title>Larry Magid's Tech Report</title>
<link>http://www.cbsnews.com</link>
<category domain="urn:rome.tree">node.-4085850</category>
<category domain="urn:rome.tree">parent.1353657827</category>
<category domain="urn:rome.attribute#url">http://www.cbsnews.com</category>
<guid>http://www.cbsnews.com</guid>
</item>
<item>
<title>Adam Curry: Daily Source Code</title>
<category domain="urn:rome.tree">node.835791399</category>
</item>
<item>
<title>#374 Daily Source Code for Tuesday April 25th 2006</title>
<link>http://radio.weblogs.com/0001014/2006/04/26.html#a7304</link>
<category domain="urn:rome.tree">node.222050897</category>
<category domain="urn:rome.tree">parent.835791399</category>
<category domain="urn:rome.attribute#url">
http://radio.weblogs.com/0001014/2006/04/26.html#a7304</category>
<guid>http://radio.weblogs.com/0001014/2006/04/26.html#a7304</guid>
</item>
<item>
<title>#373 Daily Source Code for Monday April 24th 2006</title>
<link>http://radio.weblogs.com/0001014/2006/04/24.html#a7303</link>
<category domain="urn:rome.tree">node.2088220478</category>
<category domain="urn:rome.tree">parent.835791399</category>
<category domain="urn:rome.attribute#url">
http://radio.weblogs.com/0001014/2006/04/24.html#a7303</category>
<guid>http://radio.weblogs.com/0001014/2006/04/24.html#a7303</guid>
</item>
```
Nodes get categories with the "urn:rome.tree" URI that is used to maintain the tree structure.
The other thing you will notice is the "urn:rome.attribute#url". Since OPML allows you to add arbitrary attributes to each outline element, these are used to preserve these values.

15
src/site/markdown/propono/ROMEProponoVersion0.4.md Normal file
View file

@ -0,0 +1,15 @@
# ROME Propono Version 0.4
This is the first release of the [Rome Propono](index.html) publishing library. It's a beta release and will be followed closely by Propono 0.5.
## Downloads
## API Docs
* [Propono 0.4 API Docs](https://rome.dev.java.net/apidocs/subprojects/propono/0.4/overview-summary.html)

25
src/site/markdown/propono/ROMEProponoVersion0.5.md Normal file
View file

@ -0,0 +1,25 @@
# ROME Propono Version 0.5
This is the second release of the [Rome Propono](index.html) publishing library. It's a bug fix release follow\-on to 0.4. Here are the changes:
* Fixes in Blog Client constructors
* AtomServlet uses application/atomsvc\+xml for the Service Document
* Fixed issue #66: don't expect entry to be returned from update
* Made example builds more configurable
## Downloads
## API Docs
* [Propono 0.5 API Docs](https://rome.dev.java.net/apidocs/subprojects/propono/0.5/overview-summary.html)

84
src/site/markdown/propono/ROMEProponoVersion0.6.md Normal file
View file

@ -0,0 +1,84 @@
# ROME Propono Version 0.6
September 30, 2007
This is the third release of the [Rome Propono](index.html) publishing library. It includes major changes to add support for the final Atom Publishing Protocol specification relative URIs and out\-of\-line categories. It's an an interim release it includes a pre\-release version of ROME 0.9.1\-dev. A new version will follow as soon as ROME 0.9.1 (or 1.0) has been finalized.
## Downloads
## API Docs
* [Propono 0.6 API Docs](https://rome.dev.java.net/apidocs/subprojects/propono/0.6/overview-summary.html)
## Changes
* Updated for APP final (draft #17) w/new APP URI "http://www.w3.org/2007/app"
* Tested file\-based server against Tim Bray's Ape (from CVS September 30, 2007).
* Now includes pre\-release of ROME 0.9.1 with key Atom parse fixes.
* Changed arguements in Atom server's AtomHandler interface to accept AtomRequest objects instead of String\[\] pathinfo arrays.
* Added support for relative URIs in the Service Document
* Fixes [http://java.net/jira/browse/ROME\-67](http://java.net/jira/browse/ROME-67)
* Added Collection.getHrefResolved()
* Added Categories.getHrefResolved()
* Added new options to the file\-based server's propono.properties file so you can turn on/off relative URIs and inline categories.
* propono.atomserver.filebased.relativeURIs\=true
* propono.atomserver.filebased.inlineCategories\=true
* Added support for out\-of\-line categories in Atom client classes
* Added new Categories.href property
* New ClientCategories classes can fetch remote categories from href URI
* Fixes [http://java.net/jira/browse/ROME\-68](http://java.net/jira/browse/ROME-68)
* Added support for out\-of\-line categories in Atom server classes
* New AtomHandler.getCategoriesDocument(String\[\] pathInfo) method
* New AtomHandler.isCategoriesDocumentURI(String\[\] pathInfo) method
* Renamed Introspection to Service Document
* AtomHandler.isIntrospectionURI() \-\> AtomHandler.isSerivceDocumentURI()
* AtomHandler.getIntrospection() \-\> AtomHandler.getServiceDocument()
* Added String\[\] pathInfo argument to getServiceDocument()
* Renamed PubControlModule to AppModule becuase it also supports app:edited
* Added rome.properties file to configure AppModule

30
src/site/markdown/propono/ROMEProponoVersion1.0.md Normal file
View file

@ -0,0 +1,30 @@
# ROME Propono Version 1.0
April 2009
ROME Propono 1.0 is coming soon. If you'd like to help out, you can try 1.0 RC1 and provide feedback to us on the ROME dev mail list.
## Downloads
## API Docs
* [Propono 1.0 API Docs](https://rome.dev.java.net/apidocs/subprojects/propono/1.0/overview-summary.html)
## Changes
* Updated to ROME 1.0
* Added support for pluggable authentication in the AtomPub client
* Added support for OAuth in the AtomPub client, see Javadocs for details

29
src/site/markdown/propono/index.md Normal file
View file

@ -0,0 +1,29 @@
# Home
# ROME Propono
The ROME Propono subproject is a Java class library that 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.
# Documentation
* See the [Propono API docs](https://rome.dev.java.net/apidocs/subprojects/propono/0.6/overview-summary.html) for an explanation of Propono usage, diagrams and code examples.
# Releases
* [ROMEProponoVersion1.0.html](ROMEProponoVersion1.0.html) \- Release 1.0 coming soon...
* [ROMEProponoVersion0.6.html](ROMEProponoVersion0.6.html)
* [ROMEProponoVersion0.5.html](ROMEProponoVersion0.5.html)
* [ROMEProponoVersion0.4.html](ROMEProponoVersion0.4.html)

752
src/site/markdown/rome/ChangeLog.md Normal file
View file

@ -0,0 +1,752 @@
# Change Log
## Changes made since v1.0
1. [Issue 127](http://java.net/jira/browse/ROME-127): Rome 1.0 not JDK 1.4 compatible
## Changes made since v1.0RC2
1. [Issue 121](http://java.net/jira/browse/ROME-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](PreservingWireFeeds.html) 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 [Issue 1101](http://java.net/jira/browse/ROME-110) 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 [Issue 117](http://java.net/jira/browse/ROME-117) for details.
1. New. Allow pretty printing to be turned on and off
see [Issue 114](http://java.net/jira/browse/ROME-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 ([Issue 118](http://java.net/jira/browse/ROME-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 [104](http://java.net/jira/browse/ROME-104), [107](http://java.net/jira/browse/ROME-107) and [108](http://java.net/jira/browse/ROME-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 [Issue 91](http://java.net/jira/browse/ROME-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 [Issue 48](http://java.net/jira/browse/ROME-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&amp;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 [Issue 36](http://java.net/jira/browse/ROME-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" [Issue 33](http://java.net/jira/browse/ROME-33)
* Atom 1.0 Text Types Not Set Correctly [Issue 39](http://java.net/jira/browse/ROME-39)
* Security issue [Issue 46](http://java.net/jira/browse/ROME-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 [Issue 26](http://java.net/jira/browse/ROME-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 [Issue 24](http://java.net/jira/browse/ROME-24)
* Non RFC822 Dates not processed in RSS pubDate field [Issue 27](http://java.net/jira/browse/ROME-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 [Issue 41](http://java.net/jira/browse/ROME-41)
* Atom 1.0 Date (Updated or Published) Not Set [Issue 42](http://java.net/jira/browse/ROME-42)
* lastBuildDate does not populate publishedDate [Issue 43](http://java.net/jira/browse/ROME-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 [Issue 37](http://java.net/jira/browse/ROME-37)
* ATOM 1.0 Entry links parsing [Issue 38](http://java.net/jira/browse/ROME-38)
* ConverterForRSS10.java does not set URI for item [Issue 25](http://java.net/jira/browse/ROME-25)
* Valid IRI href attributes are stripped for atom:link [Issue 34](http://java.net/jira/browse/ROME-34)
1. Module fixes
* iTunes Module has incorrect author and category support [Issue 35](http://java.net/jira/browse/ROME-35)
* mediarss.io.MediaModuleParser NumberFormatException [Issue 45](http://java.net/jira/browse/ROME-45)
* Slash module not serializable for FeedFetcher [Issue 44](http://java.net/jira/browse/ROME-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&amp;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 [Feed and entry URI Mapping](RomeV0.4FeedAndEntryURIMapping.html) 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.

384
src/site/markdown/rome/HowRomeWorks/RomeV0.4TutorialDefiningACustomModuleBeanParserAndGenerator.md Normal file
View file

@ -0,0 +1,384 @@
# 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 [Understanding the Rome common classes and interfaces](http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04Common) 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 [Understanding the Rome common classes and interfaces](http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04Common) 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 [Rome Plugins Mechanism](http://wiki.java.net/twiki/bin/view/Javawsxml/Rome04Plugins) topic.

147
src/site/markdown/rome/HowRomeWorks/RomeV0.4TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.md Normal file
View file

@ -0,0 +1,147 @@
# 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();
}
}
}
```

103
src/site/markdown/rome/HowRomeWorks/RomeV0.4TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.md Normal file
View file

@ -0,0 +1,103 @@
# 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();
}
}
}
```

205
src/site/markdown/rome/HowRomeWorks/RomeV0.4TutorialUsingRomeToCreateAndWriteASyndicationFeed.md Normal file
View file

@ -0,0 +1,205 @@
# 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();
}
}
}
```

90
src/site/markdown/rome/HowRomeWorks/RomeV0.4TutorialUsingRomeToReadASyndicationFeed.md Normal file
View file

@ -0,0 +1,90 @@
# 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();
}
}
}
```

374
src/site/markdown/rome/HowRomeWorks/UnderstandingTheRomeCommonClassesAndInterfaces.md Normal file
View file

@ -0,0 +1,374 @@
# 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/markdown/rome/HowRomeWorks/index.md Normal file
View file

@ -0,0 +1,97 @@
# How Rome works
**Dave Johnson (****[The Roller Weblogger](http://www.rollerweblogger.org/)****) has written a very nice blog** **[How Rome Works](http://www.rollerweblogger.org/page/roller/20040808#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 [Rome](http://rome.dev.java.net/) feed parser for Java and trying to understand how it works. Along the way, I put together the following class diagram and notes on the parsing process. I provide some pointers into the [Rome 0.4 Javadocs](http://rome.dev.java.net/apidocs/0_4/overview-summary.html).
You don't need to know this stuff to use Rome, but it you are interested in internals you might find it interesting.
## Notes on the Rome parsing process
Rome is based around an idealized and abstract model of a Newsfeed or "Syndication Feed." Rome can parse any format of Newsfeed, including RSS variants and Atom, into this model. Rome can convert from model representation to any of the same Newfeed output formats.
Internally, Rome defines intermediate object models for specific Newsfeed formats, or "Wire Feed" formats, including both Atom and all RSS variants. For each format, there is a separate JDOM based parser class that parses XML into an intermediate model. Rome provides "converters" to convert between the intermediate Wire Feed models and the idealized Syndication Feed model.
Rome makes no attempt at [Pilgrim\-style liberal XML parsing](http://www.xml.com/pub/a/2003/01/22/dive-into-xml.html). If a Newsfeed is not valid XML, then Rome will fail. Perhaps, as [Kevin Burton suggests](http://www.peerfear.org/rss/permalink/2003/01/23/1043368363-Smart_Parsing__Not_RSS_Parsing.shtml), 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:
1. Your code calls [SyndFeedInput](http://rome.dev.java.net/apidocs/0_4/com/sun/syndication/io/SyndFeedInput.html) to parse a Newsfeed, for example (see also [Using Rome to read a syndication feed](RomeV0.4TutorialUsingRomeToReadASyndicationFeed.html)):
```
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. [WireFeedInput](http://rome.dev.java.net/apidocs/0_4/com/sun/syndication/io/WireFeedInput.html) 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 [JDom](http://www.jdom.org/), into a [WireFeed](http://rome.dev.java.net/apidocs/0_4/com/sun/syndication/feed/WireFeed.html). If the Newsfeed is in an RSS format, the the WireFeed is of class [Channel](http://rome.dev.java.net/apidocs/0_4/com/sun/syndication/feed/rss/Channel.html) and contains Items, Clouds, and other RSS things from the [com.sun.syndication.feed.rss](http://rome.dev.java.net/apidocs/0_4/com/sun/syndication/feed/rss/package-summary.html) package. Or, on the other hand, if the Newsfeed is in Atom format, then the WireFeed is of class [Feed](http://rome.dev.java.net/apidocs/0_4/com/sun/syndication/feed/atom/Feed.html) from the [com.sun.syndication.atom](http://rome.dev.java.net/apidocs/0_4/com/sun/syndication/feed/atom/package-summary.html) 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. [SyndFeedImpl](http://rome.dev.java.net/apidocs/0_4/com/sun/syndication/feed/synd/SyndFeed.html) 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 [define your own custom modules](RomeV0.4TutorialDefiningACustomModuleBeanParserAndGenerator.html) too.
Rome also supports [Newsfeed output](RomeV0.4TutorialUsingRomeToCreateAndWriteASyndicationFeed.html) 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 [Rome Wiki](../index.html):
1. [Using Rome to read a syndication feed](RomeV0.4TutorialUsingRomeToReadASyndicationFeed.html)
1. [Using Rome to convert a syndication feed from one type to another](RomeV0.4TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html)
1. [Using Rome to aggregate many syndication feeds into a single one](RomeV0.4TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html)
1. [Using Rome to create and write a feed](RomeV0.4TutorialUsingRomeToCreateAndWriteASyndicationFeed.html)
1. [Defining a Custom Module bean, parser and generator](RomeV0.4TutorialDefiningACustomModuleBeanParserAndGenerator.html)
## 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.

101
src/site/markdown/rome/HowToBuildRome.md Normal file
View file

@ -0,0 +1,101 @@
# How to build Rome?
Rome is built using mighty [Maven](http://maven.apache.org/)! 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 [Version Control](https://rometools.jira.com/source/browse/ROME) 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 [Installing Maven](http://maven.apache.org/run-maven/index.html) 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:\-)

52
src/site/markdown/rome/PreservingWireFeeds.md Normal file
View file

@ -0,0 +1,52 @@
# 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

198
src/site/markdown/rome/ProductsOrSitesPoweredByROME.md Normal file
View file

@ -0,0 +1,198 @@
# 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 [users@rome.dev.java.net.](mailto: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
* [Firenze](http://firenze.berlios.de/)
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.
* [Feed'n Read](http://fnr.sourceforge.net/)
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.
* [Tudu Lists](http://tudu.sourceforge.net/)
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/).
* [SnipSnap](http://snipsnap.org/)
* [Roller Weblogger and Aggregator](http://www.rollerweblogger.org/page/project)
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, [created PlanetRoller in a couple of days](http://rollerweblogger.org/page/roller/20050213#rome_texen_planet_roller), leveraging ROME and ROME fetcher to do all the hard work. You can try out at [PlanetRoller](http://www.rollerweblogger.org/planet/roller.html).
* [ActiveMQ](http://incubator.apache.org/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 [browse message queues](http://docs.codehaus.org/display/ACTIVEMQ/RSS+and+Atom) (with or without filters applied) as RSS or Atom feeds.
* [XWiki](http://www.xwiki.org/)
* [mobibot](http://www.thauvin.net/mobitopia/mobibot/)
* [stat4j](http://sourceforge.net/projects/stat4j/)
Used ROME to create an RSS/ATOM Log4j Appender. Read more about it [here](http://www.jroller.com/comments/laraDAB?anchor=rss_atom_log4j_appender).
* [SPOT Manager](http://www.spotdev.net/)
SPOT Manager uses ROME to parse RSS feeds and send them to your MSN Direct wristwatch! Learn about MSN Direct [here.](http://www.msndirect.com/) Download the program from [SPOTDev.net](http://www.spotdev.net/).
* [LogDistiller](http://logdistiller.sf.net/)
LogDistiller is an extensible tool to merge and sort logs : reports can be stored in a feed file thanks to Rome.
* [ION Internet Video Console](http://openvision.tv/)
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 [here](http://openvision.tv/).
* [Blog Mover](http://code.google.com/p/blog-mover)
Blog Mover's goal is allowing your blog moving freely between each BSP(Blog Service Provider). Learn more and try it [here](http://blog-mover.redv.com/).
* [Scarab](http://scarab.tigris.org/)
The goal of the Scarab project is to build a highly customisable Artifact tracking system. It's distributed under a BSD/Apache style license.
* [Ozmozr](http://ozmozr.org/)
Ozmozr is a website for online learning communities being developed by the [Center for Open Sustainable Learning](http://www.cosl.usu.edu/) at [Utah State University](http://www.usu.edu/). 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
* [MORSE](http://www.infosys.tuwien.ac.at/prototype/morse/)
The [Model\-Aware Repository and Service Environment](http://www.infosys.tuwien.ac.at/prototype/morse/) (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 [feed](http://www.infosys.tuwien.ac.at/m2projects/at.ac.tuwien.infosys.tholmes.morse/rs-impl/) reflects the latest changes within the repository.
## Free, Based On Open Standards, using ROME
* [ScheduleWorld](http://www.scheduleworld.com/)
* [FeedPod](http://feedpod.dev.java.net/)
## Commercial using ROME
* [Interactive Brokers TraderWorkstation (TWS)](http://interactivebrokers.com/)
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.
* [parss](http://weblogs.at/parss/stories/2315/)
From the antville guys, that we met at blogtalk 1.0 2 years ago.
* [Public Interactive](http://www.publicinteractive.com/)
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.
* [Blog\-City Ltd](http://www.blog-city.com/)
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.
* [Reger.com](http://www.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!
* [CNET Networks/TechRepublic.com](http://techrepublic.com.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.
* [Edmunds.com Inside Line](http://www.edmunds.com/insideline/)
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 [Townhall](http://townhall-talk.edmunds.com/) produces RSS feeds which we then parse using ROME on our [Inside Line](http://www.edmunds.com/insideline) property. Rome has significantly speed up our development times thanks to its clean object model and its ability to generate multiple feed types.
* [HBO Podcasts](http://phobos.apple.com/WebObjects/MZStore.woa/wa/viewArtist?artistId=118405710) (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
* [DressUpYourWedding](http://www.dressupyourwedding.com/Article.do)
## Sites using ROME
* [Yabot](http://www.yabot.net/)
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/)
* [WASALive](http://www.wasalive.com/)
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 [Russian](http://ru.wasalive.com/), [French](http://fr.wasalive.com/),[Spanish](http://es.wasalive.com/), [English](http://en.wasalive.com/)
* [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
* [The Open Source Zone](http://oszone.org/)
Rome is used to power the [Planet](http://oszone.org/channels) 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.
* [rel8r.com](http://www.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
* [NewsRack](http://newsrack.in/)
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.
* [Geonames RSS to GeoRSS](http://www.geonames.org/rss-to-georss-converter.html)
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.
* [feedarea.de](http://www.feedarea.de/)
FeedArea.de is a RSS, Atom and Podcast portal using Rome for handling the feed submissions.
* [podblock.de](http://www.podblock.de/) / [podblock.com](http://www.podblock.com/)
PodBlock is a podcast portal using Rome for handling the feed submissions.
* [javaMix.co.uk](http://www.javamix.co.uk/)
javaMix is a java news aggregation website using Rome to find the news.
* [JavaMix](http://www.javamix.co.uk/)
the latest java news, articles and resources
* [Wirecatch](http://wirecatch.com/)
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.
* [Swift](http://swiftmob.com/)
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.
* [DevMeat](http://devmeat.com/)
DevMeat deliver fresh meat for software developers and Rome is TOP cook !
* [Folder2Feed](http://folder2feed.nogoodatcoding.com/)
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.
* [podcast.tv](http://www.podcast.tv/)
* [podcast.it](http://www.podcast.it/)
* [podcast.at](http://www.podcast.at/)
Podcast.tv, podcast.it and podcast.at are podcast directories using Rome for handling the feed submissions and parsing.
* [CollaborationToday.info](http://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.

56
src/site/markdown/rome/ROMEAndMaven2.md Normal file
View file

@ -0,0 +1,56 @@
# ROME and Maven 2
this page is not up to date
Starting with ROME 1.0 RC2, rome jars are deployed on the [java.net maven repository](http://download.java.net/maven/2/).
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

13
src/site/markdown/rome/ROMEAndOSGI.md Normal file
View file

@ -0,0 +1,13 @@
# 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 [Issue 118](http://java.net/jira/browse/ROME-118) for further information.
\-\- Main.nicklothian \- 08 Jan 2009

21
src/site/markdown/rome/ROMEDevelopmentProcess.md Normal file
View file

@ -0,0 +1,21 @@
# ROME Development Process
We're welcoming our first external developer, [Nick Lothian](http://www.mackmo.com/nick/blog/) 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 [RomeChangesLog](ChangeLog.html)
* I think that's it: Welcome to Rome
\-\- [PatrickChanezon](http://wiki.java.net/twiki/bin/view/Main/PatrickChanezon) \- 17 Jun 2004

428
src/site/markdown/rome/ROMEDevelopmentProposals/ROME21stProposalJune10th2006NOTCURRENT.md Normal file
View file

@ -0,0 +1,428 @@
# 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

434
src/site/markdown/rome/ROMEDevelopmentProposals/ROME22ndProposalJuly18th2006CURRENT.md Normal file
View file

@ -0,0 +1,434 @@
# 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.

54
src/site/markdown/rome/ROMEDevelopmentProposals/ROMEFeatureRequests.md Normal file
View file

@ -0,0 +1,54 @@
# 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](../../opml/index.html) parser also.
**_This is already supported by Rome_**. RSS2.0 parser, see [Date Elements mapping](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html) by default does not process Modules. Refer to the Modules Plugins documentation to see how to enable this.
* [RFC3229](http://bobwyman.pubsub.com/main/2004/09/implementations.html) support (in [RomeFetcher](../../fetcher/index.html) 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 [Mark Pilgrim](http://diveintomark.org/projects/feed_parser/) 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.

28
src/site/markdown/rome/ROMEDevelopmentProposals/index.md Normal file
View file

@ -0,0 +1,28 @@
# ROME Development Proposals
## ROME Development Proposals
Link to new ROME feature and release proposals here.
## ROME2 Proposal
* [../ROMEROADMAPProposed.html](../ROMEROADMAPProposed.html)
* [ROME2 first proposal ](ROME21stProposalJune10th2006NOTCURRENT.html) (Jun/10/2006).
* [ROME2 second proposal ](ROME22ndProposalJuly18th2006CURRENT.html) (Jul/18/2006).
## Requests for Enhancement (RFEs)
* [Issue tracking system](https://rometools.jira.com/browse/ROME) \- file RFEs here
* [Feature Requests](ROMEFeatureRequests.html) \- old feature request page

84
src/site/markdown/rome/ROMEROADMAPProposed.md Normal file
View file

@ -0,0 +1,84 @@
# ROME ROADMAP (Proposed)
<table>
<tbody>
<tr> <th>
version
</th><th>
changes
</th></tr>
<tr><td>
1.1
</td><td>
Omnibus release with ROME patches \+ JDK 1.5 changes.
</td></tr>
<tr><td>
1.5
</td><td>
Migration to org.rometools (light break compat)
</td></tr>
<tr><td>
1.6
</td><td>
Elimination of Synd\* interfaces and Synd\*Impl in favor of base objects (break compat)
</td></tr>
<tr><td>
1.7
</td><td>
Introduction of "Rome" class with pass\-by\-ref context for modules
</td></tr>
<tr><td>
1.8
</td><td>
Addition of a factory by package for the Rome class.
</td></tr>
<tr><td>
1.9
</td><td>
JSR\-330   remix of the Rome class and all deps.
</td></tr>
</tbody>
</table>
## Old Development Proposals
* [ROMEDevelopmentProposals/ROME22ndProposalJuly18th2006CURRENT.html](ROMEDevelopmentProposals/ROME22ndProposalJuly18th2006CURRENT.html)
* [ROMEDevelopmentProposals/ROME21stProposalJune10th2006NOTCURRENT.html](ROMEDevelopmentProposals/ROME21stProposalJune10th2006NOTCURRENT.html)

81
src/site/markdown/rome/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1HowToBuildAndRunTheTutorialsSampleCode.md Normal file
View file

@ -0,0 +1,81 @@
# 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

158
src/site/markdown/rome/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.md Normal file
View file

@ -0,0 +1,158 @@
# 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();
}
}
}
```

93
src/site/markdown/rome/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.md Normal file
View file

@ -0,0 +1,93 @@
# 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();
}
}
}
```

81
src/site/markdown/rome/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1TutorialUsingRomeToReadASyndicationFeed.md Normal file
View file

@ -0,0 +1,81 @@
# 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();
}
}
}
```

17
src/site/markdown/rome/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/index.md Normal file
View file

@ -0,0 +1,17 @@
# 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. [Using Rome to read a syndication feed](RomeV0.1TutorialUsingRomeToReadASyndicationFeed.html)
1. [Using Rome to convert a syndication feed from one type to another](RomeV0.1TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html)
1. [Using Rome to aggregate many syndication feeds into a single one](RomeV0.1TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html)
For instructions on how to build and run the samples used in the tutorials [click here](RomeV0.1HowToBuildAndRunTheTutorialsSampleCode.html).

33
src/site/markdown/rome/ROMEReleases/ROME0.1Beta/index.md Normal file
View file

@ -0,0 +1,33 @@
# ROME 0.1 Beta
## Dependencies
* J2SE 1.4\+ (Not J2SE 1.3\+ as it was initially documented)
* [JDOM Beta 10](http://www.jdom.org/)
* [Jakarta Commons Codec 1.2](http://jakarta.apache.org/commons/codec/)
* Rome v0.1 does not depend on Xerces as it was initially documented
## Downloads
## Additional Information
* [Tutorials](RomeV0.1Tutorials/index.html)
## 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

144
src/site/markdown/rome/ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/RomeV0.2TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.md Normal file
View file

@ -0,0 +1,144 @@
# 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();
}
}
}
```

100
src/site/markdown/rome/ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/RomeV0.2TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.md Normal file
View file

@ -0,0 +1,100 @@
# 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();
}
}
}
```

88
src/site/markdown/rome/ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/RomeV0.2TutorialUsingRomeToReadASyndicationFeed.md Normal file
View file

@ -0,0 +1,88 @@
# 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();
}
}
}
```

17
src/site/markdown/rome/ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/index.md Normal file
View file

@ -0,0 +1,17 @@
# 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. [Using Rome to read a syndication feed](RomeV0.2TutorialUsingRomeToReadASyndicationFeed.html)
1. [Using Rome to convert a syndication feed from one type to another](RomeV0.2TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html)
1. [Using Rome to aggregate many syndication feeds into a single one](RomeV0.2TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html)
The instructions for building and running the samples are identical to the [instructions for Rome v0.1](../../ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1HowToBuildAndRunTheTutorialsSampleCode.html).

29
src/site/markdown/rome/ROMEReleases/ROME0.2Beta/index.md Normal file
View file

@ -0,0 +1,29 @@
# ROME 0.2 Beta
## Dependencies
* J2SE 1.4\+
* [JDOM Beta 10](http://www.jdom.org/)
## Downloads
## Aditional Information
* [Tutorials](RomeV0.2Tutorials/index.html)
* Changes Log
## Known Issues
* Same issues as Rome v0.1

81
src/site/markdown/rome/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3HowToBuildAndRunTheTutorialsSampleCode.md Normal file
View file

@ -0,0 +1,81 @@
# 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)

368
src/site/markdown/rome/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialDefiningACustomModuleBeanParserAndGenerator.md Normal file
View file

@ -0,0 +1,368 @@
# 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

150
src/site/markdown/rome/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.md Normal file
View file

@ -0,0 +1,150 @@
# 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();
}
}
}
```

105
src/site/markdown/rome/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.md Normal file
View file

@ -0,0 +1,105 @@
# 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();
}
}
}
```

205
src/site/markdown/rome/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToCreateAndWriteASyndicationFeed.md Normal file
View file

@ -0,0 +1,205 @@
# 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();
}
}
}
```

93
src/site/markdown/rome/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToReadASyndicationFeed.md Normal file
View file

@ -0,0 +1,93 @@
# 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();
}
}
}
```

21
src/site/markdown/rome/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/index.md Normal file
View file

@ -0,0 +1,21 @@
# 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. [Using Rome to read a syndication feed](RomeV0.3TutorialUsingRomeToReadASyndicationFeed.html)
1. [Using Rome to convert a syndication feed from one type to another](RomeV0.3TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html)
1. [Using Rome to aggregate many syndication feeds into a single one](RomeV0.3TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html)
1. [Using Rome to create and write a feed](RomeV0.3TutorialUsingRomeToCreateAndWriteASyndicationFeed.html) **_(New)_**
1. [Defining a Custom Module bean, parser and generator](RomeV0.3TutorialDefiningACustomModuleBeanParserAndGenerator.html) **_(New)_**
For instructions on how to build and run the samples used in the tutorials [click here](RomeV0.3HowToBuildAndRunTheTutorialsSampleCode.html).

33
src/site/markdown/rome/ROMEReleases/ROME0.3Beta/index.md Normal file
View file

@ -0,0 +1,33 @@
# ROME 0.3 Beta
## Dependencies
* J2SE 1.4\+
* [JDOM Beta 10](http://www.jdom.org/)
## Downloads
## Additional Information
* [Tutorials](RomeV0.3Tutorials/index.html) (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 [BOM](http://www.unicode.org/faq/utf_bom.html#BOM) the JAXP SAX parser may fail, using [Xerces 2.6.2](http://xml.apache.org/xerces2-j) addresses the problem.

85
src/site/markdown/rome/ROMEReleases/ROME0.4Beta/RomeV0.4Tutorials/RomeV0.4HowToBuildAndRunTheTutorialsSampleCode.md Normal file
View file

@ -0,0 +1,85 @@
# 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)

243
src/site/markdown/rome/ROMEReleases/ROME0.4Beta/RomeV0.4Tutorials/RomeV0.4TutorialUsingRomeWithinAServletToCreateAndReturnAFeed.md Normal file
View file

@ -0,0 +1,243 @@
# 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 [Using Rome to create and write a feed](../../../HowRomeWorks/RomeV0.4TutorialUsingRomeToCreateAndWriteASyndicationFeed.html) 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.

23
src/site/markdown/rome/ROMEReleases/ROME0.4Beta/RomeV0.4Tutorials/index.md Normal file
View file

@ -0,0 +1,23 @@
# 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. [Using Rome to read a syndication feed](../../../HowRomeWorks/RomeV0.4TutorialUsingRomeToReadASyndicationFeed.html)
1. [Using Rome to convert a syndication feed from one type to another](../../../HowRomeWorks/RomeV0.4TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html)
1. [Using Rome to aggregate many syndication feeds into a single one](../../../HowRomeWorks/RomeV0.4TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html)
1. [Using Rome to create and write a feed](../../../HowRomeWorks/RomeV0.4TutorialUsingRomeToCreateAndWriteASyndicationFeed.html)
1. [Defining a Custom Module bean, parser and generator](../../../HowRomeWorks/RomeV0.4TutorialDefiningACustomModuleBeanParserAndGenerator.html)
1. [Using Rome within a Servlet to create and return a feed](RomeV0.4TutorialUsingRomeWithinAServletToCreateAndReturnAFeed.html) **_(NEW)_**
For instructions on how to build and run the samples used in the tutorials [click here](RomeV0.4HowToBuildAndRunTheTutorialsSampleCode.html).

68
src/site/markdown/rome/ROMEReleases/ROME0.4Beta/index.md Normal file
View file

@ -0,0 +1,68 @@
# 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\+
* [JDOM 1.0](http://www.jdom.org/)
## Downloads
## Additional Information
* [Tutorials](RomeV0.4Tutorials/index.html)
* [Changes Log](../../ChangeLog.html)
* Inside ROME, How Things Work
* [How ROME Works](../../HowRomeWorks/index.html), Understanding Rome (a detailed overview by Dave Johnson)
* [Rome common Package](../../HowRomeWorks/UnderstandingTheRomeCommonClassesAndInterfaces.html), bean utilities, enums, copying and clonning
* [ROME Plugins Mechanism](../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEPluginsMechanism.html), bootstrap, adding and changing parsers, generators, converters and modules
* [Feeds Date Elements](../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html), how Date data is mapped to SyndFeed and SyndEntry
* [Feed and Entry URI Mapping](../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.html), how SyndFeed and SyndEntry 'uri' properties map to concrete feed elements
* [XML Charset Encoding Detection](../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.html), how Rome helps getting the right charset encoding
## Known Issues
None.

21
src/site/markdown/rome/ROMEReleases/ROME0.5Beta/ROMET-Shirt.md Normal file
View file

@ -0,0 +1,21 @@
# 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
\-\- [PatrickChanezon](http://wiki.java.net/twiki/bin/view/Main/PatrickChanezon) \- 10 Jan 2005

68
src/site/markdown/rome/ROMEReleases/ROME0.5Beta/index.md Normal file
View file

@ -0,0 +1,68 @@
# 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](ROMET-Shirt.html)
## Dependencies
* J2SE 1.4\+
* [JDOM 1.0](http://www.jdom.org/)
## Downloads
## Additional Information
* [Tutorials](../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/index.html)
* [Changes Log](../../ChangeLog.html)
* Inside ROME, How Things Work
* [How ROME Works](../../HowRomeWorks/index.html), Understanding ROME, a detailed overview by Dave Johnson (This doc is based on ROME v0.4)
* [ROME Plugins Mechanism](../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEPluginsMechanism.html), bootstrap, adding and changing parsers, generators, converters and modules
* [Feeds Date Elements](../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html), how Date data is mapped to SyndFeed and SyndEntry
* [Feed and Entry URI Mapping](../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.html), how SyndFeed and SyndEntry 'uri' properties map to concrete feed elements
* [XML Charset Encoding Detection](../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.html), how ROME helps getting the right charset encoding
* [Creating a custom Module](../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialDefiningACustomModuleBeanParserAndGenerator.html), creating all necessary pieces, bean, parser and generator
* [The CopyFrom interface](../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/TheCopyFromInterface.html)
* Implementation documents
* [ROME bean utilities, equals, toString and clonning](../../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/UnderstandingRssAndAtOMUtilitiEsROMEBeanUtilities.html)
## Known Issues
None.

64
src/site/markdown/rome/ROMEReleases/ROME0.6Beta.md Normal file
View file

@ -0,0 +1,64 @@
# 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\+
* [JDOM 1.0](http://www.jdom.org/)
## Downloads
## Additional Information
* [Tutorials](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/index.html)
* [Changes Log](../ChangeLog.html)
* Inside ROME, How Things Work
* [How ROME Works](../HowRomeWorks/index.html), Understanding ROME, a detailed overview by Dave Johnson (This doc is based on ROME v0.4)
* [ROME Plugins Mechanism](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEPluginsMechanism.html), bootstrap, adding and changing parsers, generators, converters and modules
* [Feeds Date Elements](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html), how Date data is mapped to SyndFeed and SyndEntry
* [Feed and Entry URI Mapping](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.html), how SyndFeed and SyndEntry 'uri' properties map to concrete feed elements
* [XML Charset Encoding Detection](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.html), how ROME helps getting the right charset encoding
* [Creating a custom Module](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialDefiningACustomModuleBeanParserAndGenerator.html), creating all necessary pieces, bean, parser and generator
* [The CopyFrom interface](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/TheCopyFromInterface.html)
* Implementation documents
* [ROME bean utilities, equals, toString and clonning](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/UnderstandingRssAndAtOMUtilitiEsROMEBeanUtilities.html)
## Known Issues
None.

66
src/site/markdown/rome/ROMEReleases/ROME0.7Beta.md Normal file
View file

@ -0,0 +1,66 @@
# 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\+
* [JDOM 1.0](http://www.jdom.org/)
## Downloads
## Additional Information
* [Tutorials](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/index.html)
* [Changes Log](../ChangeLog.html)
* Inside ROME, How Things Work
* [How ROME Works](../HowRomeWorks/index.html), Understanding ROME, a detailed overview by Dave Johnson (This doc is based on ROME v0.4)
* [ROME Plugins Mechanism](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEPluginsMechanism.html), bootstrap, adding and changing parsers, generators, converters and modules
* [Feeds Date Elements](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html), how Date data is mapped to SyndFeed and SyndEntry
* [Feed and Entry URI Mapping](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.html), how SyndFeed and SyndEntry 'uri' properties map to concrete feed elements
* [XML Charset Encoding Detection](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.html), how ROME helps getting the right charset encoding
* [Creating a custom Module](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialDefiningACustomModuleBeanParserAndGenerator.html), creating all necessary pieces, bean, parser and generator
* [The CopyFrom interface](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/TheCopyFromInterface.html)
* [ROME bean utilities, equals, toString and clonning](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/UnderstandingRssAndAtOMUtilitiEsROMEBeanUtilities.html)
* [Customizing Date and time parsing](../RssAndAtOMUtiliEsROMEV0.7DateAndTimeParsing.html) in the rome.properties file **NEW**
## Known Issues
None.

74
src/site/markdown/rome/ROMEReleases/ROME0.8Beta.md Normal file
View file

@ -0,0 +1,74 @@
# 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 [RFC 4287](http://www.ietf.org/rfc/rfc4287): 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\+
* [JDOM 1.0](http://www.jdom.org/)
## Downloads
## Additional Information
* [Tutorials](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/index.html)
* [Changes Log](../ChangeLog.html)
* Inside ROME, How Things Work
* [How ROME Works](../HowRomeWorks/index.html), Understanding ROME, a detailed overview by Dave Johnson (This doc is based on ROME v0.4)
* [ROME Plugins Mechanism](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEPluginsMechanism.html), bootstrap, adding and changing parsers, generators, converters and modules
* [Feeds Date Elements](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html), how Date data is mapped to SyndFeed and SyndEntry
* [Feed and Entry URI Mapping](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.html), how SyndFeed and SyndEntry 'uri' properties map to concrete feed elements
* [XML Charset Encoding Detection](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.html), how ROME helps getting the right charset encoding
* [Creating a custom Module](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialDefiningACustomModuleBeanParserAndGenerator.html), creating all necessary pieces, bean, parser and generator
* [The CopyFrom interface](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/TheCopyFromInterface.html)
* [ROME bean utilities, equals, toString and clonning](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/UnderstandingRssAndAtOMUtilitiEsROMEBeanUtilities.html)
* [Customizing Date and time parsing](../RssAndAtOMUtiliEsROMEV0.7DateAndTimeParsing.html) in the rome.properties file **NEW**
## Known Issues
None.
\-\- [PatrickChanezon](http://wiki.java.net/twiki/bin/view/Main/PatrickChanezon) \- 02 Feb 2006

72
src/site/markdown/rome/ROMEReleases/ROME0.9Beta.md Normal file
View file

@ -0,0 +1,72 @@
# 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\+
* [JDOM 1.0](http://www.jdom.org/)
## Downloads
## Additional Information
* [Tutorials](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/index.html)
* [Changes Log](../ChangeLog.html)
* Inside ROME, How Things Work
* [How ROME Works](../HowRomeWorks/index.html), Understanding ROME, a detailed overview by Dave Johnson (This doc is based on ROME v0.4)
* [ROME Plugins Mechanism](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEPluginsMechanism.html), bootstrap, adding and changing parsers, generators, converters and modules
* [Feeds Date Elements](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html), how Date data is mapped to SyndFeed and SyndEntry
* [Feed and Entry URI Mapping](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.html), how SyndFeed and SyndEntry 'uri' properties map to concrete feed elements
* [XML Charset Encoding Detection](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.html), how ROME helps getting the right charset encoding
* [Creating a custom Module](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialDefiningACustomModuleBeanParserAndGenerator.html), creating all necessary pieces, bean, parser and generator
* [The CopyFrom interface](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/TheCopyFromInterface.html)
* [ROME bean utilities, equals, toString and clonning](../RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/UnderstandingRssAndAtOMUtilitiEsROMEBeanUtilities.html)
* [Customizing Date and time parsing](../RssAndAtOMUtiliEsROMEV0.7DateAndTimeParsing.html) in the rome.properties file **NEW**
## Known Issues
None.
\-\- Main.snoopdave \- 06 Dec 2006

42
src/site/markdown/rome/ROMEReleases/ROME1.0RC1.md Normal file
View file

@ -0,0 +1,42 @@
# 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 [change log](../ChangeLog.html)
## Dependencies
* J2SE 1.4\+
* [JDOM 1.0](http://www.jdom.org/)
## Downloads
### Documentation
* [Javadocs](http://rome.dev.java.net/apidocs/1_0RC1/overview-summary.html)

35
src/site/markdown/rome/ROMEReleases/ROME1.0RC2.md Normal file
View file

@ -0,0 +1,35 @@
# ROME 1.0 RC2
## What is New, Highlights
* ROME is now [built using Maven 2](../HowToBuildRome.html)
* ROME jars are now available in the [java.net Maven repository](../ROMEAndMaven2.html)
* More lenient handling of Number formats during parsing
* Better date parsing for Atom dates
* Complete details in the [change log](../ChangeLog.html)
## Dependencies
* [J2SE](http://wiki.java.net/twiki/bin/view/Javawsxml/J2SE) 1.4\+
* [JDOM 1.0](http://www.jdom.org/)
## Downloads
## Documentation
* [Javadocs](http://rome.dev.java.net/apidocs/1_0RC2/overview-summary.html)

40
src/site/markdown/rome/ROMEReleases/ROME1.0Release.md Normal file
View file

@ -0,0 +1,40 @@
# 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](../PreservingWireFeeds.html) for further details
* Complete details in the [change log](../ChangeLog.html)
### Downloads
### Dependencies
* J2SE 1.4\+
* [JDOM 1.0](http://www.jdom.org/)
### Documentation
* [Javadocs](http://rome.dev.java.net/apidocs/1_0/overview-summary.html)

135
src/site/markdown/rome/ROMEReleases/index.md Normal file
View file

@ -0,0 +1,135 @@
# ROME Releases
<table>
<tbody>
<tr> <th>
Version
</th><th>
Release Date
</th></tr>
<tr><td>
[ROME 1.0](ROME1.0Release.html)
</td><td>
March 12, 2009
</td></tr>
<tr><td>
[Rome v1.0 RC2](ROME1.0RC2.html)
</td><td>
Jan 9, 2009
</td></tr>
<tr><td>
[Rome v1.0 RC1](ROME1.0RC1.html)
</td><td>
Jul 16, 2007
</td></tr>
<tr><td>
[Rome v0.9 Beta](ROME0.9Beta.html)
</td><td>
Dec 11, 2006
</td></tr>
<tr><td>
[Rome v0.8 Beta](ROME0.8Beta.html)
</td><td>
Feb 01, 2006
</td></tr>
<tr><td>
[Rome v0.7 Beta](ROME0.7Beta.html)
</td><td>
Sep 09, 2005
</td></tr>
<tr><td>
[Rome v0.6 Beta](ROME0.6Beta.html)
</td><td>
Apr 01, 2005
</td></tr>
<tr><td>
[Rome v0.5 Beta](ROME0.5Beta/index.html)
</td><td>
Jan 10, 2005
</td></tr>
<tr><td>
[Rome v0.4 Beta](ROME0.4Beta/index.html)
</td><td>
Sep 27, 2004
</td></tr>
<tr><td>
[Rome v0.3 Beta](ROME0.3Beta/index.html)
</td><td>
Jul 28, 2004
</td></tr>
<tr><td>
[Rome v0.2 Beta](ROME0.2Beta/index.html)
</td><td>
Jun 16, 2004
</td></tr>
<tr><td>
[Rome v0.1 Beta](ROME0.1Beta/index.html)
</td><td>
Jun 08, 2004
</td></tr>
</tbody>
</table>

142
src/site/markdown/rome/RomeAPIFAQ.md Normal file
View file

@ -0,0 +1,142 @@
# 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, [Dublin Core](http://purl.org/rss/1.0/modules/dc/) and [Syndication](http://purl.org/rss/1.0/modules/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

112
src/site/markdown/rome/RomeV0.4FeedAndEntryURIMapping.md Normal file
View file

@ -0,0 +1,112 @@
# 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...

40
src/site/markdown/rome/RssAndAtOMUtiliEsROMEV0.7DateAndTimeParsing.md Normal file
View file

@ -0,0 +1,40 @@
# 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.

108
src/site/markdown/rome/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.md Normal file
View file

@ -0,0 +1,108 @@
# 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.

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