Issue 121: RSS item category iteration should try to reflect document order
+
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 Preserving WireFeeds (rome) for details.
+
+
Changes made since v1.0RC1
+
+
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
+
+
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.
+
Fix. Contributors properties in SyndEntry and SyndFeed were not being converted to/from WireFeed
+
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
+
New. Added new constructor to XmlReader
+
+
+public XmlReader(InputStream is, boolean lenient, String defaultEncoding)
+
+
New. Support atom person construct extensions, using the Extendable interface on SyndPerson: Patch from James Roper. See Issue 1101 for details
+
New. Maven 2 build for main project ROME can now be built with Maven 2
+
New. OSGi support OSGi headers to MANIFEST.MF so that rome.jar can also be used in an OSGi environment. See Issue 117 for details.
+
New. Allow pretty printing to be turned on and off see Issue 114 for details. Thanks to Martin Kurz for the patch.
+
Configurable classloading behavior for OSGi compatibility. We have received a report of some issues with plugin loading in an OSGi environment (Issue 118). The fix appears to be to change Class.forName to classLoader.loadClass, but the semantics for this are subtly different, so we have made this new behavior user selectable. Set the "rome.pluginmanager.useloadclass" system property to "true" to enable it.
+
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, 107 and 108 for details.
+
+
Changes made from v0.9 to v1.0RC1
+
+
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().
+
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.
+
Fix. XmlReader, multi-line prolog encoding detection. XmlReader handles properly xml-prolog detection when prolog goes over multiple lies (such as G groups feeds).
+
Fix. Base64 decoding was failing under certain padding conditions.
+
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).
+
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.
+
Fix. Making the EqualsBean to follow equals contract. For X.equals(null) it was throwing a NullPointerException, now it returns FALSE.
+
Fix. Render Atom icon and logo attributes. AtomGenerator now adds icon and logo elements to xml tree
+
Fix. Updated AtomPub namespace to its permenent home. AtomService namespace updated to http://www.w3.org/2007/app
+
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.
+
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()
+
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()
+
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
+
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.
+
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.
+
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.
+
New. XmlReader handling content-type charset values has been relaxed. XmlReader handles content-type charset encoding value within single quotes and double quotes.
+
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.
+
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.
+
Fix. WireFeedInput throws IllegalArgumentException if the feed type is not recognized. Previously the IllegalArgumentException was wrapped by a ParsingFeedException (Reported by Issue 91).
+
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.
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.
+
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.
+
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.
+
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..."
+
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
+
+
Design changes
+
+
Support Atom feed.title, feed.subtitle and entry.title Issue 48 #48 fixed via better support for Atom text constructs title and subtitle. Added get/setTitleEx() and get/setSubtitleEx(), which get get SyndContent objects. Title and subtitle still available from old getters/setters.
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
+
General parsing fixes
+
+
XmlReader xml prolog regular expression does not allow for single quotes Issue 36 The XmlReader was only parsing prolog encodings within double quotes, the regular expression to detect the encoding has been change to detect single or double quotes.
+
Fix. XML prolog parsing now support whitespaces around '=' If the XML prolog contained spaces around the '=' between the encoding attribute name and the encoding attribute value the encoding was not being detected. The fix accepts all valid whitespace characters (as defined in the XML spec).
+
RSS parser does not recognize version="2.00" Issue 33
Fix. Wrong default description type for RSS 2.0 Fix for Issue 26
+
Change default description type for RSS 2.0 from text/plain to text/html as per RSS 2.0 spec
+
Fix to add all HTML4 entities, according to http://www.w3.org/TR/REC-html40/sgml/entities.html specially for the HTMLsymbol set (Mathematical, Greek and Symbolic characters for HTML) and the HTMLspecial set (Special characters for HTML).
+
Date parsing fixes
+
+
Additional version and date leniency could extract more information Issue 24
+
Non RFC822 Dates not processed in RSS pubDate field Issue 27
+
+
RSS feed parsers were were only parsing RFC822 dates because they were not using the proper date-time parsing function for the date-time elements.
+
If a W3C date-time element had no time component it was being parsed as local time instead of GMT, ROME DateParser class has been modified to use GMT in this situation.
+
Current JDKs do not handle 'UT' timezone indicator, ROME DateParser class has been modified to handle it.
Atom 1.0 Date (Updated or Published) Not Set Issue 42
+
lastBuildDate does not populate publishedDate Issue 43 Provides a feed date for RSS 0.91 feeds that specify lastBuildDate but not pubDate.
+
Fix. Parsing some numeric elements was failing due to whitespaces The image.width and image.height of RSS091U, the frequency of SyModule and the cloud.port of RSS092 elements are now being trimmed before doing the integer parsing.
+
Atom link and URI fixes
+
+
Improper relative link resolution in Atom10Parser Issue 37
Slash module not serializable for FeedFetcher Issue 44
+
+
Changes made from v0.7 to v0.8
+
+
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.
+
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.
+
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.
+
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)
+
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
+
+
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.
+
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.
+
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.
+
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.
+
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.
+
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).
+
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.
+
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.
+
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.
+
Fix. RFC-822 2 digit years Previously RFC-822 dates did not work correctly with 2 digit years. This is now fixed.
+
Fix. No alternate link causes IndexOutOfBoundsException Fix bug where no alternate link causes IndexOutOfBoundsException in ConverterForAtom03 (Thanks to Joseph Van Valen).
+
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.
+
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) -- all "=" after the first one would disappear.
+
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
+
+
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'.
+
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.
+
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.
+
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.
+
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.
+
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.
+
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.
+
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.
+
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.
+
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).
+
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.
+
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.
+
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.
+
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.
+
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
+
+
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.
+
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.
+
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.
+
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.
+
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.
+
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.
+
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
+
+
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.
+
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.
+
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.
+
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.
+
Change. Ant 'build.xml' files have been improved The build.xml were re-written instead just using the Maven generated ones.
+
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.
+
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).
+
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.
+
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.
+
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.
+
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.
+
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.
+
Change. Refactored private CopyFrom helper class It was com.sun.syndication.feed.synd.impl.SyndCopyFrom now it is com.sun.syndication.common.impl.CopyFromHelper.
+
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.
+
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.
+
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.
+
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.
+
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.
+
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.
+
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).
+
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.
+
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
+
Rome now uses JDOM 1.0 Dependencies have been updated to use JDOM 1.0. No code changes were needed because of this.
+
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.
+
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 for a full explanation.
+
Addition. New sample, FeedServlet Added a new sample, FeedServlet. This servlet creates a feed and returns a feed.
+
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
+
+
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).
+
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.
+
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.
+
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.
+
Changed some implementation (hidden) class names Some typos corrections and adding consistency to the naming.
+
Added Fetcher module Added a HTTP fetcher with conditional get and gzip support (See modules/fetcher)
+
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
+
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).
+
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.
+
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.
+
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.
+
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.
+
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
+
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
+
Change/Fix. ToStringBean, works on defined class Same as #14 but on ToStringBean instead EqualsBean
+
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.
+
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.
+
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.
+
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.
+
New Sample and tutorial for creating a feed A new sample and tutorial that creates and writes a feed has been added.
+
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
+
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
+
+
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.
+
FeedOutput and SyndOutput outputW3CDom() method typo correction Fixed typo in outputW3CDom() method, it was ouptutW3CDom().
+
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.
+
Renamed SyndFeed createRealFeed(feedType) method to createWireFeed(feedType) For consistency with change #3
+
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.
+
WireFeed, renamed type property to feedType For consistency with #5. Also it's more clear what the type is about.
+
Overloaded SyndFeed createRealFeed() with a no parameter signature
+
FeedOutput, removed feed type from constructor It now uses the WireFeed feedType property.
+
SyndOutput, removed feed type from constructor It now uses the SyndFeed feedType property define in #5.
+
FeedOutput, removed getType() method Now FeedOutput uses the WireFeed feedType property.
+
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).
+
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.
+
Renamed syndication.io classes/interfaces Renaming for naming consistency and to reflect on what type of feed they work on.
+
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).
+
Added samples to the Rome project directory structure Rome samples are a sub-project located at rome/modules/sample.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/HowRomeWorks/HowRomeWorks.png b/HowRomeWorks/HowRomeWorks.png
new file mode 100644
index 0000000..ef677ce
Binary files /dev/null and b/HowRomeWorks/HowRomeWorks.png differ
diff --git a/HowRomeWorks/RomeV0.4TutorialDefiningACustomModuleBeanParserAndGenerator.html b/HowRomeWorks/RomeV0.4TutorialDefiningACustomModuleBeanParserAndGenerator.html
new file mode 100644
index 0000000..d3ff0a7
--- /dev/null
+++ b/HowRomeWorks/RomeV0.4TutorialDefiningACustomModuleBeanParserAndGenerator.html
@@ -0,0 +1,382 @@
+
+
+
+
+
+ ROME - Rome v0.4 Tutorial, Defining a Custom Module (bean, parser and generator)
+
+
+
+
+
+
+
+
+
+
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 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.
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 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 topic.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/HowRomeWorks/RomeV0.4TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html b/HowRomeWorks/RomeV0.4TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html
new file mode 100644
index 0000000..c44e5f9
--- /dev/null
+++ b/HowRomeWorks/RomeV0.4TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html
@@ -0,0 +1,223 @@
+
+
+
+
+
+ ROME - Rome v0.4 Tutorial, Using Rome to aggregate many syndication feeds into a single one
+
+
+
+
+
+
+
+
+
+
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:
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:
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();
+ }
+ }
+
+}
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/HowRomeWorks/RomeV0.4TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html b/HowRomeWorks/RomeV0.4TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html
new file mode 100644
index 0000000..e1c4cfa
--- /dev/null
+++ b/HowRomeWorks/RomeV0.4TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html
@@ -0,0 +1,191 @@
+
+
+
+
+
+ ROME - Rome v0.4 Tutorial, Using Rome to convert a syndication feed from one type to another
+
+
+
+
+
+
+
+
+
+
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:
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();
+ }
+ }
+
+}
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/HowRomeWorks/RomeV0.4TutorialUsingRomeToCreateAndWriteASyndicationFeed.html b/HowRomeWorks/RomeV0.4TutorialUsingRomeToCreateAndWriteASyndicationFeed.html
new file mode 100644
index 0000000..330887b
--- /dev/null
+++ b/HowRomeWorks/RomeV0.4TutorialUsingRomeToCreateAndWriteASyndicationFeed.html
@@ -0,0 +1,278 @@
+
+
+
+
+
+ ROME - Rome v0.4 Tutorial, Using Rome to create and write a syndication feed
+
+
+
+
+
+
+
+
+
+
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:
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();
+ }
+ }
+
+}
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/HowRomeWorks/RomeV0.4TutorialUsingRomeToReadASyndicationFeed.html b/HowRomeWorks/RomeV0.4TutorialUsingRomeToReadASyndicationFeed.html
new file mode 100644
index 0000000..3f045ce
--- /dev/null
+++ b/HowRomeWorks/RomeV0.4TutorialUsingRomeToReadASyndicationFeed.html
@@ -0,0 +1,181 @@
+
+
+
+
+
+ ROME - Rome v0.4 Tutorial, Using Rome to read a syndication feed
+
+
+
+
+
+
+
+
+
+
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:
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();
+ }
+ }
+
+}
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/HowRomeWorks/UnderstandingTheRomeCommonClassesAndInterfaces.html b/HowRomeWorks/UnderstandingTheRomeCommonClassesAndInterfaces.html
new file mode 100644
index 0000000..f611606
--- /dev/null
+++ b/HowRomeWorks/UnderstandingTheRomeCommonClassesAndInterfaces.html
@@ -0,0 +1,390 @@
+
+
+
+
+
+ ROME - Understanding the Rome common classes and interfaces
+
+
+
+
+
+
+
+
+
+
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.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/HowRomeWorks/index.html b/HowRomeWorks/index.html
new file mode 100644
index 0000000..20e1525
--- /dev/null
+++ b/HowRomeWorks/index.html
@@ -0,0 +1,157 @@
+
+
+
+
+
+ ROME - How Rome works
+
+
+
+
+
+
+
+
+
+
Dave Johnson (The Roller Weblogger) has written a very nice blogHow Rome Worksdescribing (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 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.
+
You don't need to know this stuff to use Rome, but it you are interested in internals you might find it interesting.
+
+
Notes on the Rome parsing process
+
Rome is based around an idealized and abstract model of a Newsfeed or "Syndication Feed." Rome can parse any format of Newsfeed, including RSS variants and Atom, into this model. Rome can convert from model representation to any of the same Newfeed output formats.
+
Internally, Rome defines intermediate object models for specific Newsfeed formats, or "Wire Feed" formats, including both Atom and all RSS variants. For each format, there is a separate JDOM based parser class that parses XML into an intermediate model. Rome provides "converters" to convert between the intermediate Wire Feed models and the idealized Syndication Feed model.
+
Rome makes no attempt at Pilgrim-style liberal XML parsing. If a Newsfeed is not valid XML, then Rome will fail. Perhaps, as Kevin Burton suggests, parsing errors in Newsfeeds can and should be corrected. Kevin suggests that, when the parse fails, you can correct the problem and parse again. (BTW, I have some sample code that shows how to do this, but it only works with Xerces - Crimsom's SAXParserException does not have reliable error line and column numbers.)
+
Here is what happens during Rome Newsfeed parsing:
URL feedUrl = new URL("file:blogging-roller.rss");
+SyndFeedInput input = new SyndFeedInput();
+SyndFeed feed = input.build(new InputStreamReader(feedUrl.openStream()));
+
+
SyndFeedInput delegates to WireFeedInput to do the actual parsing.
+
WireFeedInput uses a PluginManager of class FeedParsers to pick the right parser to use to parse the feed and then calls that parser to parse the Newsfeed.
+
The appropriate parser parses the Newsfeed parses the feed, using JDom, into a WireFeed. If the Newsfeed is in an RSS format, the the WireFeed is of class Channel and contains Items, Clouds, and other RSS things from the com.sun.syndication.feed.rss package. Or, on the other hand, if the Newsfeed is in Atom format, then the WireFeed is of class Feed from the com.sun.syndication.atom package. In the end, WireFeedInput returns a WireFeed.
+
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.
+
SyndFeedImpl uses a Converter to convert between the format specific WireFeed representation and a format-independent SyndFeed.
+
SyndFeedInput returns to you a SyndFeed containing the parsed Newsfeed.
+
+
Other Rome features
+
Rome supports Newsfeed extension modules for all formats that also support modules: RSS 1.0, RSS 2.0, and Atom. Standard modules such as Dublic Core and Syndication are supported and you can define your own custom modules too.
+
Rome also supports Newsfeed output and for each Newsfeed format provides a "generator" class that can take a Syndication Feed model and produce from it Newsfeed XML.
+
+
Learning more
+
I've linked to a number of the Rome 0.4 Tutorials, here is the full list from the Rome Wiki:
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.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/HowToBuildRome.html b/HowToBuildRome.html
new file mode 100644
index 0000000..3893220
--- /dev/null
+++ b/HowToBuildRome.html
@@ -0,0 +1,144 @@
+
+
+
+
+
+ ROME - How to build 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. 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 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 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 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.
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 (with or without filters applied) as RSS or Atom feeds.
stat4j Used ROME to create an RSS/ATOM Log4j Appender. Read more about it here.
+
SPOT Manager SPOT Manager uses ROME to parse RSS feeds and send them to your MSN Direct wristwatch! Learn about MSN Direct here. Download the program from SPOTDev.net.
+
LogDistiller 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 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.
+
Blog Mover Blog Mover's goal is allowing your blog moving freely between each BSP(Blog Service Provider). Learn more and try it here.
+
Scarab The goal of the Scarab project is to build a highly customisable Artifact tracking system. It's distributed under a BSD/Apache style license.
+
Ozmozr Ozmozr is a website for online learning communities being developed by the Center for Open Sustainable Learning at Utah State University. In ozmozr, users are both content producers and consumers, relying on their social networks to filter and distribute meaningful content. Ozmozr was built to leverage emergent technologies and support social and collaborative information filtering, self-organization, identity development, and free/open resource-sharing.
+
+
Open Source Research Prototypes using ROME
+
+
MORSE The Model-Aware Repository and Service Environment (MORSE) is a service-based environment for the storage and retrieval of models and model-instances at both design- and runtime. Models, and model-elements are identified by Universally Unique Identifiers (UUID) and stored and managed in the MORSE repository. The MORSE repository provides versioning capabilities so that models can be manipulated at runtime and new and old versions of the models can be maintained in parallel. MORSE exposes various services to runtime clients and modeling tools. For instance, a feed reflects the latest changes within the repository.
Interactive Brokers TraderWorkstation (TWS) Interactive Brokers is leading software based broker. IB offers Universal Direct-Access Trading and sophisticated trade management tools at highly competitive costs to professional traders and investors worldwide. IB is the gateway to trading a broad array of financial instruments -- stocks, options, futures, corporate bonds as well as forex -- on over 50 exchanges and marketplaces in 14 countries. TraderWorkstation is java-based trading platform; ROME library is used to fetch, aggregate and visualize news related to securities listed in the application.
+
parss From the antville guys, that we met at blogtalk 1.0 2 years ago.
+
Public Interactive Public Interactive® is the leading integrated Application Service Provider (ASP) of on-line collaborative tools, community engagement technologies, content syndication services and member and audience relationship management systems for the public broadcasting industry. Rome is used for syndicating news content and Podcasts local published by stations in the Public Interactive network.
+
Blog-City Ltd Blog-City.com has been using ROME for many months now, utilising both the core project and the Fetcher project to allow bloggers to run their own mini-aggregators within their blog.
+
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 athttp://www.reger.com/about/specs/entrydata.rddl Thanks again for all of the help and for making ROME great!
+
CNET Networks/TechRepublic.com CNET Networks uses ROME with an application called the RSS Harvester. The purpose of this application is to harvest a list of predefined RSS/ATOM feeds, saving all new items for each feed in a database. In addition, each feed has an associated keyword that allows for easy surfacing of harvested data. Once the feed data has been collected, internal editors can surface links to the harvested data on the TechRepublic website by including a call to a JSP component. This component passes several parameters including the number of items to return, the number of items from a particular site and an associated keyword. For example, http://techrepublic.com.com/2001-10591-0.html (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 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 produces RSS feeds which we then parse using ROME on our Inside Line property. Rome has significantly speed up our development times thanks to its clean object model and its ability to generate multiple feed types.
+
HBO Podcasts (iTunes Music Store Link) HoPE (HBO Podcast Engine) powered by ROME and the iTunes Podcast module. To date has served over 15-million podcasts for HBO podcast content such as The Sopranos, Real Time with Bill Maher, and Rome
Yabot Yabot is a news service currently available in five editions (May 2008).
+
Discovering and implementing ROME made Yabot's feed aggregation faster and easier. In previous versions we rendered the XML our selves but with ROME now doing most of this work developers can focus on presentation and integration features. Thanks!
WASALive Wasalive is a news, blogs and forums search engine. Results are sort by a mix of relevancy and date. Thanks to ROME library, Wasabot fetch and parse more than 70k feeds/days and store 3M posts. Thanks to ROME UTF8 support Wasalive is avalaible in Russian, French,Spanish, English
+
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 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 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 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 Rome is used to power the Planet section of The Open Source Zone, where we aggregate the most interesting feeds concerning Open Source. Took very little to implement, thanks to Rome. Rome Fetcher is used too, which is great.
+
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 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 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 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 FeedArea.de is a RSS, Atom and Podcast portal using Rome for handling the feed submissions.
+
podblock.de / podblock.com PodBlock is a podcast portal using Rome for handling the feed submissions.
+
javaMix.co.uk javaMix is a java news aggregation website using Rome to find the news.
+
JavaMix the latest java news, articles and resources
+
Wirecatch Wirecatch is a semantic news aggregator and visualization tool. It uses Rome to grab several news feeds and show connections and relationships between names, concepts and documents.
+
Swift Swift imports rss feeds and formats them for mobile devices. Swift also include many other tools for building mobile friendly webpages that will reshape themselves for each phone so the experience for the end user is as good as possible.
+
DevMeat DevMeat deliver fresh meat for software developers and Rome is TOP cook !
+
Folder2Feed Folder2Feed allows users to generate feeds from the contents of local and network folders; providing an easy way to monitor updates to folders of interest for a large audience.
podcast.at Podcast.tv, podcast.it and podcast.at are podcast directories using Rome for handling the feed submissions and parsing.
+
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.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ROMEAndMaven2.html b/ROMEAndMaven2.html
new file mode 100644
index 0000000..ae1e81c
--- /dev/null
+++ b/ROMEAndMaven2.html
@@ -0,0 +1,126 @@
+
+
+
+
+
+ ROME - ROME and Maven 2
+
+
+
+
+
+
+
+
+
+
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 for further information.
+
-- Main.nicklothian - 08 Jan 2009
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ROMEDevelopmentProcess.html b/ROMEDevelopmentProcess.html
new file mode 100644
index 0000000..372493a
--- /dev/null
+++ b/ROMEDevelopmentProcess.html
@@ -0,0 +1,107 @@
+
+
+
+
+
+ ROME - ROME Development Process
+
+
+
+
+
+
+
+
+
+
We're welcoming our first external developer, Nick Lothian today, so we thought it would be good to set a few basic rules for this project. We don't want to be too formal, since we're still alpha, and trust our developer's common sense to "do the right thing".
+
+
Please before commiting anything send an email in the rome developer lists to explain what you want to do
+
When you create some new code, please javadoc it, and unit tests are welcome
+
If your code involves new functionality for end users, please document it on the wiki.
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:
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.
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:
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:
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:
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.
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. 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: 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 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 parser also. This is already supported by Rome. RSS2.0 parser, see Date Elements mapping by default does not process Modules. Refer to the Modules Plugins documentation to see how to enable this.
+
RFC3229 support (in RomeFetcher and example code implementing it for production) would be a killer feature.
+
The RSS 1.0 Spec http://web.resource.org/rss/1.0/spec 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 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.
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&#232;ces</FONT>
+
+
In the hope of gettin "Quatre pièces" in your html feed. You get from the SynFeedOutput.output() this:
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.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ROMEDevelopmentProposals/index.html b/ROMEDevelopmentProposals/index.html
new file mode 100644
index 0000000..2508407
--- /dev/null
+++ b/ROMEDevelopmentProposals/index.html
@@ -0,0 +1,113 @@
+
+
+
+
+
+ ROME - ROME Development Proposals
+
+
+
+
+
+
+
+
+
+
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
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html b/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html
new file mode 100644
index 0000000..7531cf6
--- /dev/null
+++ b/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html
@@ -0,0 +1,205 @@
+
+
+
+
+
+ ROME - Rome v0.1 Tutorial, Using Rome to aggregate many syndication feeds into a single one
+
+
+
+
+
+
+
+
+
+
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:
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();
+ }
+ }
+
+}
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html b/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html
new file mode 100644
index 0000000..50ab7cc
--- /dev/null
+++ b/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html
@@ -0,0 +1,161 @@
+
+
+
+
+
+ ROME - Rome v0.1 Tutorial, Using Rome to convert a syndication feed from one type to another
+
+
+
+
+
+
+
+
+
+
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();
+ }
+ }
+
+}
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1TutorialUsingRomeToReadASyndicationFeed.html b/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1TutorialUsingRomeToReadASyndicationFeed.html
new file mode 100644
index 0000000..c28740f
--- /dev/null
+++ b/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/RomeV0.1TutorialUsingRomeToReadASyndicationFeed.html
@@ -0,0 +1,152 @@
+
+
+
+
+
+ ROME - Rome v0.1 Tutorial, Using Rome to read a syndication feed
+
+
+
+
+
+
+
+
+
+
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();
+ }
+ }
+
+}
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/index.html b/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/index.html
new file mode 100644
index 0000000..1d415d5
--- /dev/null
+++ b/ROMEReleases/ROME0.1Beta/RomeV0.1Tutorials/index.html
@@ -0,0 +1,105 @@
+
+
+
+
+
+ ROME - 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.
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:
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();
+ }
+ }
+
+}
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/RomeV0.2TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html b/ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/RomeV0.2TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html
new file mode 100644
index 0000000..e97ae12
--- /dev/null
+++ b/ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/RomeV0.2TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html
@@ -0,0 +1,168 @@
+
+
+
+
+
+ ROME - Rome v0.2 Tutorial, Using Rome to convert a syndication feed from one type to another
+
+
+
+
+
+
+
+
+
+
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();
+ }
+ }
+
+}
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/RomeV0.2TutorialUsingRomeToReadASyndicationFeed.html b/ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/RomeV0.2TutorialUsingRomeToReadASyndicationFeed.html
new file mode 100644
index 0000000..b80b2e8
--- /dev/null
+++ b/ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/RomeV0.2TutorialUsingRomeToReadASyndicationFeed.html
@@ -0,0 +1,159 @@
+
+
+
+
+
+ ROME - Rome v0.2 Tutorial, Using Rome to read a syndication feed
+
+
+
+
+
+
+
+
+
+
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();
+ }
+ }
+
+}
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/index.html b/ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/index.html
new file mode 100644
index 0000000..8cb40ea
--- /dev/null
+++ b/ROMEReleases/ROME0.2Beta/RomeV0.2Tutorials/index.html
@@ -0,0 +1,105 @@
+
+
+
+
+
+ ROME - 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.
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)
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialDefiningACustomModuleBeanParserAndGenerator.html b/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialDefiningACustomModuleBeanParserAndGenerator.html
new file mode 100644
index 0000000..704ddbc
--- /dev/null
+++ b/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialDefiningACustomModuleBeanParserAndGenerator.html
@@ -0,0 +1,349 @@
+
+
+
+
+
+ ROME - Rome v0.3 Tutorial, Defining a Custom Module (bean, parser and generator)
+
+
+
+
+
+
+
+
+
+
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.
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
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html b/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html
new file mode 100644
index 0000000..e73d8bc
--- /dev/null
+++ b/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToAggregateManySyndicationFeedsIntoASingleOne.html
@@ -0,0 +1,203 @@
+
+
+
+
+
+ ROME - Rome v0.3 Tutorial, Using Rome to aggregate many syndication feeds into a single one
+
+
+
+
+
+
+
+
+
+
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:
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:
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();
+ }
+ }
+
+}
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html b/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html
new file mode 100644
index 0000000..1e8a8a5
--- /dev/null
+++ b/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToConvertASyndicationFeedFromOneTypeToAnother.html
@@ -0,0 +1,170 @@
+
+
+
+
+
+ ROME - Rome v0.3 Tutorial, Using Rome to convert a syndication feed from one type to another
+
+
+
+
+
+
+
+
+
+
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:
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();
+ }
+ }
+
+}
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToCreateAndWriteASyndicationFeed.html b/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToCreateAndWriteASyndicationFeed.html
new file mode 100644
index 0000000..22412d6
--- /dev/null
+++ b/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToCreateAndWriteASyndicationFeed.html
@@ -0,0 +1,258 @@
+
+
+
+
+
+ ROME - Rome v0.3 Tutorial, Using Rome to create and write a syndication feed
+
+
+
+
+
+
+
+
+
+
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:
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();
+ }
+ }
+
+}
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToReadASyndicationFeed.html b/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToReadASyndicationFeed.html
new file mode 100644
index 0000000..dad457e
--- /dev/null
+++ b/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/RomeV0.3TutorialUsingRomeToReadASyndicationFeed.html
@@ -0,0 +1,161 @@
+
+
+
+
+
+ ROME - Rome v0.3 Tutorial, Using Rome to read a syndication feed
+
+
+
+
+
+
+
+
+
+
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:
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();
+ }
+ }
+
+}
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/index.html b/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/index.html
new file mode 100644
index 0000000..a1ab7b1
--- /dev/null
+++ b/ROMEReleases/ROME0.3Beta/RomeV0.3Tutorials/index.html
@@ -0,0 +1,107 @@
+
+
+
+
+
+ ROME - 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.
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 the JAXP SAX parser may fail, using Xerces 2.6.2 addresses the problem.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ROMEReleases/ROME0.3Beta/rome-0.3-src.tar.gz b/ROMEReleases/ROME0.3Beta/rome-0.3-src.tar.gz
new file mode 100644
index 0000000..ea48feb
Binary files /dev/null and b/ROMEReleases/ROME0.3Beta/rome-0.3-src.tar.gz differ
diff --git a/ROMEReleases/ROME0.3Beta/rome-0.3-src.zip b/ROMEReleases/ROME0.3Beta/rome-0.3-src.zip
new file mode 100644
index 0000000..0ace930
Binary files /dev/null and b/ROMEReleases/ROME0.3Beta/rome-0.3-src.zip differ
diff --git a/ROMEReleases/ROME0.3Beta/rome-0.3.tar.gz b/ROMEReleases/ROME0.3Beta/rome-0.3.tar.gz
new file mode 100644
index 0000000..0d47709
Binary files /dev/null and b/ROMEReleases/ROME0.3Beta/rome-0.3.tar.gz differ
diff --git a/ROMEReleases/ROME0.3Beta/rome-0.3.zip b/ROMEReleases/ROME0.3Beta/rome-0.3.zip
new file mode 100644
index 0000000..551c465
Binary files /dev/null and b/ROMEReleases/ROME0.3Beta/rome-0.3.zip differ
diff --git a/ROMEReleases/ROME0.3Beta/rome-samples-0.3-src.tar.gz b/ROMEReleases/ROME0.3Beta/rome-samples-0.3-src.tar.gz
new file mode 100644
index 0000000..744efc1
Binary files /dev/null and b/ROMEReleases/ROME0.3Beta/rome-samples-0.3-src.tar.gz differ
diff --git a/ROMEReleases/ROME0.3Beta/rome-samples-0.3-src.zip b/ROMEReleases/ROME0.3Beta/rome-samples-0.3-src.zip
new file mode 100644
index 0000000..54848c7
Binary files /dev/null and b/ROMEReleases/ROME0.3Beta/rome-samples-0.3-src.zip differ
diff --git a/ROMEReleases/ROME0.4Beta/RomeV0.4Tutorials/RomeV0.4HowToBuildAndRunTheTutorialsSampleCode.html b/ROMEReleases/ROME0.4Beta/RomeV0.4Tutorials/RomeV0.4HowToBuildAndRunTheTutorialsSampleCode.html
new file mode 100644
index 0000000..30a258f
--- /dev/null
+++ b/ROMEReleases/ROME0.4Beta/RomeV0.4Tutorials/RomeV0.4HowToBuildAndRunTheTutorialsSampleCode.html
@@ -0,0 +1,131 @@
+
+
+
+
+
+ ROME - Rome v0.4, How to build and run the tutorials sample code
+
+
+
+
+
+
+
+
+
+
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 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)
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ROMEReleases/ROME0.4Beta/RomeV0.4Tutorials/RomeV0.4TutorialUsingRomeWithinAServletToCreateAndReturnAFeed.html b/ROMEReleases/ROME0.4Beta/RomeV0.4Tutorials/RomeV0.4TutorialUsingRomeWithinAServletToCreateAndReturnAFeed.html
new file mode 100644
index 0000000..a107bc8
--- /dev/null
+++ b/ROMEReleases/ROME0.4Beta/RomeV0.4Tutorials/RomeV0.4TutorialUsingRomeWithinAServletToCreateAndReturnAFeed.html
@@ -0,0 +1,302 @@
+
+
+
+
+
+ ROME - Rome v0.4 Tutorial, Using Rome within a Servlet to create and return a feed
+
+
+
+
+
+
+
+
+
+
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:
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 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:
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 in a default localhost Tomcat installation.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ROMEReleases/ROME0.4Beta/RomeV0.4Tutorials/index.html b/ROMEReleases/ROME0.4Beta/RomeV0.4Tutorials/index.html
new file mode 100644
index 0000000..61c575b
--- /dev/null
+++ b/ROMEReleases/ROME0.4Beta/RomeV0.4Tutorials/index.html
@@ -0,0 +1,108 @@
+
+
+
+
+
+ ROME - 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.
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!
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.
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
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: let's Nuke all these feeds! NEW
+
Enclosure support at the Synd level, for all our podcaster friends
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
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.
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 for further details
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 and 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
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/RomeV0.4FeedAndEntryURIMapping.html b/RomeV0.4FeedAndEntryURIMapping.html
new file mode 100644
index 0000000..29659a9
--- /dev/null
+++ b/RomeV0.4FeedAndEntryURIMapping.html
@@ -0,0 +1,138 @@
+
+
+
+
+
+ ROME - 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...
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/RssAndAtOMUtiliEsROMEV0.7DateAndTimeParsing.html b/RssAndAtOMUtiliEsROMEV0.7DateAndTimeParsing.html
new file mode 100644
index 0000000..894128c
--- /dev/null
+++ b/RssAndAtOMUtiliEsROMEV0.7DateAndTimeParsing.html
@@ -0,0 +1,112 @@
+
+
+
+
+
+ ROME - Rss and atOM utiliEs (ROME) v0.7 Date and Time Parsing
+
+
+
+
+
+
+
+
+
+
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.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.html b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.html
new file mode 100644
index 0000000..33a68af
--- /dev/null
+++ b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedAndEntryURIMappingHowSyndFeedAndSyndEntryUriPropertiesMapToRSSAndAtomElements.html
@@ -0,0 +1,137 @@
+
+
+
+
+
+ ROME - Feed and Entry URI Mapping, how SyndFeed and SyndEntry 'uri' properties map to RSS and Atom elements
+
+
+
+
+
+
+
+
+
+
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.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html
new file mode 100644
index 0000000..55a18cd
--- /dev/null
+++ b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/FeedsDateElementsMappingToSyndFeedAndSyndEntry.html
@@ -0,0 +1,131 @@
+
+
+
+
+
+ ROME - Feeds Date Elements Mapping to SyndFeed and SyndEntry
+
+
+
+
+
+
+
+
+
+
Feeds Date Elements Mapping to SyndFeed and SyndEntry
+
The different RSS versions and Atom define different date elements at feed and entry level. Some of them also define syndication information indicating when (and when not) and how often to fetch feeds for updates. There is not always a possible mapping or conversion of this information when going from one format to another.
+
As this is still subject of debate (How About a Date and Date Survey), for now, in Rss and atOM utilitiEs (ROME) we've taken a simplistic approach.
+
When handling feeds at WireFeed level, rss.Channel or atom.Feed, it is possible to access all the date elements and syndication information available in the feed.
+
When handling feeds at SyndFeed level, synd.SyndFeed, there is only one date element available, the publishedDate. Both, SyndFeed and SyndEntry have the publisheDate property. In addition, it is possible to use the Syndication Module.
+
The mapping of the date elements from the different feed formats to SyndFeed is as follows.
+
+
For RSS 0.90
+
RSS 0.90 does not define date elements.
+
There is no mapping to SyndFeed and SyndEntry date properties.
+
+
For RSS 0.91, 0.92
+
RSS 0.91 and 0.92 define pubDate and lastBuildDate at feed level.
+
The feed pubDate element is mapped to the SyndFeedpublishedDate property. The lastBuildDate element is lost.
+
+
For RSS 0.93, 0.94 and 2.0
+
RSS 0.93, 0.94 and 2.0 define pubDate and lastBuildDate at feed level. They also define pubDate and expirationDate at item level.
+
The feed pubDate element is mapped to the SyndFeedpublishedDate property. The lastBuildDate element is lost.
+
The item pubDate element is mapped to the SyndEntrypublishedDate property. The expirationDate element is lost.
+
+
For RSS 1.0
+
RSS 1.0 use DC Module data at feed an item level to indicate date information about the feed and the items.
+
SyndFeed and SyndEntry use the DC Module date element for the publishedDate property.
+
+
For Atom 0.3
+
Atom 0.3 defines a modified element at feed level and the modified, created & issued elements at entry level.
+
The feed modified element is mapped to the SyndFeedpublishedDate property.
+
The item modified element is mapped to the SyndEntrypublishedDate property. The entry elements, created and issued, are lost.
+
+
For Atom 1.0
+
(Atom 1.0 supported in ROME since v0.8)
+
Atom 1.0 defines an updated element at the feed level, which ROME maps to SyndFeed.publishedDate.
+
Atom 1.0 defines updated and published elements at the entry level, which ROME maps to SyndEntry.updatedDate and SyndEntry.publishedDate respectively.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEPluginsMechanism.html b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEPluginsMechanism.html
new file mode 100644
index 0000000..6206c0c
--- /dev/null
+++ b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEPluginsMechanism.html
@@ -0,0 +1,231 @@
+
+
+
+
+
+ ROME - Rss and atOM utilitiEs (ROME) Plugins Mechanism
+
+
+
+
+
+
+
+
+
+
ROME has been designed around a plugin mechanism. All the supported feed types (RSSs and Atom) is done by plugins included in the distribution.
+
Parsing feeds, generating feeds, converting feeds from a concrete feed to a SyndFeed and vice versa, parsing modules and generating modules is done using plugins.
+
Plugins for new functionality can be added and default plugins can be easily replaced with alternate plugins.
+
+
Plugins definition files
+
Plugins are defined in a properties file, the rome.properties file.
+
The default plugins definition file is included in the ROME JAR file, com/sun/syndication/rome.properties, this is the first plugins definition file to be processed. It defines the default parsers, generators and converters for feeds and modules ROME provides.
+
After loading the default plugins definition file, ROME looks for additional plugins definition files in all the CLASSPATH entries, this time at root level, /rome.properties. And appends the plugins definitions to the existing ones. Note that if there are several /rome.properties files in the different CLASSPATH entries all of them are processed. The order of processing depends on how the ClassLoader processes the CLASSPATH entries, this is normally done in the order of appearance -of the entry- in the CLASSPATH.
+
For each type of plugin (parser, generator, converter, ect) a list of available plugins is built following the read order just described. The plugins classes are then loaded and instantiated. All plugins have some kind of primary key. In the case or parsers, generators and converters the primary key is the type of feed they handle. In the case of modules, the primary key is the module URI. If a plugin list definition (the aggregation of all the plugins of the same time from all the rome.properties) contains more than one plugin with the same primary key, the latter one is the one that will be used(this enables replacing default plugins with custom ones).
+
The plugins are read, loaded and managed by the implementation class com.sun.syndication.io.impl.PluginManager. This class is an abstract class and it is extended to provide support for each type of plugin.
+
+
Parser Plugins
+
Parser plugins are managed by the com.sun.syndication.io.impl.FeedParsers class (subclass of the PluginManager). This plugin manager looks for the WireFeedParser.classes property in all the rome.properties files. The fully qualified names of the parser classes must be separated by whitespaces or commas. For example, the default rome.properties file parser plugins definition is as follows:
All the classes defined in this property have to implement the com.sun.syndication.io.WireFeedParser interface. Parser instances must be thread safe. The return value of the getType() method is used as the primary key. If more than one parser returns the same type, the latter one prevails.
+
+
Generator Plugins
+
Generator plugins are managed by the com.sun.syndication.io.impl.FeedGenerators class (subclass of the PluginManager). This plugin manager looks for the WireFeedGenerator.classes property in all the rome.properties files. The fully qualified names of the generator classes must be separated by whitespaces or commas. For example, the default rome.properties file generator plugins definition is as follows:
All the classes defined in this property have to implement the com.sun.syndication.io.WireFeedGenerator interface. Generator instances must be thread safe. The return value of the getType() method is used as the primary key. If more than one generator returns the same type, the latter one prevails.
+
+
Converter Plugins
+
Converter plugins are managed by the com.sun.syndication.synd.impl.Converters class (subclass of the PluginManager). This plugin manager looks for the Converter.classes property in all the rome.properties files. The fully qualified names of the converter classes must be separated by whitespaces or commas. For example, the default rome.properties file converter plugins definition is as follows:
All the classes defined in this property have to implement the com.sun.syndication.synd.Converter interface. Converter instances must be thread safe. The return value of the getType() method is used as the primary key. If more than one converter returns the same type, the latter one prevails.
+
+
Module Plugins
+
There are 2 types of module plugins, module parser plugins and module generator plugins. They use a same pattern feed parsers and generators use.
+
The main difference is that support for module plugins has to be wired in the feed parser and generator plugins. The default feed parser and generator plugins supporting module plugins are: RSS 1.0, RSS 2.0 and Atom 0.3.
+
It is important to understand that this wiring is for modules support. Once a feed parser or generator has modules support, new modules can be used just by adding them to right property in the rome.properties file. No code changes are required.
+
Module parsers and generators are defined at feed and item level. This allow selective handling of modules, for example handling Syndication module at feed level only.
+
Module parser plugins are managed by the com.sun.syndication.io.impl.ModuleParsers class (subclass of the PluginManager). This plugin manager looks for the .feed.ModuleParser.classes and the .item.ModuleParser.classes properties in all the rome.properties files. must be the type defined by the parser (ie: rss_1.0, atom_0.3). The fully qualified names of the module parser classes must be separated by whitespaces or commas. For example, the default rome.properties file modules parser plugins definition is as follows:
+
+
+# Parsers for Atom 0.3 feed modules
+#
+atom_0.3.feed.ModuleParser.classes=com.sun.syndication.io.impl.SyModuleParser \
+ com.sun.syndication.io.impl.DCModuleParser
+
+# Parsers for Atom 0.3 entry modules
+#
+atom_0.3.item.ModuleParser.classes=com.sun.syndication.io.impl.DCModuleParser
+
+# Parsers for RSS 1.0 feed modules
+#
+rss_1.0.feed.ModuleParser.classes=com.sun.syndication.io.impl.SyModuleParser \
+ com.sun.syndication.io.impl.DCModuleParser
+
+# Parsers for RSS 1.0 item modules
+#
+rss_1.0.item.ModuleParser.classes=com.sun.syndication.io.impl.DCModuleParser
+
+# Parsers for RSS 2.0 feed modules
+#
+rss_2.0.feed.ModuleParser.classes=
+
+# Parsers for RSS 2.0 item modules
+#
+rss_2.0.item.ModuleParser.classes=
+
+
All the classes defined in this property have to implement the com.sun.syndication.io.ModuleParser interface. ModuleParser instances must be thread safe. The return value of the getNamesapceUri() method is used as the primary key. If more than one module parser returns the same URI, the latter one prevails.
+
Module generator plugins are managed by the com.sun.syndication.io.impl.GeneratorParsers class (subclass of the PluginManager). This plugin manager looks for the .feed.ModuleGenerator.classes and the .item.ModuleGenerator.classes properties in all the rome.properties files. must be the type defined by the generator (ie: rss_1.0, atom_0.3). The fully qualified names of the module generator classes must be separated by whitespaces or commas. For example, the default rome.properties file modules generator plugins definition is as follows:
+
+
+# Generators for Atom 0.3 feed modules
+#
+atom_0.3.feed.ModuleGenerator.classes=com.sun.syndication.io.impl.SyModuleGenerator \
+ com.sun.syndication.io.impl.DCModuleGenerator
+
+# Generators for Atom 0.3 entry modules
+#
+atom_0.3.item.ModuleGenerator.classes=com.sun.syndication.io.impl.DCModuleGenerator
+
+# Generators for RSS 1.0 feed modules
+#
+rss_1.0.feed.ModuleGenerator.classes=com.sun.syndication.io.impl.SyModuleGenerator \
+ com.sun.syndication.io.impl.DCModuleGenerator
+
+# Generators for RSS_1.0 entry modules
+#
+rss_1.0.item.ModuleGenerator.classes=com.sun.syndication.io.impl.DCModuleGenerator
+
+# Generators for RSS 2.0 feed modules
+#
+rss_2.0.feed.ModuleGenerator.classes=
+
+# Generators for RSS_2.0 entry modules
+#
+rss_2.0.item.ModuleGenerator.classes=
+
+
All the classes defined in this property have to implement the com.sun.syndication.io.ModuleGenerator interface. ModuleGenerator instances must be thread safe. The return value of the getNamesapceUri() method is used as the primary key. If more than one module generator returns the same URI, the latter one prevails.
+
+
+
\ No newline at end of file
diff --git a/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5HowToBuildAndRunTheTutorialsSampleCode.html b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5HowToBuildAndRunTheTutorialsSampleCode.html
new file mode 100644
index 0000000..bb7fa63
--- /dev/null
+++ b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5HowToBuildAndRunTheTutorialsSampleCode.html
@@ -0,0 +1,132 @@
+
+
+
+
+
+ ROME - Rss and atOM utilitiEs (ROME) v0.5, How to build and run the tutorials sample code
+
+
+
+
+
+
+
+
+
+
Rss and atOM utilitiEs (ROME) v0.5, How to build and run the tutorials sample code
+
These instructions are outdated
+
+
Building the samples with Maven
+
This is, as usual, the easiest way.
+
There's only one configuration step: Maven downloads dependencies from an online repository (by default ibiblio), to a local repository (on UNIX usually in ~/.maven/repository). Because the rome distribution is not yet on ibiblio, you need to add it yourself, either to your local repository, or to your own intranet maven repository if you have such a thing in your organization.
+
If you built ROME run maven jar:install in the rome project to install ROME's jar in your Maven repository.
+
If you got ROME binary distribution copy the ROME's jar file to your Maven repository (on UNIX that would be cp rome-0.5/rome-0.5.jar ~/.maven/repository/rome/jars/).
+
Then building the samples it's easy as a pie, just run maven jar in the samples sub-project and you are all set.
+
To build the sample Web Application, just run maven war in the samples sub-project. The WAR file, rome-samples.war, will be created under the target directory.
+
+
Building the samples with Ant
+
The targets present in the build.xml are very helpful, ant get-deps will download from ibiblio to rome-samples/target/lib all the jar files ROME depends on and are needed for building an application using Rome.
+
In order to build the samples (or any subprojects), you'll need to first ensure that rome itself is built. You can do this simply by running ant in the project root directory.
+
Once this is done, change to the samples directory, and just run ant. This will produce two files, rome-samples.jar which contains the sample applications, and rome-samples.war which will contain a deployable web application war file for the FeedServlet sample.
+
+
Running the samples with Maven
+
The Maven goals for running the samples are defined in maven.xml.
+
+
maven run-agr runs the FeedAggregator sample
+
maven run-conv runs the FeedConverter sample
+
maven run-read runs the FeedReader sample
+
maven run-write runs the FeedWriter sample
+
maven run-sampleModule runs the FeedConverter sample against a file with Sample Module data (shows off custom module plugin)
+
To run the sample Web Application you'll need to deploy the WAR file into your servlet container. If you are using Tomcat 4 or Tomcat 5 and the WAR file was dropped in the ${TOMCAT}/webapps directory the URL for the FeedServlet would be http://localhost:8080/rome-samples/feed 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)
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialDefiningACustomModuleBeanParserAndGenerator.html b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialDefiningACustomModuleBeanParserAndGenerator.html
new file mode 100644
index 0000000..4bd9efc
--- /dev/null
+++ b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialDefiningACustomModuleBeanParserAndGenerator.html
@@ -0,0 +1,365 @@
+
+
+
+
+
+ ROME - Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Defining a Custom Module (bean, parser and generator)
+
+
+
+
+
+
+
+
+
+
Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Defining a Custom Module (bean, parser and generator)
+
Software requirements: Synd J2SE 1.4+, JDOM 1.0 and ROME 0.5.
+
This tutorial walks through the steps of creating a custom module for syndication feeds that support additional namespaces (such as RSS 1.0, RSS 2.0 and Atom 0.3).
+
To understand this tutorial you should be familiar the with ROME API and with the use of modules in syndication feeds.
+
Out of the box ROME parsers and generators support plug-ability of modules for RSS 1.0, RSS 2.0 and Atom 0.3 at both feed and item/entry levels. Also support for the Dublin Core and Syndication modules is provided.
+
The complete source for this tutorial is in the ROME samples bundle as well as in CVS.
+
+
What is the intended outcome of the tutorial?
+
The goal is to add support for a hypothetical Sample Module by defining a module bean, module parser and module generator and the necessary configuration to wire the parser and generator to an RSS 1.0 parser and RSS 1.0 generator.
+
The sample module defines 3 elements, 'bar', 'foo' and 'date', where 'bar' and 'date' may occur at most once and the 'foo' element may occur several times. For example, a feed with the Sample Module data would look like:
+
+
+<?xml version="1.0"?>
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns="http://purl.org/rss/1.0/"
+ xmlns:sample="http://rome.dev.java.net/module/sample/1.0">
+ <channel>
+ <title>RSS 1.0 Feed with Sample Module</title>
+ <link>http://rome.dev.java.net</link>
+ <description>This is a feed showing how to use a custom module with ROME</description>
+ <items>
+ <rdf:Seq>
+ <rdf:li resource="item01" />
+ <rdf:li resource="item02" />
+ </rdf:Seq>
+ </items>
+ <sample:bar>Channel bar</sample:bar>
+ <sample:foo>Channel first foo</sample:foo>
+ <sample:foo>Channel second foo</sample:foo>
+ </channel>
+ <item rdf:about="item01">
+ <title>Title of Item 01</title>
+ <link>http://rome.dev.java.net/item01</link>
+ <description>Item 01 does not have Sample module data</description>
+ </item>
+ <item rdf:about="item02">
+ <title>Title of Item 02</title>
+ <link>http://rome.dev.java.net/item02</link>
+ <description>Item 02 has Sample module data</description>
+ <sample:bar>Item 02 bar</sample:bar>
+ <sample:foo>Item 02 only foo</sample:foo>
+ <sample:date>2004-07-27T00:00+00:00</sample:date>
+ </item>
+</rdf:RDF>
+
+
+
Sample Module Bean
+
First we must start with the bean interface, SampleModule. SampleModule must extend Module. The Module interface defines the getUri() method, which will return a URI identifying the module.
+
The Module interface also extends the CopyFrom interface to enable copying properties from alternate implementations of the concrete Module interface. More on this later in this page.
+
The SampleModule's URI is defined as a constant, accessible via the getURI() instance method. This is for convenience and good practice only.
+
Then the module defines 3 properties: bar (String), foos (List) and date (Date). The elements of the foos property list must be strings (wishing for Java 5 generics already?).
+
+
+public interface SampleModule extends Module {
+
+ public static final String URI = "http://rome.dev.java.net/module/sample/1.0";
+
+ public String getBar();
+ public void setBar(String bar);
+
+ public List getFoos();
+ public void setFoos(List foos);
+
+ public Date getDate();
+ public void setDate(Date date);
+}
+
+
Next we have to write the bean implementation, SampleModuleImpl.
+
SampleModuleImpl extends ModuleImpl. ModuleImpl is the default implementation of the ==Module interface. ModuleImpl automatically provides equals, hashCode, toString and clone support for the properties of the class given in the constructor (SampleModule). Also the URI of the Sample module is indicated; it will be used by the Module.getUri() method.
The module properties are just Java Bean properties. The only catch is to follow ROME semantics for Collection properties: in the case of a null value for the collection, an empty collection must be returned. Also, following ROME semantics, all properties are by reference, including mutable ones.
+
+
+public class SampleModuleImpl extends ModuleImpl implements SampleModule {
+ private String _bar;
+ private List _foos;
+ private Date _date;
+ ...
+ public void setBar(String bar) {
+ _bar = bar;
+ }
+
+ public List getFoos() {
+ return (_foos==null) ? (_foos=new ArrayList()) : _foos;
+ }
+
+ public void setFoos(List foos) {
+ _foos = foos;
+ }
+
+ public Date getDate() {
+ return _date;
+ }
+
+ public void setDate(Date date) {
+ _date = date;
+ }
+
+
+
The CopyFrom interface
+
Now the weird part, the bits for the CopyFrom logic. The The CopyFrom interface (rome) document fully explains the CopyFrom logic in detail. In short, the CopyFrom interface is to support copying properties from one implementation of a bean (defined through an interface) to another implementation of the same bean.
+
The getInterface() method returns the bean interface of the implementation (this is necessary for collections containing sub-classes such as a list of modules).
+
The copyFrom() method copies all the properties from the parameter object (which must be a SampleModule implementation) into the caller bean properties. Note that the copyFrom must do a deep copy.
+
+
+public class SampleModuleImpl extends ModuleImpl implements SampleModule {
+ ...
+ public Class getInterface() {
+ return SampleModule.class;
+ }
+
+ public void copyFrom(Object obj) {
+ SampleModule sm = (SampleModule) obj;
+ setBar(sm.getBar());
+ List foos = new ArrayList(sm.getFoos()); // this is enough for the copy because the list elements are inmutable (Strings)
+ setFoos(foos);
+ setDate((Date)sm.getDate().clone()); // because Date is not inmutable.
+ }
+
+}
+
+
+
Sample Module Parser
+
The sample module parser must implement the ModuleParser interface. This interface defines 2 methods, getNamespaceUri() that returns the URI of the module and parse(Element) which extracts the module elements from the given Element.
+
The feed parsers will invoke the module parser with a feed element or with an item element. The module parser must look for module elements in the children of the given element. That is was the Sample parser is doing when looking for 'bar', 'foo' and 'date' children elements in the received element.
+
In the case of the 'foo' element it looks for all occurrences as the Sample module schema allows for more than one occurrence of the 'foo' element. A SampleModule bean is created and the found values are set into it. For the 'date' element it assumes its a date value in W3C datetime format.
+
If no Sample Module elements are found in the feed, the parse(Element) method returns null. This is to avoid having an empty instance of a module -not present in the feed- in the feed bean or in the item bean.
+
+
+public class SampleModuleParser implements ModuleParser {
+
+ private static final Namespace SAMPLE_NS = Namespace.getNamespace("sample", SampleModule.URI);
+
+ public String getNamespaceUri() {
+ return SampleModule.URI;
+ }
+
+ public Module parse(Element dcRoot) {
+ boolean foundSomething = false;
+ SampleModule fm = new SampleModuleImpl();
+
+ Element e = dcRoot.getChild("bar", SAMPLE_NS);
+ if (e != null) {
+ foundSomething = true;
+ fm.setBar(e.getText());
+ }
+ List eList = dcRoot.getChildren("foo", SAMPLE_NS);
+ if (eList.size() > 0) {
+ foundSomething = true;
+ fm.setFoos(parseFoos(eList));
+ }
+ e = dcRoot.getChild("date", SAMPLE_NS);
+ if (e != null) {
+ foundSomething = true;
+ fm.setDate(DateParser.parseW3CDateTime(e.getText()));
+ }
+ return (foundSomething) ? fm : null;
+ }
+
+ private List parseFoos(List eList) {
+ List foos = new ArrayList();
+ for (int i = 0; i < eList.size(); i++) {
+ Element e = (Element) eList.get(i);
+ foos.add(e.getText());
+ }
+ return foos;
+ }
+
+}
+
+
+
Sample Module Generator
+
The sample module generator must implement the ModuleGenerator interface. This interface defines 2 methods, getNamespaceUri() that returns the URI of the module and generate(ModuleI,Element) which injects the module data into the given Element.
+
The feed generator will invoke the module generator with a feed element or with an item element. The module generator must inject the module properties into the given element (which is a feed or an item). This injection has to be done using the right namespace. The set of namespaces returned by the getNamespaces() method will be used to declare the namespaces used by the module in the feed root element.
+
If no Sample Module bean is in the feed bean the module generator is not invoked at all.
+
+
+public class SampleModuleGenerator implements ModuleGenerator {
+ private static final Namespace SAMPLE_NS = Namespace.getNamespace("sample", SampleModule.URI);
+
+ public String getNamespaceUri() {
+ return SampleModule.URI;
+ }
+
+ private static final Set NAMESPACES;
+
+ static {
+ Set nss = new HashSet();
+ nss.add(SAMPLE_NS);
+ NAMESPACES = Collections.unmodifiableSet(nss);
+ }
+
+ public Set getNamespaces() {
+ return NAMESPACES;
+ }
+
+ public void generate(Module module, Element element) {
+
+ // this is not necessary, it is done to avoid the namespace definition in every item.
+ Element root = element;
+ while (root.getParent()!=null && root.getParent() instanceof Element) {
+ root = (Element) element.getParent();
+ }
+ root.addNamespaceDeclaration(SAMPLE_NS);
+
+ SampleModuleI fm = (SampleModule)module;
+ if (fm.getBar() != null) {
+ element.addContent(generateSimpleElement("bar", fm.getBar()));
+ }
+ List foos = fm.getFoos();
+ for (int i = 0; i < foos.size(); i++) {
+ element.addContent(generateSimpleElement("foo",foos.get(i).toString()));
+ }
+ if (fm.getDate() != null) {
+ element.addContent(generateSimpleElement("date", DateParser.formatW3CDateTime(fm.getDate())));
+ }
+ }
+
+ protected Element generateSimpleElement(String name, String value) {
+ Element element = new Element(name, SAMPLE_NS);
+ element.addContent(value);
+ return element;
+ }
+
+}
+
+
+
Configuration to make ROME process Sample Module in feeds
+
The last step is to setup the configuration file to indicate to ROME how and when to use the Sample Module parser and generator.
+
The configuration is stored in a Properties file, 'rome.properties', that has to be in the root of the classpath or JAR where the Sample Module bean, parser and generator classes are.
+
You must indicate the syndication feed formats (ie RSS 1.0) that must be aware of the Sample Module. You must indicate if the Sample Module is available for feed or item elements, or for both. You must indicate both the parser and the generator classes.
+
Following is the 'rome.properties' file for the Sample Module, it's defined for RSS 1.0 only, for both feed and item elements.
+
+
+# Parsers for RSS 1.0 feed modules
+#
+rss_1.0.feed.ModuleParser.classes=com.sun.syndication.samples.module.SampleModuleParser
+
+# Parsers for RSS 1.0 item modules
+#
+rss_1.0.item.ModuleParser.classes=com.sun.syndication.samples.module.SampleModuleParser
+
+# Generators for RSS 1.0 feed modules
+#
+rss_1.0.feed.ModuleGenerator.classes=com.sun.syndication.samples.module.SampleModuleGenerator
+
+# Generators for RSS_1.0 entry modules
+#
+rss_1.0.item.ModuleGenerator.classes=com.sun.syndication.samples.module.SampleModuleGenerator
+
+
If you are defining more than one module, indicate the parser and generator implementation classes separated by commas or spaces.
+
+
Using the Sample Module from the SyndFeed beans
+
They will be there, just use them. You may get the SampleModule bean using the getModule(String Uri) method of the SyndFeed bean and the SyndEntry bean.
+
Adding or replacing a syndication feed parser, generator or converter goes along the same lines of what it has been explained in the tutorial for modules. This is explained in the ROME Plugins Mechanism topic.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToAggregateManySyndicationFeedsIntoASingleOne.html b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToAggregateManySyndicationFeedsIntoASingleOne.html
new file mode 100644
index 0000000..ff50d65
--- /dev/null
+++ b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToAggregateManySyndicationFeedsIntoASingleOne.html
@@ -0,0 +1,203 @@
+
+
+
+
+
+ ROME - Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to aggregate many syndication feeds into a single one
+
+
+
+
+
+
+
+
+
+
Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to aggregate many syndication feeds into a single one
+
Software requirements: J2SE 1.4+, JDOM 1.0 and ROME 0.5.
+
ROME represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeed interface. The SyndFeed interfaces and its properties follow the Java Bean patterns. The default implementations provided with ROME are all lightweight classes.
+
ROME includes parsers to process syndication feeds into SyndFeed instances. The SyndFeedInput class handles the parsers using the correct one based on the syndication feed being processed. The developer does not need to worry about selecting the right parser for a syndication feed, the SyndFeedInput will take care of it by peeking at the syndication feed structure. All it takes to read a syndication feed using ROME are the following 2 lines of code:
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:
The snipped of code above creates a SyndFeed instance using the default implementation provided by ROME, sets the feed type to RSS 1.0, sets the title, description, author and link properties of the feed.
+
SyndFeed properties can be modified, assigned to other SyndFeed instances, removed, etc. It's important to remember that the getters/setters semantics defined for all SyndFeed properties (and properties of its properties) is a copy by reference, not by value. In other words if you alter the property of a SyndFeed property you are altering the SyndFeed. Or, another example, if you assign the list of entries of one SyndFeed instance to another SyndFeed isntance and then you modify the list or any of the entries in the list, you are modifying the entries of both SyndFeed instances.
+
The following lines of code show how to copy the entries of a SyndFeed instance being read (inFeed) into a SyndFeed instance being created within the application (feed):
+
+
+package com.sun.syndication.samples;
+
+import java.net.URL;
+import java.io.InputStreamReader;
+import java.io.PrintWriter;
+import java.util.List;
+import java.util.ArrayList;
+
+import com.sun.syndication.feed.synd.SyndFeed;
+import com.sun.syndication.feed.synd.SyndFeedImpl;
+import com.sun.syndication.io.SyndFeedOutput;
+import com.sun.syndication.io.SyndFeedInput;
+import com.sun.syndication.io.XmlReader;
+
+/**
+ * It aggregates a list of RSS/Atom feeds (they can be of different types)
+ * into a single feed of the specified type.
+ * <p>
+ * @author Alejandro Abdelnur
+ *
+ */
+public class FeedAggregator {
+
+ public static void main(String[] args) {
+ boolean ok = false;
+ if (args.length>=2) {
+ try {
+ String outputType = args[0];
+
+ SyndFeed feed = new SyndFeedImpl();
+ feed.setFeedType(outputType);
+
+ feed.setTitle("Aggregated Feed");
+ feed.setDescription("Anonymous Aggregated Feed");
+ feed.setAuthor("anonymous");
+ feed.setLink("http://www.anonymous.com");
+
+ List entries = new ArrayList();
+ feed.setEntries(entries);
+
+ for (int i=1;i<args.length;i++) {
+ URL inputUrl = new URL(args[i]);
+
+ SyndFeedInput input = new SyndFeedInput();
+ SyndFeed inFeed = input.build(new XmlReader(inputUrl));
+
+ entries.addAll(inFeed.getEntries());
+
+ }
+
+ SyndFeedOutput output = new SyndFeedOutput();
+ output.output(feed,new PrintWriter(System.out));
+
+ ok = true;
+ }
+ catch (Exception ex) {
+ System.out.println("ERROR: "+ex.getMessage());
+ }
+ }
+
+ if (!ok) {
+ System.out.println();
+ System.out.println("FeedAggregator aggregates different feeds into a single one.");
+ System.out.println("The first parameter must be the feed type for the aggregated feed.");
+ System.out.println(" [valid values are: rss_0.9, rss_0.91U, rss_0.91N, rss_0.92, rss_0.93, ]");
+ System.out.println(" [ rss_0.94, rss_1.0, rss_2.0 & atom_0.3 ]");
+ System.out.println("The second to last parameters are the URLs of feeds to aggregate.");
+ System.out.println();
+ }
+ }
+
+}
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToConvertASyndicationFeedFromOneTypeToAnother.html b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToConvertASyndicationFeedFromOneTypeToAnother.html
new file mode 100644
index 0000000..e2e0870
--- /dev/null
+++ b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToConvertASyndicationFeedFromOneTypeToAnother.html
@@ -0,0 +1,171 @@
+
+
+
+
+
+ ROME - Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to convert a syndication feed from one type to another
+
+
+
+
+
+
+
+
+
+
Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to convert a syndication feed from one type to another
+
Software requirements: Synd J2SE 1.4+, JDOM 1.0 and ROME 0.5.
+
ROME represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeed interface. The SyndFeed interfaces and its properties follow the Java Bean patterns. The default implementations provided with ROME are all lightweight classes.
+
ROME includes parsers to process syndication feeds into SyndFeed instances. The SyndFeedInput class handles the parsers using the correct one based on the syndication feed being processed. The developer does not need to worry about selecting the right parser for a syndication feed, the SyndFeedInput will take care of it by peeking at the syndication feed structure. All it takes to read a syndication feed using ROME are the following 2 lines of code:
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();
+ }
+ }
+
+}
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToCreateAndWriteASyndicationFeed.html b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToCreateAndWriteASyndicationFeed.html
new file mode 100644
index 0000000..c73d2e2
--- /dev/null
+++ b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToCreateAndWriteASyndicationFeed.html
@@ -0,0 +1,258 @@
+
+
+
+
+
+ ROME - Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to create and write a syndication feed
+
+
+
+
+
+
+
+
+
+
Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to create and write a syndication feed
+
Software requirements: J2SE 1.4+, JDOM 1.0 and ROME 0.5.
+
ROME represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeed interface. The SyndFeed interfaces and its properties follow the Java Bean patterns. The default implementations provided with ROME are all lightweight classes.
+
Creating a feed with SyndFeed beans consists of creating beans and setting their properties. The following code fragments show how a SyndFeed bean with 3 entries is created.
+
First the SyndFeed instance is created, the preferred syndication format is set and the feed header info (title, link, description) is also set.
+
+
+SyndFeed feed = new SyndFeedImpl();
+feed.setFeedType(feedType);
+
+feed.setTitle("Sample Feed (created with ROME)");
+feed.setLink("http://rome.dev.java.net");
+feed.setDescription("This feed has been created using ROME (Java syndication utilities");
+
+
Then a list for entries is created, entries are created and added to the list. Each entry is set with a title, link, published date and a description. The description for the first entry is plain test, for the third entry is HTML. After each entry is created is added to the list.
+
+
+List entries = new ArrayList();
+SyndEntry entry;
+SyndContent description;
+
+entry = new SyndEntryImpl();
+entry.setTitle("ROME v1.0");
+entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome01");
+entry.setPublishedDate(DATE_PARSER.parse("2004-06-08"));
+description = new SyndContentImpl();
+description.setType("text/plain");
+description.setValue("Initial release of ROME");
+entry.setDescription(description);
+entries.add(entry);
+[...]
+entry = new SyndEntryImpl();
+entry.setTitle("ROME v3.0");
+entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome03");
+entry.setPublishedDate(DATE_PARSER.parse("2004-07-27"));
+description = new SyndContentImpl();
+description.setType("text/html");
+description.setValue("<p>More Bug fixes, mor API changes, some new features and some Unit testing</p>"+
+ "<p>For details check the <a href=\"https://rometools.jira.com/wiki/display/ROME/Change+Log#ChangeLog-Changesmadefromv0.3tov0.4\">Changes Log</a></p>");
+entry.setDescription(description);
+entries.add(entry);
+
+
Finally the list with entries is added to the SyndFeed bean.
+
+
+feed.setEntries(entries);
+
+
The SyndFeed bean is now ready to be written out to a syndication feed XML document. Note that any of supported syndication formats can be set in the feedType property.
+
ROME includes generators that allow producing syndication feed XML documents from SyndFeed instances. The SyndFeedOutput class handles the generation of the syndication feed XML documents on any of the supported feed formats (RSS and Atom). The developer does not need to worry about selecting the right generator for a syndication feed, the SyndFeedOutput will take care of it by looking at the information in the SyndFeed bean. All it takes to write a syndication feed XML document using ROME -assuming you have a SyndFeed bean and a Writer instance- are the following lines of code:
First a SyndFeedOutput instance is created, this instance will work with any syndication feed type (RSS and Atom versions). Then the feed and the writer are given to the SyndFeedOutput instance, the SyndFeedOutput will write the syndication feed XML document represented by the SyndFeed bean to the Writer stream.
+
Following is the full code for a Java application that creates a syndication feed and writes it to a file in the specified syndication format.
+
+
+package com.sun.syndication.samples;
+
+import com.sun.syndication.feed.synd.*;
+import com.sun.syndication.io.SyndFeedOutput;
+
+import java.io.FileWriter;
+import java.io.Writer;
+import java.text.DateFormat;
+import java.text.SimpleDateFormat;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * It creates a feed and writes it to a file.
+ * <p>
+ *
+ */
+public class FeedWriter {
+
+ private static final DateFormat DATE_PARSER = new SimpleDateFormat("yyyy-MM-dd");
+
+ public static void main(String[] args) {
+ boolean ok = false;
+ if (args.length==2) {
+ try {
+ String feedType = args[0];
+ String fileName = args[1];
+
+ SyndFeed feed = new SyndFeedImpl();
+ feed.setFeedType(feedType);
+
+ feed.setTitle("Sample Feed (created with ROME)");
+ feed.setLink("http://rome.dev.java.net");
+ feed.setDescription("This feed has been created using ROME (Java syndication utilities");
+
+ List entries = new ArrayList();
+ SyndEntry entry;
+ SyndContent description;
+
+ entry = new SyndEntryImpl();
+ entry.setTitle("ROME v1.0");
+ entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome01");
+ entry.setPublishedDate(DATE_PARSER.parse("2004-06-08"));
+ description = new SyndContentImpl();
+ description.setType("text/plain");
+ description.setValue("Initial release of ROME");
+ entry.setDescription(description);
+ entries.add(entry);
+
+ entry = new SyndEntryImpl();
+ entry.setTitle("ROME v2.0");
+ entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome02");
+ entry.setPublishedDate(DATE_PARSER.parse("2004-06-16"));
+ description = new SyndContentImpl();
+ description.setType("text/plain");
+ description.setValue("Bug fixes, minor API changes and some new features");
+ entry.setDescription(description);
+ entries.add(entry);
+
+ entry = new SyndEntryImpl();
+ entry.setTitle("ROME v3.0");
+ entry.setLink("http://wiki.java.net/bin/view/Javawsxml/Rome03");
+ entry.setPublishedDate(DATE_PARSER.parse("2004-07-27"));
+ description = new SyndContentImpl();
+ description.setType("text/html");
+ description.setValue("<p>More Bug fixes, mor API changes, some new features and some Unit testing</p>"+
+ "<p>For details check the <a href=\"https://rometools.jira.com/wiki/display/ROME/Change+Log#ChangeLog-Changesmadefromv0.3tov0.4\">Changes Log</a></p>");
+ entry.setDescription(description);
+ entries.add(entry);
+
+ feed.setEntries(entries);
+
+ Writer writer = new FileWriter(fileName);
+ SyndFeedOutput output = new SyndFeedOutput();
+ output.output(feed,writer);
+ writer.close();
+
+ System.out.println("The feed has been written to the file ["+fileName+"]");
+
+ ok = true;
+ }
+ catch (Exception ex) {
+ ex.printStackTrace();
+ System.out.println("ERROR: "+ex.getMessage());
+ }
+ }
+
+ if (!ok) {
+ System.out.println();
+ System.out.println("FeedWriter creates a RSS/Atom feed and writes it to a file.");
+ System.out.println("The first parameter must be the syndication format for the feed");
+ System.out.println(" (rss_0.90, rss_0.91, rss_0.92, rss_0.93, rss_0.94, rss_1.0 rss_2.0 or atom_0.3)");
+ System.out.println("The second parameter must be the file name for the feed");
+ System.out.println();
+ }
+ }
+
+}
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToReadASyndicationFeed.html b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToReadASyndicationFeed.html
new file mode 100644
index 0000000..7802837
--- /dev/null
+++ b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEToReadASyndicationFeed.html
@@ -0,0 +1,161 @@
+
+
+
+
+
+ ROME - Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to read a syndication feed
+
+
+
+
+
+
+
+
+
+
Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME to read a syndication feed
+
Software requirements: J2SE 1.4+, JDOM 1.0 and ROME 0.5.
+
ROME represents syndication feeds (RSS and Atom) as instances of the com.sun.syndication.synd.SyndFeed interface. The SyndFeed interfaces and its properties follow the Java Bean patterns. The default implementations provided with ROME are all lightweight classes.
+
ROME includes parsers to process syndication feeds into SyndFeed instances. The SyndFeedInput class handles the parsers using the correct one based on the syndication feed being processed. The developer does not need to worry about selecting the right parser for a syndication feed, the SyndFeedInput will take care of it by peeking at the syndication feed structure. All it takes to read a syndication feed using ROME are the following 2 lines of code:
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();
+ }
+ }
+
+}
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEWithinAServletToCreateAndReturnAFeed.html b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEWithinAServletToCreateAndReturnAFeed.html
new file mode 100644
index 0000000..c0de70e
--- /dev/null
+++ b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/RssAndAtOMUtilitiEsROMEV0.5TutorialUsingROMEWithinAServletToCreateAndReturnAFeed.html
@@ -0,0 +1,302 @@
+
+
+
+
+
+ ROME - Rss and atOM utilitiEs (ROME) v0.5 Tutorial, Using ROME within a Servlet to create and return a feed
+
+
+
+
+
+
+
+
+
+
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:
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 Tutorial.
+
Then the feed type of the response is determined, first looking at the request parameters and falling back to a default feed type (specified by a servlet init parameter) if the type is not indicated in the request parameters. Setting the feed type in the feed bean will indicate the SyndFeedOutput the feed type to output.
+
Finally, the response is set with the proper content type (the MIME_TYPE constant is 'application/xml; charset=UTF-8') and the feed is written to response writer using the SyndFeedOutput output classes.
+
Following is the full code for the servlet.
+
+
+package com.sun.syndication.samples.servlet;
+
+import com.sun.syndication.feed.synd.*;
+import com.sun.syndication.io.FeedException;
+import com.sun.syndication.io.SyndFeedOutput;
+
+import javax.servlet.http.HttpServlet;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import java.io.IOException;
+import java.text.DateFormat;
+import java.text.ParseException;
+import java.text.SimpleDateFormat;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Sample Servlet that serves a feed created with ROME.
+ * <p>
+ * The feed type is determined by the 'type' request parameter, if the parameter is missing it defaults
+ * to the 'default.feed.type' servlet init parameter, if the init parameter is missing it defaults to 'atom_0.3'
+ * <p>
+ * @author Alejandro Abdelnur
+ *
+ */
+public class FeedServlet extends HttpServlet {
+ private static final String DEFAULT_FEED_TYPE = "default.feed.type";
+ private static final String FEED_TYPE = "type";
+ private static final String MIME_TYPE = "application/xml; charset=UTF-8";
+ private static final String COULD_NOT_GENERATE_FEED_ERROR = "Could not generate feed";
+
+ private static final DateFormat DATE_PARSER = new SimpleDateFormat("yyyy-MM-dd");
+
+ private String _defaultFeedType;
+
+ public void init() {
+ _defaultFeedType = getServletConfig().getInitParameter(DEFAULT_FEED_TYPE);
+ _defaultFeedType = (_defaultFeedType!=null) ? _defaultFeedType : "atom_0.3";
+ }
+
+ public void doGet(HttpServletRequest req,HttpServletResponse res) throws IOException {
+ try {
+ SyndFeed feed = getFeed(req);
+
+ String feedType = req.getParameter(FEED_TYPE);
+ feedType = (feedType!=null) ? feedType : _defaultFeedType;
+ feed.setFeedType(feedType);
+
+ res.setContentType(MIME_TYPE);
+ SyndFeedOutput output = new SyndFeedOutput();
+ output.output(feed,res.getWriter());
+ }
+ catch (FeedException ex) {
+ String msg = COULD_NOT_GENERATE_FEED_ERROR;
+ log(msg,ex);
+ res.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR,msg);
+ }
+ }
+
+ protected SyndFeed getFeed(HttpServletRequest req) throws IOException,FeedException {
+ SyndFeed feed = new SyndFeedImpl();
+
+ feed.setTitle("Sample Feed (created with ROME)");
+ feed.setLink("http://rome.dev.java.net");
+ feed.setDescription("This feed has been created using ROME (Java syndication utilities");
+
+ List entries = new ArrayList();
+ SyndEntry entry;
+ SyndContent description;
+
+ entry = new SyndEntryImpl();
+ entry.setTitle("ROME v0.1");
+ entry.setLink("http://wiki.java.net/bin/view/Javawsxml/rome01");
+ try {
+ entry.setPublishedDate(DATE_PARSER.parse("2004-06-08"));
+ }
+ catch (ParseException ex) {
+ // IT CANNOT HAPPEN WITH THIS SAMPLE
+ }
+ description = new SyndContentImpl();
+ description.setType("text/plain");
+ description.setValue("Initial release of ROME");
+ entry.setDescription(description);
+ entries.add(entry);
+
+ entry = new SyndEntryImpl();
+ entry.setTitle("Rome v0.2");
+ entry.setLink("http://wiki.java.net/bin/view/Javawsxml/rome02");
+ try {
+ entry.setPublishedDate(DATE_PARSER.parse("2004-06-16"));
+ }
+ catch (ParseException ex) {
+ // IT CANNOT HAPPEN WITH THIS SAMPLE
+ }
+ description = new SyndContentImpl();
+ description.setType("text/plain");
+ description.setValue("Bug fixes, minor API changes and some new features"+
+ "<p>For details check the <a href=\"https://rometools.jira.com/wiki/display/ROME/Change+Log#ChangeLog-Changesmadefromv0.2tov0.3\">Changes Log for 0.2</a></p>");
+ entry.setDescription(description);
+ entries.add(entry);
+
+ entry = new SyndEntryImpl();
+ entry.setTitle("ROME v0.3");
+ entry.setLink("http://wiki.java.net/bin/view/Javawsxml/rome03");
+ try {
+ entry.setPublishedDate(DATE_PARSER.parse("2004-07-27"));
+ }
+ catch (ParseException ex) {
+ // IT CANNOT HAPPEN WITH THIS SAMPLE
+ }
+ description = new SyndContentImpl();
+ description.setType("text/html");
+ description.setValue("<p>Bug fixes, API changes, some new features and some Unit testing</p>"+
+ "<p>For details check the <a href=\"https://rometools.jira.com/wiki/display/ROME/Change+Log#ChangeLog-Changesmadefromv0.3tov0.4\">Changes Log for 0.3</a></p>");
+ entry.setDescription(description);
+ entries.add(entry);
+
+ entry = new SyndEntryImpl();
+ entry.setTitle("ROME v0.4");
+ entry.setLink("http://wiki.java.net/bin/view/Javawsxml/rome04");
+ try {
+ entry.setPublishedDate(DATE_PARSER.parse("2004-09-24"));
+ }
+ catch (ParseException ex) {
+ // IT CANNOT HAPPEN WITH THIS SAMPLE
+ }
+ description = new SyndContentImpl();
+ description.setType("text/html");
+ description.setValue("<p>Bug fixes, API changes, some new features, Unit testing completed</p>"+
+ "<p>For details check the <a href=\"https://rometools.jira.com/wiki/display/ROME/Change+Log#ChangeLog-Changesmadefromv0.4tov0.5\">Changes Log for 0.4</a></p>");
+ entry.setDescription(description);
+ entries.add(entry);
+
+ feed.setEntries(entries);
+
+ return feed;
+ }
+
+}
+
+
To use the FeedServlet we need to create a Web Application. For the Web Application we need a deployment descriptor, the web.xml file:
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 in a default localhost Tomcat installation.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/TheCopyFromInterface.html b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/TheCopyFromInterface.html
new file mode 100644
index 0000000..278e26e
--- /dev/null
+++ b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/TheCopyFromInterface.html
@@ -0,0 +1,181 @@
+
+
+
+
+
+ ROME - The CopyFrom interface
+
+
+
+
+
+
+
+
+
+
The CopyFrom interface defines functionality similar to a deep cloning. The difference with the clone() method (besides the deep cloning requirements) is that the object to be the copy of the original one has to be explicitly created and it is this object the one that triggers the deep copying process. Implemetations of the CopyFrom interface should work propertly on arrays, collections, CopyFrom and basic type properties.
+
Using CopyFrom objects enables copying data between different implementations of a given interface without these implementation having to know about each other.
+
CopyFrom is unidirectional. A class implementing the CopyFrom knows how to extract properties from the given class (commonly having an interface in common).
+
A simple example using the CopyFrom interface is:
+
+
+ public interface Foo extends CopyFrom {
+ public void setName(String name);
+ public String getName();
+
+ public void setValues(Set values);
+ public Set getValues();
+ }
+
+ public class FooImplA implements Foo {
+ private String _name;
+ private Set _values;
+
+ public void setName(String name) {
+ _name = name;
+ }
+
+ public String getName() {
+ return _name;
+ }
+
+ public void setValues(Set values) {
+ _values = values;
+ }
+
+ public Set getValues() {
+ return _values;
+ }
+
+ public void copyFrom(Object obj) {
+ Foo other = (Foo) obj;
+ setName(other.getName());
+ setValues(new HashSet(other.getValues());
+ }
+
+ public Class getInterface() {
+ return Foo.class;
+ }
+ }
+
+ public class FooImplB implements Foo {
+ private Map _data;
+
+ public FooImplB() {
+ _data = new HashMap();
+ }
+
+ public void setName(String name) {
+ _data.put("name",name);
+ }
+
+ public String getName() {
+ return (String) _data.get("name");
+ }
+
+ public void setValues(Set values) {
+ _data.put("values",values);
+ }
+
+ public Set getValues() {
+ return (Set) _data.get("values");
+ }
+
+ public void copyFrom(Object obj) {
+ Foo other = (Foo) obj;
+ setName(other.getName());
+ setValues(new HashSet(other.getValues());
+ }
+
+ public Class getInterface() {
+ return Foo.class;
+ }
+ }
+
+
A use case for the CopyFrom functionality is a Java Bean implementation of an interface and a persistency implementation (such as Hibernate) of the the same interface that may add extra persistency related properties to the bean (ie, the 'Id' property as the persistency layer primary key).
+
For bean, array and collection properties the bean being invoked which copyFrom() method is invoked is responsible for those properties.
+
For properties implementing the CopyFrom interface, the bean must create a property instance implementing the interface returned by the getInterface() method. This allows the bean doing the copyFrom() to handle specialized subclasses of property elements propertly. This is also applicacle to array and collection properties. The 'modules' property of the SyndFeed and SyndEntry beans is a use case of this feature where the copyFrom() invocation must create different beans subclasses for each type of module, the getInteface() helps to find the right implementation.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/UnderstandingRssAndAtOMUtilitiEsROMEBeanUtilities.html b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/UnderstandingRssAndAtOMUtilitiEsROMEBeanUtilities.html
new file mode 100644
index 0000000..939cbdc
--- /dev/null
+++ b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/UnderstandingRssAndAtOMUtilitiEsROMEBeanUtilities.html
@@ -0,0 +1,209 @@
+
+
+
+
+
+ ROME - Understanding Rss and atOM utilitiEs (ROME) Bean Utilities
+
+
+
+
+
+
+
+
+
+
Understanding Rss and atOM utilitiEs (ROME) Bean Utilities
+
ROME bean utilities are not part of ROME public API. They are used by the default implementation of ROME beans and it may be useful for alternate implementations as well. It is important to keep in mind that these APIs are not public and they are subject to change breaking backward compatibility.
+
Rome com.sun.syndication.feed.impl package contains a set of Java classes that provide support for all the basic features Java Beans commonly must have: toString, equals, hashcode and cloning.
+
By using these classes Beans don't have to hand code these functions. This greatly simplifies things when Beans have several properties, collection properties and composite properties.
+
The CloneableBean, EqualsBean, ToStringBean and ObjectBean classes use instrospection on the properties of the classes using them. This is done recursively on all properties. All ROME Beans default implementations leverage these classes.
+
+
ToStringBean
+
Beans implementing the ToString interface must implement the toString(String prefix) method. This method must print the bean properties names and values, one per per line, separating the name and value with an '=' sign and prefixing the name with the given prefix parameter using the same notation used in the JSP expression language used in JSTL and in JSP 2.0. This must be done recursively for all array, collection and ToString properties.
+
The ToStringBean class provides an implementation of the toString() method producing a detailed output of all the properties of the Bean being processed. The ToStringBean constructor takes the class definition the ToStringBean class should use for properties scanning -using instrospection- for printing, normally it is the class of the Bean using the ToStringBean.
+
+
Using the ToStringBean class
+
+
+ public class MyBean {
+
+ public Foo getFoo() { ... }
+ public void setFoo(Foo foo) { ... }
+
+ public String getName() { ... }
+ public void setName(String name) { ... }
+
+ public List getValues() { ... }
+ public void setValues(List values) { ... }
+
+ public String toString(String prefix) {
+ ToStringBean tsBean = new ToStringBean(MyBean.class,this);
+ return tsBean.toString(prefix);
+ }
+
+ public String toString() {
+ return toString("myBean");
+ }
+ }
+
+
+
EqualBean
+
The EqualsBean class provides a recursive introspetion-based implementation of the equals() and hashCode() methods working on the Bean properties. The EqualsBean constructor takes the class definition that should be properties scanned (using introspection) by the equals() and thehashCode() methods. The EqualsBean class works on array, collection, bean and basic type properties.
+
+
Using the EqualsBean class
+
+
+ public class MyBean {
+
+ public Foo getFoo() { ... }
+ public void setFoo(Foo foo) { ... }
+
+ public String getName() { ... }
+ public void setName(String name) { ... }
+
+ public List getValues() { ... }
+ public void setValues(List values) { ... }
+
+ public boolean equals(Object obj) {
+ EqualsBean eBean = new EqualsBean(MyBean.class,this);
+ return eBean.beanEquals(obj);
+ }
+
+ public int hashCode() {
+ EqualsBean equals = new EqualsBean(MyBean.class,this);
+ return equals.beanHashCode();
+ }
+ }
+
+
+
CloneableBean
+
The CloneableBean class provides a recursive introspetion-based implementation of the clone() method working on the Bean properties. The CloneableBean class works on array, collection, bean and basic type properties.
+
+
Using the CloneableBean class
+
+
+ public class MyBean implements Cloneable {
+
+ public Foo getFoo() { ... }
+ public void setFoo(Foo foo) { ... }
+
+ public String getName() { ... }
+ public void setName(String name) { ... }
+
+ public List getValues() { ... }
+ public void setValues(List values) { ... }
+
+ public Object clone() {
+ CloneableBean cBean = new CloneableBean(this);
+ return cBean.beanClone();
+ }
+ }
+
+
By default, the CloneableBean copies all properties of the given object. It also supports an ignore-properties set, the property names in this set will not be copied to the cloned instance. This is useful for cases where the Bean has convenience properties (properties that are actually references to other properties or properties of properties). For example SyndFeed and SyndEntry beans have convenience properties, publishedDate, author, copyright and categories all of them mapped to properties in the DC Module.
+
+
ObjectBean
+
The ObjectBean is a convenience bean providing ToStringBean, EqualsBean and CloneableBean functionality support. Also, ObjectBeans implements the Serializable interface making the beans serializable if all its properties are. Beans extending ObjectBean get toString(), equals(),hashCode() and clone() support as defined above.
+
And example of using the ObjectBean class is:
+
+
+ public class MyBean extends ObjectBean {
+
+ public MyBean() {
+ super(MyBean.class);
+ }
+
+ public Foo getFoo() { ... }
+ public void setFoo(Foo foo) { ... }
+
+ public String getName() { ... }
+ public void setName(String name) { ... }
+
+ public List getValues() { ... }
+ public void setValues(List values) { ... }
+ }
+
+
It can also be used in delegation mode instead as some of the previous examples.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.html b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.html
new file mode 100644
index 0000000..648190c
--- /dev/null
+++ b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/XMLCharsetEncodingDetectionHowRssAndAtOMUtilitiEsROMEHelpsGettingTheRightCharsetEncoding.html
@@ -0,0 +1,204 @@
+
+
+
+
+
+ ROME - XML Charset Encoding detection, how Rss and atOM utilitiEs (ROME) helps getting the right charset encoding
+
+
+
+
+
+
+
+
+
+
XML Charset Encoding detection, how Rss and atOM utilitiEs (ROME) helps getting the right charset encoding
+
Determining the charset set encoding of an XML document it may prove not as easy as it seems, and when the XML document is served over HTTP things get a little more hairy.
+
Current Java libraries or utilities don't do this by default, A JAXP SAX parser may detect the charset encoding of a XML document looking at the first bytes of the stream as defined Section 4.3.3 and Appendix F.1 of the in XML 1.0 (Third Edition) specification. But Appendix F.1 is non-normative and not all Java XML parsers do it right now. For example the JAXP SAX parser implementation in J2SE 1.4.2 does not handle Appendix F.1 and Xerces 2.6.2 just added support for it. But still this does not solve the whole problem. JAXP SAX parsers are not aware of the HTTP transport rules for charset encoding resolution as defined by RFC 3023. They are not because they operate on a byte stream or a char stream without any knowledge of the stream transport protocol, HTTP in this case.
To isolate developers from this issue ROME has a special character stream class, the XmlReader. The XmlReader class is a subclass of the java.io.Reader that detects the charset encoding of XML documents read from files, input streams, URLs and input streams obtained over HTTP. Ideally this should be built into the JAXP SAX classes, most likely in the InputSource class.
+
+
Default Lenient Behavior
+
It is very common for many sites, due to improper configuration or lack of knowledge, to declare an invalid charset encoding. Invalid according to the XML 1.0 specification and the RFC 3023. For example a mismatch between the implicit charset encoding in the HTTP content-type and the explicit charset encoding in the XML prolog.
+
Because of this, ROME XmlReader by default has a lenient detection. This lenient detection works in the following order:
+
+
A strict charset encoding detection, as specified by the Algorithms below is attempted
+
If the content type was 'text/html' it replaces it with 'text/xml' and tries strict charset encoding detection again
+
If the XML prolog had a charset encoding that encoding is used
+
If the content type had a charset encoding that encoding is used
+
'UTF-8' is used
+
The XmlReader class has 2 constructors that allow a strict (non-lenient) charset encoding detection to be performed. This constructors take a lenient boolean flag, the flag should be set to false for a strict detection.
+
+
The Algorithms per XML 1.0 and RFC 3023 specifications
+
Following it's a detailed explanation on the algorithms the XmlReader uses to determine the charset encoding. These algorithms first appeared in Tucu's Weblog.
+
+
Raw XML charset encoding detection
+
Detection of the charset encoding of a XML document without external information (i.e. reading a XML document from a file). Following Section 4.3.3 and Appendix F.1 of the XML 1.0 specification the charset encoding of an XML document is determined as follows:
+
+
+BOMEnc : byte order mark. Possible values: 'UTF-8', 'UTF-16BE', 'UTF-16LE' or NULL
+XMLGuessEnc: best guess using the byte representation of the first bytes of XML declaration
+ ('<?xml...?>') if present. Possible values: 'UTF-8', 'UTF-16BE', 'UTF-16LE' or NULL
+XMLEnc : encoding in the XML declaration ('<?xml encoding="..."?>'). Possible values: anything or NULL
+
+if BOMEnc is NULL
+ if XMLGuessEnc is NULL or XMLEnc is NULL
+ encoding is 'UTF-8' [1.0]
+ else
+ if XMLEnc is 'UTF-16' and (XMLGuessEnc is 'UTF-16BE' or XMLGuessEnc is 'UTF-16LE')
+ encoding is XMLGuessEnc [1.1]
+ else
+ encoding is XMLEnc [1.2]
+else
+if BOMEnc is 'UTF-8'
+ if XMLGuessEnc is not NULL and XMLGuessEnc is not 'UTF-8'
+ ERROR, encoding mismatch [1.3]
+ if XMLEnc is not NULL and XMLEnc is not 'UTF-8'
+ ERROR, encoding mismatch [1.4]
+ encoding is 'UTF-8'
+else
+if BOMEnc is 'UTF-16BE' or BOMEnc is 'UTF-16LE'
+ if XMLGuessEnc is not NULL and XMLGuessEnc is not BOMEnc
+ ERROR, encoding mismatch [1.5]
+ if XMLEnc is not NULL and XMLEnc is not 'UTF-16' and XMLEnc is not BOMEnc
+ ERROR, encoding mismatch [1.6]
+ encoding is BOMEnc
+else
+ ERROR, cannot happen given BOMEnc possible values (see above) [1.7]
+
+
Byte Order Mark encoding and XML guessed encoding detection rules are clearly explained in the XML 1.0 Third Edition Appendix F.1. Note that in this algorithm BOMEnc and XMLGuessEnc are restricted to UTF-8 and UTF-16* encodings.
+
+
#1.0. There is no BOM, an encoding or encoding family cannot be guessed from the first bytes in the stream, defaulting to UTF-8.
+
#1.1. Strictly following XML 1.0 Third Edition Section 4.3.3 Charset Encoding in Entities (2nd paragraph) no BOM and UTF-16 XML declaration encoding is an error. The BOM is required to identify if the encoding is BE or LE. But if XMLEnc was read it means that the encoding byte order of the stream was guessed from the first bytes in the stream, note that this is possible only if the document starts with a XML declaration. The logic verifies that there is no conflicting encoding information and relaxes the BOM requirement if a XML declaration (that allows guessing the byte order) is present.
+
#1.2. XMLEnc is present, it is not UTF-16 (although it can be UTF-16BE or UTF-16LE), the guessed encoding is used to read the XML declaration encoding. Detecting encoding mismatches here it would require awareness of charset families, instead the algorithm relies on the charset encoding routines that will process the stream to discover and report mismatches. IMPORTANT: To handle other encodings (i.e. USC-4 or EBCDIC encoding families) the algorithm should be extended here.
+
#1.3, #1.4, #1.5, #1.6 There is an explicit encoding mismatch.
+
#1.7. Given the currently assumed BOMEnc values this case cannot happen. IMPORTANT: To handle other encodings (i.e. USC-4 or EBCDIC encoding families) the algorithm should be extended here.
+
+
XML over HTTP charset encoding detection
+
Detection of the charset encoding of a XML document with external information (provided by HTTP). Following Section 4.3.3, Appendix F.1 and Appendix F.2 of the XML 1.0 specification, plus RFC 3023 the charset encoding of an XML document served over HTTP is determined as follows:
+
+
+ContentType: Content-Type HTTP header
+CTMime : MIME type defined in the ContentType
+CTEnc : charset encoding defined in the ContentType, NULL otherwise
+BOMEnc : byte order mark. Possible values: 'UTF-8', 'UTF-16BE', 'UTF-16LE' or NULL
+XMLGuessEnc: best guess using the byte representation of the first bytes of XML declaration
+ ('<?xml...?>') if present. Possible values: 'UTF-8', 'UTF-16BE', 'UTF-16LE' or NULL
+XMLEnc : encoding in the XML declaration ('<?xml encoding="..."?>'). Possible values: anything or NULL
+APP-XML : RFC 3023 defined 'application/*xml' types
+TEXT-XML : RFC 3023 defined 'text/*xml' types
+
+if CTMime is APP-XML or CTMime is TEXT-XML
+ if CTEnc is NULL
+ if CTMime is APP-XML
+ encoding is determined using the Raw XML charset encoding detection algorithm [2.0]
+ else
+ if CTMime is TEXT-XML
+ encoding is 'US-ASCII' [2.1]
+ else
+ if (CTEnc is 'UTF-16BE' or CTEnc is 'UTF-16LE') and BOMEnc is not NULL
+ ERROR, RFC 3023 explicitly forbids this [2.2]
+ else
+ if CTEnc is 'UTF-16'
+ if BOMEnc is 'UTF-16BE' or BOMEnc is 'UTF-16LE'
+ encoding is BOMEnc [2.3]
+ else
+ ERROR, missing BOM or encoding mismatch [2.4]
+ else
+ encoding is CTEnc [2.5]
+else
+ ERROR, handling for other MIME types is undefined [2.6]
+
+
Byte Order Mark encoding and XML guessed encoding detection rules are clearly explained in the XML 1.0 Third Edition Appendix F.1. Note that in this algorithm BOMEnc and XMLGuessEnc are restricted to UTF-8 and UTF-16* encodings.
+
+
#2.0. HTTP content type declares a MIME of application type and XML sub-type. There is not HTTP Content-type charset encoding information. The charset encoding is determined using the Raw XML charset encoding detection algorithm. Refer to RFC 3023 Section 3.2. Application/xml Registration.
+
#2.1. HTTP content type declares a MIME of text type and XML sub-type. There is not HTTP Content-type charset encoding information. The charset encoding is US-ASCII. Refer to RFC 3023 Section 3.1. Text/xml Registration.
+
#2.2. For text-XML and application-XML MIME types if the HTTP content type declares 'UTF-16BE' or 'UTF-16LE' as the charset encoding, a BOM is prohibited. Refer to RFC 3023 Section 4. The Byte Order Mark (BOM) and Conversions to/from the UTF-16 Charset.
+
#2.3. For text-XML and application-XML MIME types if the HTTP content type declares 'UTF-16' as the charset encoding, a BOM is required and it must be used to determine the byte order. Refer to RFC 3023 Section 4. The Byte Order Mark (BOM) and Conversions to/from the UTF-16 Charset.
+
#2.4. For text-XML and application-XML MIME types if the HTTP content type declares 'UTF-16' as the charset encoding, a BOM must be present and it must be 'UTF-16BE' or 'UTF-16LE'. Refer to RFC 3023 Section 4. The Byte Order Mark (BOM) and Conversions to/from the UTF-16 Charset.
+
#2.5. For text-XML and application-XML MIME types if the HTTP content type declares a charset encoding other than the UTF-16 variants, that charset encoding is used, no other special handling is required.
+
#2.6. There is not defined logic to determine the charset encoding based on the MIME type given by the HTTP content type.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/index.html b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/index.html
new file mode 100644
index 0000000..ee4a7dd
--- /dev/null
+++ b/RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/index.html
@@ -0,0 +1,125 @@
+
+
+
+
+
+ ROME - Rss and atOM utilitiEs (ROME) v0.5 and above Tutorials and Articles
+
+
+
+
+
+
+
+
+
+
Rss and atOM utilitiEs (ROME) v0.5 and above Tutorials and Articles
+
+
Tutorials
+
The following tutorials show how to use the ROME API. They focus on the higher abstraction layer of classes offered by ROME, what we call the Synd* classes. By using the Synd* classes developers don't have to deal with the specifics of any syndication feed. They work with normalized feeds, the Synd* feeds. This makes it much easier to write applications that have to deal with all the variety of syndication feed types in use today.
java.net - Taking a Tour of ROME by Randy J. Ray (February 2, 2006). Working with web syndication? Your development path may lead you to ROME--not the city, but the syndication framework, which makes working with RSS and Atom a breeze for both server-and client-side code. Randy J. Ray has an introduction to this project.
java.net - Taking a Tour of ROME by Randy J. Ray (February 2, 2006). Working with web syndication? Your development path may lead you to ROME--not the city, but the syndication framework, which makes working with RSS and Atom a breeze for both server-and client-side code. Randy J. Ray has an introduction to this project.
+
+
+
\ No newline at end of file
diff --git a/WhatPartOfTheAPIYouShouldBeUsing.html b/WhatPartOfTheAPIYouShouldBeUsing.html
new file mode 100644
index 0000000..24baff6
--- /dev/null
+++ b/WhatPartOfTheAPIYouShouldBeUsing.html
@@ -0,0 +1,101 @@
+
+
+
+
+
+ ROME - What part of the API you should be using
+
+
+
+
+
+
+
+
+
+
Rome API allows developers to work with classes that closely resemble a particular syndication feed type. For example, the Channel class for RSS feeds and the Feed class for Atom feeds. All the Synd* classes, which leverage the RSS and Atom specific classes, are the bridge to go from one syndication type to another.
+
For day to day coding, we found ourselves using the Synd* classes (in com.sun.syndication.feed.synd, com.sun.syndication.feed.module and com.sun.syndication.io packages) as we need to do applications that understand the different syndication feed types. And it is much simpler to work with a higher and independent abstraction.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/WhatSWrongWithOtherExistingRSSParsingLibraries.html b/WhatSWrongWithOtherExistingRSSParsingLibraries.html
new file mode 100644
index 0000000..ae593d7
--- /dev/null
+++ b/WhatSWrongWithOtherExistingRSSParsingLibraries.html
@@ -0,0 +1,130 @@
+
+
+
+
+
+ ROME - What's wrong with other existing RSS parsing libraries?
+
+
+
+
+
+
+
+
+
+
What's wrong with other existing RSS parsing libraries?
+
Before we started with Rome we've evaluated other Java syndication management libraries to see if they'd fit our criteria. Feel free to update this evaluation if we forgot or mischaracterized your favorite library: this is a wiki after all:-)
They have some interesting features such as Hibernate and Castor based database serialization, and JSP taglibs, which are useful paraphernalia for server side application development. This seems to be their main focus of development today.
+
But we prefer to focus on our ESCAPE design criteria, so that our library does one thing really well: syndication parsing, abstract representation and conversion from/to all formats.
+
Thus our library will be useful for both client and server side developers.
+
We will develop the server side add-on later when the basics will be well oiled.
+
+
RSS4J
+
RSS4J was released in version 0.92 in april 2002. It did not evolve since then.
+
The web site explains:
+
This toolkit supports the three most commonly used RSS standards - 0.90 (the original), 0.91 and 1.0. RSS 0.92 and 0.93 are not supported due to the dramatic changes it makes to the format and the fact that 1.0 is already finalized.
+
No need to say more: it seems to be a dead project and doesn't even start to address our requirements.
+
+
RSS Utilities
+
RSS Utilities seems like a one-shot project from Rodrigo Oliveira, released in august 2003. It is a taglib to display RSS in JSPs, and includes a small parser for RSS 0.91, 0.92 and 2.0.
+
It does not seem to be maintained, does not address RSS 1.0 and Atom.
+
I would encourage Rodrigo to rewrite his taglibs using Rome as the parser, and eventually to contribute them to Rome.
+
+
RSSLibJ
+
RSSLibJ is a full-Java RSS generation and consumption library, primarily centering on generating RSS feeds but able to consume them as well. It's maintained, but undergoing a refactoring to change a rather undesirable dependency.
+
(This isn't a review - this was added by one of RSSLibJ 's authors.)
+
+
Sandler
+
Sandler is yet another parser except that it only supports Atom feeds. I can't say more than that because I haven't used it. And now I won't have to.
+
+
Conclusion
+
These are the only RSS or Syndication management libraries we found in Java when we reviewed what was available and wether it was worth starting a new project. Feel free to add to it if we forgot something.
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/WhyThisProject.html b/WhyThisProject.html
new file mode 100644
index 0000000..4a56109
--- /dev/null
+++ b/WhyThisProject.html
@@ -0,0 +1,110 @@
+
+
+
+
+
+ ROME - Why this project?
+
+
+
+
+
+
+
+
+
+
Various flavors of RSS and Atom syndication formats were reaching a tipping point in 2004. At Sun we started various projects involving these Syndication formats, but when looking around for Java libraries to take care of the parsing and generation of RSS we were not satisfied with what we found. Project ROME was started out of this frustration.
+
Our requirements are to ESCAPE from Syndication Feeds Hell. In order to allow that the library must be:
+
+
*E*asy to use: given a url, get back a feed object independent of the underlying format, and serialize the feed object to the format I want.
+
*S*imple: RSS initially stood for "Really Simple Syndication"*, and this simplicity is what made the format successful. Specifications wars have made the current situation much more complicated. The goal of the library is to give that simplicity back to developers: each API we use force on us a mental model of the domain and we are using more and more libraries on each project we implement. This library tries to ease the cognitive load of developers and provides a very simple model for feeds and entries, abstarcting out the details of the various underlying formats.
+
*C*omplete: must handle all versions of RSS and Atom
+
*A*bstract: provides a Java-friendly abstraction layer on top of the various syndication specifications, that maps the commonalities of the various feed formats into a single simple JavaBeans Data Model.
+
*P*owerful: lets me access all the metadata of the feeds regardless of their format. If I need them, lets me access optional metadata expressed in extensions accepted by various formats (RSS 1.0 modules, other namespaces in Atom).
+
*E*xtensible: It needs to define a simple pluggable architecture to provide support for future extensions of the formats.
+
* - not so, it was originally "RDF Site Summary", see: RSS History
Copies all the properties of the given bean into this one.
+
+ Any existing properties in this bean are lost.
+
+ This method is useful for moving from one implementation of a bean interface to another.
+ For example from the default SyndFeed bean implementation to a Hibernate ready implementation.
+
+Parent class of the RSS (Channel) and Atom (Feed) feed beans.
+
+ NOTE: We don't like this class at this package level but the alternative would have
+ been a proliferation of packages (one more level to hold atom and rss package with
+ this class just in that package).
+
+ The format of the 'type' property must be [FEEDNAME]_[FEEDVERSION] with the FEEDNAME in lower case,
+ for example: rss_0.9, rss_0.93, atom_0.3
+
SyndFeedImpl(WireFeed feed)
+
+
+ Creates a SyndFeedImpl and populates all its properties out of the
+ given RSS Channel or Atom Feed properties.
+
+
+
SyndFeedImpl(WireFeed feed,
+ boolean preserveWireFeed)
+
+
+ Creates a SyndFeedImpl and populates all its properties out of the
+ given RSS Channel or Atom Feed properties, while optionally preserving
+ the WireFeed for access via the orignalWireFeed() method.
WireFeedGenerator.generate(WireFeed feed)
+
+
+ Creates an XML document (JDOM) for the given feed bean.
+
+
+
+ void
+
WireFeedOutput.output(WireFeed feed,
+ File file)
+
+
+ Creates a File containing with the XML representation for the given WireFeed.
+
+
+
+ void
+
WireFeedOutput.output(WireFeed feed,
+ File file,
+ boolean prettyPrint)
+
+
+ Creates a File containing with the XML representation for the given WireFeed.
+
+
+
+ void
+
WireFeedOutput.output(WireFeed feed,
+ Writer writer)
+
+
+ Writes to an Writer the XML representation for the given WireFeed.
+
+
+
+ void
+
WireFeedOutput.output(WireFeed feed,
+ Writer writer,
+ boolean prettyPrint)
+
+
+ Writes to an Writer the XML representation for the given WireFeed.
+
+
+
+ org.jdom.Document
+
WireFeedOutput.outputJDom(WireFeed feed)
+
+
+ Creates a JDOM document for the given WireFeed.
RSS20wNSParser.parseChannel(org.jdom.Element rssRoot)
+
+
+ After we parse the feed we put "rss_2.0" in it (so converters and generators work)
+ this parser is a phantom.
+ It works on all read/write properties, recursively. It support all primitive types, Strings, Collections,
+ Cloneable objects and multi-dimensional arrays of any of them.
+
Creates a CloneableBean to be used in a delegation pattern.
+
+ For example:
+
+
+ public class Foo implements Cloneable {
+ private CloneableBean _cloneableBean;
+
+ public Foo() {
+ _cloneableBean = new CloneableBean(this);
+ }
+
+ public Object clone() throws CloneNotSupportedException {
+ return _cloneableBean.beanClone();
+ }
+
+ }
+
+
+
+
+
Parameters:
obj - object bean to clone.
+
+
+
+
+CloneableBean
+
+public CloneableBean(Object obj,
+ Set ignoreProperties)
+
+
Creates a CloneableBean to be used in a delegation pattern.
+
+ The property names in the ignoreProperties Set will not be copied into
+ 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.
+
+
+
+
Parameters:
obj - object bean to clone.
ignoreProperties - properties to ignore when cloning.
+ To be used by classes extending CloneableBean. Although it works also for classes using
+ CloneableBean in a delegation pattern, for correctness those classes should use the
+
+Provides deep Bean equals() and hashCode() functionality for Java Beans.
+
+ It works on all read/write properties, recursively. It support all primitive types, Strings, Collections,
+ bean-like objects and multi-dimensional arrays of any of them.
+
+ The hashcode is calculated by getting the hashcode of the Bean String representation.
+
EqualsBean(Class beanClass,
+ Object obj)
+
+
+ Creates a EqualsBean to be used in a delegation pattern.
+
+
+
+
+
+
+
+
+
+Method Summary
+
+
+
+ boolean
+
beanEquals(Object obj)
+
+
+ Indicates whether some other object is "equal to" the object passed in the constructor,
+ as defined by the Object equals() method.
+
+
+
+ int
+
beanHashCode()
+
+
+ Returns the hashcode for the object passed in the constructor.
+
+
+
+ boolean
+
equals(Object obj)
+
+
+ Indicates whether some other object is "equal to" this object as defined by the Object equals() method.
+
+
+
+ int
+
hashCode()
+
+
+ Returns the hashcode for this object.
Indicates whether some other object is "equal to" this object as defined by the Object equals() method.
+
+ To be used by classes extending EqualsBean. Although it works also for classes using
+ EqualsBean in a delegation pattern, for correctness those classes should use the
+
+ It follows the contract defined by the Object hashCode() method.
+
+ The hashcode is calculated by getting the hashcode of the Bean String representation.
+
+ To be used by classes extending EqualsBean. Although it works also for classes using
+ EqualsBean in a delegation pattern, for correctness those classes should use the
+
+Convenience class providing clone(), toString(), equals() and hashCode() functionality for Java Beans.
+
+ It works on all read/write properties, recursively.
+
+ It uses the CloneableBean, EqualsBean and ToStringBean classes in a delegation pattern.
+
+
ObjectBean programming conventions
+
+ All ObjectBean subclasses having properties that return collections they should never
+ return null if the property has been set to null or if a collection has not been set.
+ They should create and return an empty collection, this empty collection instance should
+ also be set to the corresponding property.
+
+ All ObjectBean subclasses properties should be live references.
+
beanClass - the class/interface to be used for property scanning.
+
+
+
+
+ObjectBean
+
+public ObjectBean(Class beanClass,
+ Object obj,
+ Set ignoreProperties)
+
+
Constructor.
+
+ The property names in the ignoreProperties Set will not be copied into
+ 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.
+
+
+
+
Parameters:
beanClass - the class/interface to be used for property scanning.
ignoreProperties - properties to ignore when cloning.
+ It works on all read/write properties, recursively. It support all primitive types, Strings, Collections,
+ ToString objects and multi-dimensional arrays of any of them.
+
Unmodifiable Set containing the convenience properties of this class.
+
+ Convenience properties are mapped to Modules, for cloning the convenience
+ properties can be ignored as the will be copied as part of the module
+ cloning.
+
+
+
+
+
+
+
+
+
+
+
+Constructor Detail
+
+
+
+
+DCModuleImpl
+
+public DCModuleImpl()
+
+
Default constructor. All properties are set to null.
+
Copies all the properties of the given bean into this one.
+
+ Any existing properties in this bean are lost.
+
+ This method is useful for moving from one implementation of a bean interface to another.
+ For example from the default SyndFeed bean implementation to a Hibernate ready implementation.
+
Copies all the properties of the given bean into this one.
+
+ Any existing properties in this bean are lost.
+
+ This method is useful for moving from one implementation of a bean interface to another.
+ For example from the default SyndFeed bean implementation to a Hibernate ready implementation.
+
+Base class for modules describing Metadata of feeds, default implementations.
+ Examples of such modules are the Dublin Core and Syndication modules.
+
Copies all the properties of the given bean into this one.
+
+ Any existing properties in this bean are lost.
+
+ This method is useful for moving from one implementation of a bean interface to another.
+ For example from the default SyndFeed bean implementation to a Hibernate ready implementation.
+
RSS090Generator.populateChannel(Channel channel,
+ org.jdom.Element eChannel)
+
+
+ Populates the given channel with parsed data from the ROME element that holds the
+ channel data.
RSS10Parser.parseItem(org.jdom.Element rssRoot,
+ org.jdom.Element eItem)
+
+
+ Parses an item element of an RSS document looking for item information.
RSS091UserlandParser.parseItem(org.jdom.Element rssRoot,
+ org.jdom.Element eItem)
+
+
+ Parses an item element of an RSS document looking for item information.
RSS090Parser.parseItem(org.jdom.Element rssRoot,
+ org.jdom.Element eItem)
+
+
+ Parses an item element of an RSS document looking for item information.
Copies all the properties of the given bean into this one.
+
+ Any existing properties in this bean are lost.
+
+ This method is useful for moving from one implementation of a bean interface to another.
+ For example from the default SyndFeed bean implementation to a Hibernate ready implementation.
+
Copies all the properties of the given bean into this one.
+
+ Any existing properties in this bean are lost.
+
+ This method is useful for moving from one implementation of a bean interface to another.
+ For example from the default SyndFeed bean implementation to a Hibernate ready implementation.
+
+ How the entry URI maps to a concrete feed type (RSS or Atom) depends on
+ the concrete feed type. This is explained in detail in Rome documentation,
+ Feed and entry URI mapping.
+
+ The returned URI is a normalized URI as specified in RFC 2396bis.
+
+ How the entry URI maps to a concrete feed type (RSS or Atom) depends on
+ the concrete feed type. This is explained in detail in Rome documentation,
+ Feed and entry URI mapping.
+
+ For Atom feeds, this returns the authors as a list of SyndPerson objects,
+ for RSS feeds this method is a convenience method, it maps to the
+ Dublin Core module creator.
+
+ For Atom feeds, this sets the authors as a list of SyndPerson
+ objects, for RSS feeds this method is a convenience method, it maps
+ to the Dublin Core module creator.
+
Returns the name of the first entry author in the collection of authors.
+
+ For Atom feeds, this returns the authors as a list of SyndPerson objects,
+ for RSS feeds this method is a convenience method, it maps to the
+ Dublin Core module creator.
+
+ For Atom feeds, this sets the feed author's name, for RSS feeds
+ this method is a convenience method, it maps to the Dublin Core
+ module creator.
+
Return the original item this SyndEntry is generated from.
+ The type of the object returned depends on the original type of
+ the feed. Atom 0.3/1.0 will return com.sun.syndication.feed.atom.Entry,
+ while RSS will return com.sun.syndication.feed.rss.Item.java.
+ If this entry was not generated from a WireFeed, or the SyndFeed
+ was not set to preserve the WireFeed then it will return null
+
+
+
+
+
+
+
Returns:
the WireFeed Item or Entry this Entry is generated from, or null
SyndEntryImpl(Class beanClass,
+ Set convenienceProperties)
+
+
+ For implementations extending SyndEntryImpl to be able to use the ObjectBean functionality
+ with extended interfaces.
Unmodifiable Set containing the convenience properties of this class.
+
+ Convenience properties are mapped to Modules, for cloning the convenience properties
+ can be ignored as the will be copied as part of the module cloning.
+
+
+
+
+
+
+
+
+
+
+
+Constructor Detail
+
+
+
+
+SyndEntryImpl
+
+protected SyndEntryImpl(Class beanClass,
+ Set convenienceProperties)
+
+
For implementations extending SyndEntryImpl to be able to use the ObjectBean functionality
+ with extended interfaces.
+
+
+
+
Parameters:
beanClass -
convenienceProperties - set containing the convenience properties of the SyndEntryImpl
+ (the are ignored during cloning, check CloneableBean for details).
+
+
+
+
+SyndEntryImpl
+
+public SyndEntryImpl()
+
+
Default constructor. All properties are set to null.
+
+ How the entry URI maps to a concrete feed type (RSS or Atom) depends on
+ the concrete feed type. This is explained in detail in Rome documentation,
+ Feed and entry URI mapping.
+
+ The returned URI is a normalized URI as specified in RFC 2396bis.
+
+ How the entry URI maps to a concrete feed type (RSS or Atom) depends on
+ the concrete feed type. This is explained in detail in Rome documentation,
+ Feed and entry URI mapping.
+
Copies all the properties of the given bean into this one.
+
+ Any existing properties in this bean are lost.
+
+ This method is useful for moving from one implementation of a bean interface to another.
+ For example from the default SyndFeed bean implementation to a Hibernate ready implementation.
+
+ For Atom feeds, this returns the authors as a list of SyndPerson objects,
+ for RSS feeds this method is a convenience method, it maps to the
+ Dublin Core module creator.
+
+ For Atom feeds, this sets the authors as a list of SyndPerson
+ objects, for RSS feeds this method is a convenience method, it maps
+ to the Dublin Core module creator.
+
Return the original item this SyndEntry is generated from.
+ The type of the object returned depends on the original type of
+ the feed. Atom 0.3/1.0 will return com.sun.syndication.feed.atom.Entry,
+ while RSS will return com.sun.syndication.feed.rss.Item.java.
+ If this entry was not generated from a WireFeed, or the SyndFeed
+ was not set to preserve the WireFeed then it will return null
+
Returns the WireFeed this SyndFeed was created from.
+ Will return null if the original feed is not stored or if this SyndFeed was not created from a WireFeed
+
+
+
+
+
+
+
Returns:
The WireFeed this was created from, or null
+
+
+
+
+
+isPreservingWireFeed
+
+boolean isPreservingWireFeed()
+
+
+
+
+
+
+
Returns:
true if this SyndFeed preserves the WireFeed it was created from
+ How the feed URI maps to a concrete feed type (RSS or Atom) depends on
+ the concrete feed type. This is explained in detail in Rome documentation,
+ Feed and entry URI mapping.
+
+ The returned URI is a normalized URI as specified in RFC 2396bis.
+
+ Note: The URI is the unique identifier, in the RSS 2.0/atom case this is
+ the GUID, for RSS 1.0 this is the URI attribute of the item. The Link
+ is the URL that the item is accessible under, the URI is the
+ permanent identifier which the aggregator should use to reference
+ this item. Often the URI will use some standardized identifier scheme
+ such as DOI's so that items can be identified even if they appear in
+ multiple feeds with different "links" (they might be on different
+ hosting platforms but be the same item). Also, though rare, there
+ could be multiple items with the same link but a different URI and
+ associated metadata which need to be treated as distinct entities.
+ In the RSS 1.0 case the URI must be a valid RDF URI reference.
+
+ How the feed URI maps to a concrete feed type (RSS or Atom) depends on
+ the concrete feed type. This is explained in detail in Rome documentation,
+ Feed and entry URI mapping.
+
+ Note: The URI is the unique identifier, in the RSS 2.0/atom case this is
+ the GUID, for RSS 1.0 this is the URI attribute of the item. The Link
+ is the URL that the item is accessible under, the URI is the
+ permanent identifier which the aggregator should use to reference
+ this item. Often the URI will use some standardized identifier scheme
+ such as DOI's so that items can be identified even if they appear in
+ multiple feeds with different "links" (they might be on different
+ hosting platforms but be the same item). Also, though rare, there
+ could be multiple items with the same link but a different URI and
+ associated metadata which need to be treated as distinct entities.
+ In the RSS 1.0 case the URI must be a valid RDF URI reference.
+
+ Note: The URI is the unique identifier, in the RSS 2.0/atom case this is
+ the GUID, for RSS 1.0 this is the URI attribute of the item. The Link
+ is the URL that the item is accessible under, the URI is the
+ permanent identifier which the aggregator should use to reference
+ this item. Often the URI will use some standardized identifier scheme
+ such as DOI's so that items can be identified even if they appear in
+ multiple feeds with different "links" (they might be on different
+ hosting platforms but be the same item). Also, though rare, there
+ could be multiple items with the same link but a different URI and
+ associated metadata which need to be treated as distinct entities.
+ In the RSS 1.0 case the URI must be a valid RDF URI reference.
+
+ Note: The URI is the unique identifier, in the RSS 2.0/atom case this is
+ the GUID, for RSS 1.0 this is the URI attribute of the item. The Link
+ is the URL that the item is accessible under, the URI is the
+ permanent identifier which the aggregator should use to reference
+ this item. Often the URI will use some standardized identifier scheme
+ such as DOI's so that items can be identified even if they appear in
+ multiple feeds with different "links" (they might be on different
+ hosting platforms but be the same item). Also, though rare, there
+ could be multiple items with the same link but a different URI and
+ associated metadata which need to be treated as distinct entities.
+ In the RSS 1.0 case the URI must be a valid RDF URI reference.
+
+ For Atom feeds, this returns the authors as a list of SyndPerson objects,
+ for RSS feeds this method is a convenience method, it maps to the
+ Dublin Core module creator.
+
+ For Atom feeds, this sets the authors as a list of SyndPerson
+ objects, for RSS feeds this method is a convenience method, it maps
+ to the Dublin Core module creator.
+
Returns the name of the first feed author in the collection of authors.
+
+ For Atom feeds, this returns the authors as a list of SyndPerson objects,
+ for RSS feeds this method is a convenience method, it maps to the
+ Dublin Core module creator.
+
+ For Atom feeds, this sets the feed author's name, for RSS feeds
+ this method is a convenience method, it maps to the Dublin Core
+ module creator.
+
SyndFeedImpl(Class beanClass,
+ Set convenienceProperties)
+
+
+ For implementations extending SyndFeedImpl to be able to use the ObjectBean functionality
+ with extended interfaces.
+
+
+
+
+
SyndFeedImpl(WireFeed feed)
+
+
+ Creates a SyndFeedImpl and populates all its properties out of the
+ given RSS Channel or Atom Feed properties.
+
+
+
+
+
SyndFeedImpl(WireFeed feed,
+ boolean preserveWireFeed)
+
+
+ Creates a SyndFeedImpl and populates all its properties out of the
+ given RSS Channel or Atom Feed properties, while optionally preserving
+ the WireFeed for access via the orignalWireFeed() method.
Unmodifiable Set containing the convenience properties of this class.
+
+ Convenience properties are mapped to Modules, for cloning the convenience properties
+ can be ignored as the will be copied as part of the module cloning.
+
+
+
+
+
+
+
+
+
+
+
+Constructor Detail
+
+
+
+
+SyndFeedImpl
+
+protected SyndFeedImpl(Class beanClass,
+ Set convenienceProperties)
+
+
For implementations extending SyndFeedImpl to be able to use the ObjectBean functionality
+ with extended interfaces.
+
+
+
+
Parameters:
beanClass -
convenienceProperties - set containing the convenience properties of the SyndEntryImpl
+ (the are ignored during cloning, check CloneableBean for details).
+
+
+
+
+SyndFeedImpl
+
+public SyndFeedImpl()
+
+
Default constructor. All properties are set to null.
+
Creates a SyndFeedImpl and populates all its properties out of the
+ given RSS Channel or Atom Feed properties, while optionally preserving
+ the WireFeed for access via the orignalWireFeed() method.
+
Returns the WireFeed this SyndFeed was created from.
+ Will return null if the original feed is not stored or if this SyndFeed was not created from a WireFeed.
+
+ Note: The wire feed returned here will NOT contain any modifications done on this SyndFeed since it was created.
+ That is in contrast to the createWireFeed method, which will reflect the current state of the SyndFeed
+
+ How the feed URI maps to a concrete feed type (RSS or Atom) depends on
+ the concrete feed type. This is explained in detail in Rome documentation,
+ Feed and entry URI mapping.
+
+ The returned URI is a normalized URI as specified in RFC 2396bis.
+
+ Note: The URI is the unique identifier, in the RSS 2.0/atom case this is
+ the GUID, for RSS 1.0 this is the URI attribute of the item. The Link
+ is the URL that the item is accessible under, the URI is the
+ permanent identifier which the aggregator should use to reference
+ this item. Often the URI will use some standardized identifier scheme
+ such as DOI's so that items can be identified even if they appear in
+ multiple feeds with different "links" (they might be on different
+ hosting platforms but be the same item). Also, though rare, there
+ could be multiple items with the same link but a different URI and
+ associated metadata which need to be treated as distinct entities.
+ In the RSS 1.0 case the URI must be a valid RDF URI reference.
+
+ How the feed URI maps to a concrete feed type (RSS or Atom) depends on
+ the concrete feed type. This is explained in detail in Rome documentation,
+ Feed and entry URI mapping.
+
+ Note: The URI is the unique identifier, in the RSS 2.0/atom case this is
+ the GUID, for RSS 1.0 this is the URI attribute of the item. The Link
+ is the URL that the item is accessible under, the URI is the
+ permanent identifier which the aggregator should use to reference
+ this item. Often the URI will use some standardized identifier scheme
+ such as DOI's so that items can be identified even if they appear in
+ multiple feeds with different "links" (they might be on different
+ hosting platforms but be the same item). Also, though rare, there
+ could be multiple items with the same link but a different URI and
+ associated metadata which need to be treated as distinct entities.
+ In the RSS 1.0 case the URI must be a valid RDF URI reference.
+
+ Note: The URI is the unique identifier, in the RSS 2.0/atom case this is
+ the GUID, for RSS 1.0 this is the URI attribute of the item. The Link
+ is the URL that the item is accessible under, the URI is the
+ permanent identifier which the aggregator should use to reference
+ this item. Often the URI will use some standardized identifier scheme
+ such as DOI's so that items can be identified even if they appear in
+ multiple feeds with different "links" (they might be on different
+ hosting platforms but be the same item). Also, though rare, there
+ could be multiple items with the same link but a different URI and
+ associated metadata which need to be treated as distinct entities.
+ In the RSS 1.0 case the URI must be a valid RDF URI reference.
+
+ Note: The URI is the unique identifier, in the RSS 2.0/atom case this is
+ the GUID, for RSS 1.0 this is the URI attribute of the item. The Link
+ is the URL that the item is accessible under, the URI is the
+ permanent identifier which the aggregator should use to reference
+ this item. Often the URI will use some standardized identifier scheme
+ such as DOI's so that items can be identified even if they appear in
+ multiple feeds with different "links" (they might be on different
+ hosting platforms but be the same item). Also, though rare, there
+ could be multiple items with the same link but a different URI and
+ associated metadata which need to be treated as distinct entities.
+ In the RSS 1.0 case the URI must be a valid RDF URI reference.
+
Copies all the properties of the given bean into this one.
+
+ Any existing properties in this bean are lost.
+
+ This method is useful for moving from one implementation of a bean interface to another.
+ For example from the default SyndFeed bean implementation to a Hibernate ready implementation.
+
+ For Atom feeds, this returns the authors as a list of SyndPerson objects,
+ for RSS feeds this method is a convenience method, it maps to the
+ Dublin Core module creator.
+
+ For Atom feeds, this sets the authors as a list of SyndPerson
+ objects, for RSS feeds this method is a convenience method, it maps
+ to the Dublin Core module creator.
+
Copies all the properties of the given bean into this one.
+
+ Any existing properties in this bean are lost.
+
+ This method is useful for moving from one implementation of a bean interface to another.
+ For example from the default SyndFeed bean implementation to a Hibernate ready implementation.
+
SyndFeedOutput.output(SyndFeed feed,
+ File file)
+
+
+ Creates a File containing with the XML representation for the given SyndFeedImpl.
+
+
+
+ void
+
SyndFeedOutput.output(SyndFeed feed,
+ File file,
+ boolean prettyPrint)
+
+
+ Creates a File containing with the XML representation for the given SyndFeedImpl.
+
+
+
+ void
+
SyndFeedOutput.output(SyndFeed feed,
+ Writer writer)
+
+
+ Writes to an Writer the XML representation for the given SyndFeedImpl.
+
+
+
+ void
+
SyndFeedOutput.output(SyndFeed feed,
+ Writer writer,
+ boolean prettyPrint)
+
+
+ Writes to an Writer the XML representation for the given SyndFeedImpl.
+
+
+
+ org.jdom.Document
+
SyndFeedOutput.outputJDom(SyndFeed feed)
+
+
+ Creates a JDOM document for the given SyndFeedImpl.
+Adds the ability to give a direct wire feed generator reference to plugin
+ modules that need to call back to their wire feed to complete
+ generation of their particular namespace. Examples of such parsers
+ include the SSE091Generator.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Method Summary
+
+
+
+ void
+
setFeedGenerator(WireFeedGenerator feedGenerator)
+
+
+ Provides a parent wirefeed reference to this ModuleParser,
+ or "plugin-in".
+
+
+
+
+
+
Methods inherited from interface com.sun.syndication.io.ModuleGenerator
+Adds the ability to give a direct wire feed reference to plugin
+ modules that need to call back to their wire feed to complete
+ parsing of their particular namespace. Examples of such parsers
+ include the SSE091Parser.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Method Summary
+
+
+
+ void
+
setFeedParser(WireFeedParser feedParser)
+
+
+ Provides a parent wirefeed reference to this ModuleParser,
+ or "plugin-in".
+
+
+
+
+
+
Methods inherited from interface com.sun.syndication.io.ModuleParser
Returns a set with all the URIs (JDOM Namespace elements) this module generator uses.
+
+ It is used by the the feed generators to add their namespace definition in
+ the root element of the generated document (forward-missing of Java 5.0 Generics).
+
+
+
+
+
Returns:
a set with all the URIs (JDOM Namespace elements) this module generator uses.
Creates a String with the XML representation for the given SyndFeedImpl.
+
+ If the feed encoding is not NULL, it will be used in the XML prolog encoding attribute. 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.
+
+
+
+
Parameters:
feed - Abstract feed to create XML representation from. The type of the SyndFeedImpl must match
+ the type given to the FeedOuptut constructor.
+
Returns:
a String with the XML representation for the given SyndFeedImpl.
+
Throws:
+
FeedException - thrown if the XML representation for the feed could not be created.
Creates a String with the XML representation for the given SyndFeedImpl.
+
+ If the feed encoding is not NULL, it will be used in the XML prolog encoding attribute. 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.
+
+
+
+
Parameters:
feed - Abstract feed to create XML representation from. The type of the SyndFeedImpl must match
+ the type given to the FeedOuptut constructor.
prettyPrint - pretty-print XML (true) oder collapsed
+
Returns:
a String with the XML representation for the given SyndFeedImpl.
+
Throws:
+
FeedException - thrown if the XML representation for the feed could not be created.
Creates a File containing with the XML representation for the given SyndFeedImpl.
+
+ If the feed encoding is not NULL, it will be used in the XML prolog encoding attribute. The platform
+ default charset encoding is used to write the feed to the file. It is the responsibility
+ of the developer to ensure the feed encoding is set to the platform charset encoding.
+
+
+
+
Parameters:
feed - Abstract feed to create XML representation from. The type of the SyndFeedImpl must match
+ the type given to the FeedOuptut constructor.
file - the file where to write the XML representation for the given SyndFeedImpl.
+
Throws:
+
IOException - thrown if there was some problem writing to the File.
+
FeedException - thrown if the XML representation for the feed could not be created.
Creates a File containing with the XML representation for the given SyndFeedImpl.
+
+ If the feed encoding is not NULL, it will be used in the XML prolog encoding attribute. The platform
+ default charset encoding is used to write the feed to the file. It is the responsibility
+ of the developer to ensure the feed encoding is set to the platform charset encoding.
+
+
+
+
Parameters:
feed - Abstract feed to create XML representation from. The type of the SyndFeedImpl must match
+ the type given to the FeedOuptut constructor.
prettyPrint - pretty-print XML (true) oder collapsed
file - the file where to write the XML representation for the given SyndFeedImpl.
+
Throws:
+
IOException - thrown if there was some problem writing to the File.
+
FeedException - thrown if the XML representation for the feed could not be created.
Writes to an Writer the XML representation for the given SyndFeedImpl.
+
+ If the feed encoding is not NULL, it will be used in the XML prolog encoding attribute. 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.
+
+
+
+
Parameters:
feed - Abstract feed to create XML representation from. The type of the SyndFeedImpl must match
+ the type given to the FeedOuptut constructor.
writer - Writer to write the XML representation for the given SyndFeedImpl.
+
Throws:
+
IOException - thrown if there was some problem writing to the Writer.
+
FeedException - thrown if the XML representation for the feed could not be created.
Writes to an Writer the XML representation for the given SyndFeedImpl.
+
+ If the feed encoding is not NULL, it will be used in the XML prolog encoding attribute. 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.
+
+
+
+
Parameters:
feed - Abstract feed to create XML representation from. The type of the SyndFeedImpl must match
+ the type given to the FeedOuptut constructor.
prettyPrint - pretty-print XML (true) oder collapsed
writer - Writer to write the XML representation for the given SyndFeedImpl.
+
Throws:
+
IOException - thrown if there was some problem writing to the Writer.
+
FeedException - thrown if the XML representation for the feed could not be created.
+Parses an XML document (File, InputStream, Reader, W3C SAX InputSource, W3C DOM Document or JDom DOcument)
+ into an WireFeed (RSS/Atom).
+
+ It accepts all flavors of RSS (0.90, 0.91, 0.92, 0.93, 0.94, 1.0 and 2.0) and
+ Atom 0.3 feeds. Parsers are plugable (they must implement the WireFeedParser interface).
+
+ The WireFeedInput useds liberal parsers.
+
+
+
+
+
+
Author:
+
Alejandro Abdelnur
+
+
+
+
+
+
+
+
+
+
+
+Constructor Summary
+
+
+
WireFeedInput()
+
+
+ Creates a WireFeedInput instance with input validation turned off.
+
+
+
WireFeedInput(boolean validate)
+
+
+ Creates a WireFeedInput instance.
+Generates an XML document (String, File, OutputStream, Writer, W3C DOM document or JDOM document)
+ out of an WireFeed (RSS/Atom).
+
+ It generates all flavors of RSS (0.90, 0.91, 0.92, 0.93, 0.94, 1.0 and 2.0) and
+ Atom 0.3 feeds. Generators are plugable (they must implement the ModuleParser interface).
+
Creates a String with the XML representation for the given WireFeed.
+
+ If the feed encoding is not NULL, it will be used in the XML prolog encoding attribute. 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.
+
+ NOTE: This method delages to the 'Document WireFeedOutput#outputJDom(WireFeed)'.
+
+
+
+
Parameters:
feed - Abstract feed to create XML representation from. The type of the WireFeed must match
+ the type given to the FeedOuptut constructor.
+
Returns:
a String with the XML representation for the given WireFeed.
+
Throws:
+
IllegalArgumentException - thrown if the feed type of the WireFeedOutput and WireFeed don't match.
+
FeedException - thrown if the XML representation for the feed could not be created.
Creates a String with the XML representation for the given WireFeed.
+
+ If the feed encoding is not NULL, it will be used in the XML prolog encoding attribute. 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.
+
+ NOTE: This method delages to the 'Document WireFeedOutput#outputJDom(WireFeed)'.
+
+
+
+
Parameters:
feed - Abstract feed to create XML representation from. The type of the WireFeed must match
+ the type given to the FeedOuptut constructor.
prettyPrint - pretty-print XML (true) oder collapsed
+
Returns:
a String with the XML representation for the given WireFeed.
+
Throws:
+
IllegalArgumentException - thrown if the feed type of the WireFeedOutput and WireFeed don't match.
+
FeedException - thrown if the XML representation for the feed could not be created.
Creates a File containing with the XML representation for the given WireFeed.
+
+ If the feed encoding is not NULL, it will be used in the XML prolog encoding attribute. The platform
+ default charset encoding is used to write the feed to the file. It is the responsibility
+ of the developer to ensure the feed encoding is set to the platform charset encoding.
+
+ NOTE: This method delages to the 'Document WireFeedOutput#outputJDom(WireFeed)'.
+
+
+
+
Parameters:
feed - Abstract feed to create XML representation from. The type of the WireFeed must match
+ the type given to the FeedOuptut constructor.
file - the file where to write the XML representation for the given WireFeed.
+
Throws:
+
IllegalArgumentException - thrown if the feed type of the WireFeedOutput and WireFeed don't match.
+
IOException - thrown if there was some problem writing to the File.
+
FeedException - thrown if the XML representation for the feed could not be created.
Creates a File containing with the XML representation for the given WireFeed.
+
+ If the feed encoding is not NULL, it will be used in the XML prolog encoding attribute. The platform
+ default charset encoding is used to write the feed to the file. It is the responsibility
+ of the developer to ensure the feed encoding is set to the platform charset encoding.
+
+ NOTE: This method delages to the 'Document WireFeedOutput#outputJDom(WireFeed)'.
+
+
+
+
Parameters:
feed - Abstract feed to create XML representation from. The type of the WireFeed must match
+ the type given to the FeedOuptut constructor.
file - the file where to write the XML representation for the given WireFeed.
prettyPrint - pretty-print XML (true) oder collapsed
+
Throws:
+
IllegalArgumentException - thrown if the feed type of the WireFeedOutput and WireFeed don't match.
+
IOException - thrown if there was some problem writing to the File.
+
FeedException - thrown if the XML representation for the feed could not be created.
Writes to an Writer the XML representation for the given WireFeed.
+
+ If the feed encoding is not NULL, it will be used in the XML prolog encoding attribute. It is the responsibility
+ of the developer to ensure the Writer instance is using the same charset encoding.
+
+ NOTE: This method delages to the 'Document WireFeedOutput#outputJDom(WireFeed)'.
+
+
+
+
Parameters:
feed - Abstract feed to create XML representation from. The type of the WireFeed must match
+ the type given to the FeedOuptut constructor.
writer - Writer to write the XML representation for the given WireFeed.
+
Throws:
+
IllegalArgumentException - thrown if the feed type of the WireFeedOutput and WireFeed don't match.
+
IOException - thrown if there was some problem writing to the Writer.
+
FeedException - thrown if the XML representation for the feed could not be created.
Writes to an Writer the XML representation for the given WireFeed.
+
+ If the feed encoding is not NULL, it will be used in the XML prolog encoding attribute. It is the responsibility
+ of the developer to ensure the Writer instance is using the same charset encoding.
+
+ NOTE: This method delages to the 'Document WireFeedOutput#outputJDom(WireFeed)'.
+
+
+
+
Parameters:
feed - Abstract feed to create XML representation from. The type of the WireFeed must match
+ the type given to the FeedOuptut constructor.
writer - Writer to write the XML representation for the given WireFeed.
prettyPrint - pretty-print XML (true) oder collapsed
+
Throws:
+
IllegalArgumentException - thrown if the feed type of the WireFeedOutput and WireFeed don't match.
+
IOException - thrown if there was some problem writing to the Writer.
+
FeedException - thrown if the XML representation for the feed could not be created.
+Character stream that handles (or at least attemtps to) all the necessary Voodo to figure out
+ the charset encoding of the XML document within the stream.
+
+ IMPORTANT: This class is not related in any way to the org.xml.sax.XMLReader. This one IS a
+ character stream.
+
+ All this has to be done without consuming characters from the stream, if not the XML parser
+ will not recognized the document as a valid XML. This is not 100% true, but it's close enough
+ (UTF-8 BOM is not handled by all parsers right now, XmlReader handles it and things work in all
+ parsers).
+
+ The XmlReader class handles the charset encoding of XML documents in Files, raw streams and
+ HTTP streams by offering a wide set of constructors.
+
+ By default the charset encoding detection is lenient, the constructor with the lenient flag
+ can be used for an script (following HTTP MIME and XML specifications).
+ All this is nicely explained by Mark Pilgrim in his blog,
+
+ Determining the character encoding of a feed.
+
XmlReader(InputStream is,
+ boolean lenient)
+
+
+ Creates a Reader for a raw InputStream.
+
+
+
XmlReader(InputStream is,
+ boolean lenient,
+ String defaultEncoding)
+
+
+ Creates a Reader for a raw InputStream and uses the provided default encoding if none is determined.
+
+
+
XmlReader(InputStream is,
+ String httpContentType)
+
+
+ Creates a Reader using an InputStream and the associated content-type header.
+
+
+
XmlReader(InputStream is,
+ String httpContentType,
+ boolean lenient)
+
+
+ Creates a Reader using an InputStream and the associated content-type header.
+
+
+
XmlReader(InputStream is,
+ String httpContentType,
+ boolean lenient,
+ String defaultEncoding)
+
+
+ Creates a Reader using an InputStream and the associated content-type header.
+
+
+
XmlReader(URL url)
+
+
+ Creates a Reader using the InputStream of a URL.
+
+
+
XmlReader(URLConnection conn)
+
+
+ Creates a Reader using the InputStream of a URLConnection.
getDefaultEncoding()
+
+
+ Returns the default encoding to use if none is set in HTTP content-type,
+ XML prolog and the rules based on content-type are not adequate.
setDefaultEncoding(String encoding)
+
+
+ Sets the default encoding to use if none is set in HTTP content-type,
+ XML prolog and the rules based on content-type are not adequate.
Creates a Reader using the InputStream of a URL.
+
+ If the URL is not of type HTTP and there is not 'content-type' header in the fetched
+ data it uses the same logic used for Files.
+
+ If the URL is a HTTP Url or there is a 'content-type' header in the fetched
+ data it uses the same logic used for an InputStream with content-type.
+
+ It does a lenient charset encoding detection, check the constructor with the lenient parameter
+ for details.
+
+
+
+
Parameters:
url - URL to create a Reader from.
+
Throws:
+
IOException - thrown if there is a problem reading the stream of the URL.
Creates a Reader using the InputStream of a URLConnection.
+
+ If the URLConnection is not of type HttpURLConnection and there is not
+ 'content-type' header in the fetched data it uses the same logic used for files.
+
+ If the URLConnection is a HTTP Url or there is a 'content-type' header in the fetched
+ data it uses the same logic used for an InputStream with content-type.
+
+ It does a lenient charset encoding detection, check the constructor with the lenient parameter
+ for details.
+
+
+
+
Parameters:
conn - URLConnection to create a Reader from.
+
Throws:
+
IOException - thrown if there is a problem reading the stream of the URLConnection.
Creates a Reader using an InputStream and the associated content-type header.
+
+ First it checks if the stream has BOM. If there is not BOM checks the content-type encoding.
+ If there is not content-type encoding checks the XML prolog encoding. If there is not XML
+ prolog encoding uses the default encoding mandated by the content-type MIME type.
+
+ It does a lenient charset encoding detection, check the constructor with the lenient parameter
+ for details.
+
+
+
+
Parameters:
is - InputStream to create the reader from.
httpContentType - content-type header to use for the resolution of the charset encoding.
+
Throws:
+
IOException - thrown if there is a problem reading the file.
Creates a Reader using an InputStream and the associated content-type header.
+
+ First it checks if the stream has BOM. If there is not BOM checks the content-type encoding.
+ If there is not content-type encoding checks the XML prolog encoding. If there is not XML
+ prolog encoding uses the default encoding mandated by the content-type MIME type.
+
+ If lenient detection is indicated and the detection above fails as per specifications it then attempts
+ the following:
+
+ If the content type was 'text/html' it replaces it with 'text/xml' and tries the 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.
+
+ If lenient detection is indicated and XmlReaderException is never thrown.
+
+
+
+
Parameters:
is - InputStream to create the reader from.
httpContentType - content-type header to use for the resolution of the charset encoding.
lenient - indicates if the charset encoding detection should be relaxed.
defaultEncoding - default encoding to use if one cannot be detected.
+
Throws:
+
IOException - thrown if there is a problem reading the file.
+
XmlReaderException - thrown if the charset encoding could not be determined according to the specs.
Creates a Reader using an InputStream and the associated content-type header.
+
+ First it checks if the stream has BOM. If there is not BOM checks the content-type encoding.
+ If there is not content-type encoding checks the XML prolog encoding. If there is not XML
+ prolog encoding uses the default encoding mandated by the content-type MIME type.
+
+ If lenient detection is indicated and the detection above fails as per specifications it then attempts
+ the following:
+
+ If the content type was 'text/html' it replaces it with 'text/xml' and tries the 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.
+
+ If lenient detection is indicated and XmlReaderException is never thrown.
+
+
+
+
Parameters:
is - InputStream to create the reader from.
httpContentType - content-type header to use for the resolution of the charset encoding.
lenient - indicates if the charset encoding detection should be relaxed.
+
Throws:
+
IOException - thrown if there is a problem reading the file.
+
XmlReaderException - thrown if the charset encoding could not be determined according to the specs.
Sets the default encoding to use if none is set in HTTP content-type,
+ XML prolog and the rules based on content-type are not adequate.
+
+ If it is set to NULL the content-type based rules are used.
+
+ By default it is NULL.
+
+
Returns the default encoding to use if none is set in HTTP content-type,
+ XML prolog and the rules based on content-type are not adequate.
+
+ If it is NULL the content-type based rules are used.
+
+
+The XmlReaderException is thrown by the XmlReader constructors if the charset encoding
+ can not be determined according to the XML 1.0 specification and RFC 3023.
+
+ The exception returns the unconsumed InputStream to allow the application to do an
+ alternate processing with the stream. Note that the original InputStream given to the
+ XmlReader cannot be used as that one has been already read.
+
WireFeedInput.build(Reader reader)
+
+
+ Builds an WireFeed (RSS or Atom) from an Reader.
+
+
+
+ org.jdom.Document
+
WireFeedGenerator.generate(WireFeed feed)
+
+
+ Creates an XML document (JDOM) for the given feed bean.
+
+
+
+ void
+
SyndFeedOutput.output(SyndFeed feed,
+ File file)
+
+
+ Creates a File containing with the XML representation for the given SyndFeedImpl.
+
+
+
+ void
+
SyndFeedOutput.output(SyndFeed feed,
+ File file,
+ boolean prettyPrint)
+
+
+ Creates a File containing with the XML representation for the given SyndFeedImpl.
+
+
+
+ void
+
SyndFeedOutput.output(SyndFeed feed,
+ Writer writer)
+
+
+ Writes to an Writer the XML representation for the given SyndFeedImpl.
+
+
+
+ void
+
SyndFeedOutput.output(SyndFeed feed,
+ Writer writer,
+ boolean prettyPrint)
+
+
+ Writes to an Writer the XML representation for the given SyndFeedImpl.
+
+
+
+ void
+
WireFeedOutput.output(WireFeed feed,
+ File file)
+
+
+ Creates a File containing with the XML representation for the given WireFeed.
+
+
+
+ void
+
WireFeedOutput.output(WireFeed feed,
+ File file,
+ boolean prettyPrint)
+
+
+ Creates a File containing with the XML representation for the given WireFeed.
+
+
+
+ void
+
WireFeedOutput.output(WireFeed feed,
+ Writer writer)
+
+
+ Writes to an Writer the XML representation for the given WireFeed.
+
+
+
+ void
+
WireFeedOutput.output(WireFeed feed,
+ Writer writer,
+ boolean prettyPrint)
+
+
+ Writes to an Writer the XML representation for the given WireFeed.
+
+
+
+ org.jdom.Document
+
SyndFeedOutput.outputJDom(SyndFeed feed)
+
+
+ Creates a JDOM document for the given SyndFeedImpl.
+
+
+
+ org.jdom.Document
+
WireFeedOutput.outputJDom(WireFeed feed)
+
+
+ Creates a JDOM document for the given WireFeed.
DelegatingModuleGenerator
+
+
+ Adds the ability to give a direct wire feed generator reference to plugin
+ modules that need to call back to their wire feed to complete
+ generation of their particular namespace.
DelegatingModuleParser
+
+
+ Adds the ability to give a direct wire feed reference to plugin
+ modules that need to call back to their wire feed to complete
+ parsing of their particular namespace.
DelegatingModuleGenerator.setFeedGenerator(WireFeedGenerator feedGenerator)
+
+
+ Provides a parent wirefeed reference to this ModuleParser,
+ or "plugin-in".
RSS20wNSParser
+
+
+ To address issue with certain feeds (brought up by Charles Miller):
+
+ "During the debacle that was the rollout of RSS2.0, this namespace was tried,
+ and even appeared in Dave Winer's Scripting News feed for a while.
XmlReader(InputStream is,
+ boolean lenient)
+
+
+ Creates a Reader for a raw InputStream.
+
+
+
XmlReader(InputStream is,
+ boolean lenient,
+ String defaultEncoding)
+
+
+ Creates a Reader for a raw InputStream and uses the provided default encoding if none is determined.
+
+
+
XmlReader(InputStream is,
+ String httpContentType,
+ boolean lenient)
+
+
+ Creates a Reader using an InputStream and the associated content-type header.
+
+
+
XmlReader(InputStream is,
+ String httpContentType,
+ boolean lenient,
+ String defaultEncoding)
+
+
+ Creates a Reader using an InputStream and the associated content-type header.
getType()
+
+
+ Returns the type of feed the generator creates.
+
+
+
+protected static void
+
purgeUnusedNamespaceDeclarations(org.jdom.Element root)
+
+
+ Purging unused declarations is less optimal, performance-wise, than never adding them in the first place.
Purging unused declarations is less optimal, performance-wise, than never adding them in the first place. So, we
+ should still ask the ROME guys to fix their code (not adding dozens of unnecessary module declarations). Having
+ said that: purging them here, before XML generation, is more efficient than parsing and re-molding the XML after
+ ROME generates it.
+
+ Note that the calling app could still add declarations/modules to the Feed tree after this. Which is fine. But
+ those modules are then responsible for crawling to the root of the tree, at generate() time, to make sure their
+ namespace declarations are present.
+
Returns a set with all the URIs (JDOM Namespace elements) this module
+ generator uses.
+
+ It is used by the the feed generators to add their namespace definition
+ in the root element of the generated document (forward-missing of
+ Java 5.0 Generics).
+
+
+A helper class that parses Dates out of Strings with date time in RFC822 and W3CDateTime
+ formats plus the variants Atom (0.3) and RSS (0.9, 0.91, 0.92, 0.93, 0.94, 1.0 and 2.0)
+ specificators added to those formats.
+
+ It uses the JDK java.text.SimpleDateFormat class attemtping the parse using a mask for
+ each one of the possible formats.
+
+
+Generates an XML document (JDOM Document) out of a Feed.
+
+ It can generate all flavors of RSS (0.90, 0.91, 0.92, 0.93, 0.94, 1.0 and 2.0) and
+ Atom 0.3 feed.
+
+ WireFeedGenerator instances are thread safe.
+
+ Generators for a specific type must extend this class and register in the generator list.
+ (Right now registration is hardcoded in the WireFeedGenerator constructor).
+
+Parses an XML document (JDOM Document) into a Feed.
+
+ It accepts all flavors of RSS (0.90, 0.91, 0.92, 0.93, 0.94, 1.0 and 2.0) and
+ Atom 0.3 feeds.
+
+ The WireFeedParser is a liberal parser.
+
+ WireFeedParser instances are thread safe.
+
+ Parsers for a specific type must extend this class and register in the parser list.
+ (Right now registration is hardcoded in the WireFeedParser constructor).
+
+A helper class that parses Numbers out of Strings in a lenient manner.
+
+
+ No method will throw any sort of Exception when parsing a string.
+ All methods accept any Java String or null as legal input, if the
+ input is non null, whitespace will be trimmed first, and then parsing
+ will be attempted.
+
+
+ :TODO: Add Integer, Float, and Double methods as needed.
+
+Properties loader that aggregates a master properties file and several extra properties files,
+ all from the current classpath.
+
+ The master properties file has to be in a distinct location than the extra properties files.
+ First the master properties file is loaded, then all the extra properties files in their order
+ of appearance in the classpath.
+
+ Current use cases (plugin manager for parsers/converters/generators for feeds and modules
+ and date formats) assume properties are list of tokens, that why the only method to get
+ property values is the getTokenizedProperty().
+
Returns an array of tokenized values stored under a property key in all properties files.
+ If the master file has this property its tokens will be the first ones in the array.
+
+
+
+
Parameters:
key - property key to retrieve values
separator - String with all separator characters to tokenize from the values in all
+ properties files.
+
Returns:
all the tokens for the given property key from all the properties files.
Returns an array of values stored under a property key in all properties files.
+ If the master file has this property it will be the first ones in the array.
+
+
+
+
Parameters:
key - property key to retrieve values
+
Returns:
all the values for the given property key from all the properties files.
populateChannel(Channel channel,
+ org.jdom.Element eChannel)
+
+
+ Populates the given channel with parsed data from the ROME element that holds the
+ channel data.
Parses the root element of an RSS document into a Channel bean.
+
+ It reads title, link and description and delegates to parseImage, parseItems
+ and parseTextInput. This delegation always passes the root element of the RSS
+ document as different RSS version may have this information in different parts
+ of the XML tree (no assumptions made thanks to the specs variaty)
+
+
+
+
Parameters:
rssRoot - the root element of the RSS document to parse.
+
This method exists because RSS0.90 and RSS1.0 have the 'item' elements under the root elemment.
+ And RSS0.91, RSS0.02, RSS0.93, RSS0.94 and RSS2.0 have the item elements under the 'channel' element.
+
+
This method exists because RSS0.90 and RSS1.0 have the 'image' element under the root elemment.
+ And RSS0.91, RSS0.02, RSS0.93, RSS0.94 and RSS2.0 have it under the 'channel' element.
+
+
This method exists because RSS0.90 and RSS1.0 have the 'textinput' element under the root elemment.
+ And RSS0.91, RSS0.02, RSS0.93, RSS0.94 and RSS2.0 have it under the 'channel' element.
+
+
Parses the root element of an RSS document looking for all items information.
+
+ It iterates through the item elements list, obtained from the getItems() method, and invoke parseItem()
+ for each item element. The resulting RSSItem of each item element is stored in a list.
+
+
+
+
Parameters:
rssRoot - the root element of the RSS document to parse for all items information.
+
Parses the root element of an RSS document looking for text-input information.
+
+ It reads title, description, name and link out of the 'textinput' or 'textInput' element.
+
+
+
+
Parameters:
rssRoot - the root element of the RSS document to parse for text-input information.
+
isHourFormat24()
+
+
+ To be overriden by RSS 0.91 Netscape and RSS 0.94
+
+
+
+protected void
+
populateChannel(Channel channel,
+ org.jdom.Element eChannel)
+
+
+ Populates the given channel with parsed data from the ROME element that holds the
+ channel data.
Parses the root element of an RSS document into a Channel bean.
+
+ It first invokes super.parseChannel and then parses and injects the following
+ properties if present: language, pubDate, rating and copyright.
+
+
Parses the root element of an RSS document looking for image information.
+
+ It first invokes super.parseImage and then parses and injects the following
+ properties if present: url, link, width, height and description.
+
+
Parses an item element of an RSS document looking for item information.
+
+ It first invokes super.parseItem and then parses and injects the description property if present.
+
+
populateChannel(Channel channel,
+ org.jdom.Element eChannel)
+
+
+ Populates the given channel with parsed data from the ROME element that holds the
+ channel data.
Parses the root element of an RSS document into a Channel bean.
+
+ It first invokes super.parseChannel and then parses and injects the following
+ properties if present: language, pubDate, rating and copyright.
+
+
Parses an item element of an RSS document looking for item information.
+
+ It first invokes super.parseItem and then parses and injects the description property if present.
+
+
Parses an item element of an RSS document looking for item information.
+
+ It first invokes super.parseItem and then parses and injects the description property if present.
+
+
Parses the root element of an RSS document into a Channel bean.
+
+ It first invokes super.parseChannel and then parses and injects the following
+ properties if present: language, pubDate, rating and copyright.
+
+
Parses an item element of an RSS document looking for item information.
+
+ It first invokes super.parseItem and then parses and injects the description property if present.
+
+
populateChannel(Channel channel,
+ org.jdom.Element eChannel)
+
+
+ Populates the given channel with parsed data from the ROME element that holds the
+ channel data.
Indicates if a JDom document is an RSS instance that can be parsed with the parser.
+
+ It checks for RDF ("http://www.w3.org/1999/02/22-rdf-syntax-ns#") and
+ RSS ("http://purl.org/rss/1.0/") namespaces being defined in the root element.
+
Parses an item element of an RSS document looking for item information.
+
+ It first invokes super.parseItem and then parses and injects the description property if present.
+
+
Parses the root element of an RSS document into a Channel bean.
+
+ It reads title, link and description and delegates to parseImage, parseItems
+ and parseTextInput. This delegation always passes the root element of the RSS
+ document as different RSS version may have this information in different parts
+ of the XML tree (no assumptions made thanks to the specs variaty)
+
+
populateChannel(Channel channel,
+ org.jdom.Element eChannel)
+
+
+ Populates the given channel with parsed data from the ROME element that holds the
+ channel data.
+To address issue with certain feeds (brought up by Charles Miller):
+
+ "During the debacle that was the rollout of RSS2.0, this namespace was tried,
+ and even appeared in Dave Winer's Scripting News feed for a while. It was
+ then withdrawn, but the wonderful thing about standards is the moment you
+ roll one out, even if it's marked as unfinished and subject to change,
+ someone will end up stuck with it forever."
+
+ Note that there is not counter part on the generator, we only generate the final RSS2
+
parseChannel(org.jdom.Element rssRoot)
+
+
+ After we parse the feed we put "rss_2.0" in it (so converters and generators work)
+ this parser is a phantom.
+
+
+
+
+
+
Methods inherited from class com.sun.syndication.io.impl.RSS20Parser
Returns a set with all the URIs (JDOM Namespace elements) this module generator uses.
+
+ It is used by the the feed generators to add their namespace definition in
+ the root element of the generated document (forward-missing of Java 5.0 Generics).
+
+
RSS20wNSParser
+
+
+ To address issue with certain feeds (brought up by Charles Miller):
+
+ "During the debacle that was the rollout of RSS2.0, this namespace was tried,
+ and even appeared in Dave Winer's Scripting News feed for a while.
RSS20wNSParser
+
+
+ To address issue with certain feeds (brought up by Charles Miller):
+
+ "During the debacle that was the rollout of RSS2.0, this namespace was tried,
+ and even appeared in Dave Winer's Scripting News feed for a while.
RSS20wNSParser
+
+
+ To address issue with certain feeds (brought up by Charles Miller):
+
+ "During the debacle that was the rollout of RSS2.0, this namespace was tried,
+ and even appeared in Dave Winer's Scripting News feed for a while.
RSS20wNSParser
+
+
+ To address issue with certain feeds (brought up by Charles Miller):
+
+ "During the debacle that was the rollout of RSS2.0, this namespace was tried,
+ and even appeared in Dave Winer's Scripting News feed for a while.
RSS20wNSParser
+
+
+ To address issue with certain feeds (brought up by Charles Miller):
+
+ "During the debacle that was the rollout of RSS2.0, this namespace was tried,
+ and even appeared in Dave Winer's Scripting News feed for a while.
RSS20wNSParser
+
+
+ To address issue with certain feeds (brought up by Charles Miller):
+
+ "During the debacle that was the rollout of RSS2.0, this namespace was tried,
+ and even appeared in Dave Winer's Scripting News feed for a while.
RSS20wNSParser
+
+
+ To address issue with certain feeds (brought up by Charles Miller):
+
+ "During the debacle that was the rollout of RSS2.0, this namespace was tried,
+ and even appeared in Dave Winer's Scripting News feed for a while.
A helper class that parses Dates out of Strings with date time in RFC822 and W3CDateTime
+ formats plus the variants Atom (0.3) and RSS (0.9, 0.91, 0.92, 0.93, 0.94, 1.0 and 2.0)
+ specificators added to those formats.
To address issue with certain feeds (brought up by Charles Miller):
+
+ "During the debacle that was the rollout of RSS2.0, this namespace was tried,
+ and even appeared in Dave Winer's Scripting News feed for a while.
PropertiesLoader
+
+
+ Properties loader that aggregates a master properties file and several extra properties files,
+ all from the current classpath.
Adds the ability to give a direct wire feed generator reference to plugin
+ modules that need to call back to their wire feed to complete
+ generation of their particular namespace.
Adds the ability to give a direct wire feed reference to plugin
+ modules that need to call back to their wire feed to complete
+ parsing of their particular namespace.
Character stream that handles (or at least attemtps to) all the necessary Voodo to figure out
+ the charset encoding of the XML document within the stream.
The XmlReaderException is thrown by the XmlReader constructors if the charset encoding
+ can not be determined according to the XML 1.0 specification and RFC 3023.
FeedException
+
+
+ Exception thrown by WireFeedInput, WireFeedOutput, WireFeedParser and WireFeedGenerator instances if they
+ can not parse or generate a feed.
+
+
+
ModuleGenerator
+
+
+ Injects module metadata into a XML node (JDOM element).
+
+
+
ModuleParser
+
+
+ Parses module metadata from a XML node (JDOM element).
WireFeedGenerator
+
+
+ Generates an XML document (JDOM) out of a feed for a specific real feed type.
+
+
+
WireFeedParser
+
+
+ Parses an XML document (JDOM) into a feed bean.
+
+
+
XmlReaderException
+
+
+ The XmlReaderException is thrown by the XmlReader constructors if the charset encoding
+ can not be determined according to the XML 1.0 specification and RFC 3023.
FeedException
+
+
+ Exception thrown by WireFeedInput, WireFeedOutput, WireFeedParser and WireFeedGenerator instances if they
+ can not parse or generate a feed.
+
+
+
ModuleGenerator
+
+
+ Injects module metadata into a XML node (JDOM element).
+
+
+
ModuleParser
+
+
+ Parses module metadata from a XML node (JDOM element).
+
+
+
WireFeedGenerator
+
+
+ Generates an XML document (JDOM) out of a feed for a specific real feed type.
+
+
+
WireFeedParser
+
+
+ Parses an XML document (JDOM) into a feed bean.
+This API (Application Programming Interface) document has pages corresponding to the items in the navigation bar, described as follows.
+Overview
+
+
+
+The Overview page is the front page of this API document and provides a list of all packages with a summary for each. This page can also contain an overall description of the set of packages.
+
+Package
+
+
+
+Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain four categories:
+
Interfaces (italic)
Classes
Enums
Exceptions
Errors
Annotation Types
+
+
+Class/Interface
+
+
+
+Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:
+
Class inheritance diagram
Direct Subclasses
All Known Subinterfaces
All Known Implementing Classes
Class/interface declaration
Class/interface description
+
+
Nested Class Summary
Field Summary
Constructor Summary
Method Summary
+
+
Field Detail
Constructor Detail
Method Detail
+Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.
+
+
+Annotation Type
+
+
+
+Each annotation type has its own separate page with the following sections:
+
Annotation Type declaration
Annotation Type description
Required Element Summary
Optional Element Summary
Element Detail
+
+
+
+Enum
+
+
+
+Each enum has its own separate page with the following sections:
+
Enum declaration
Enum description
Enum Constant Summary
Enum Constant Detail
+
+
+Use
+
+Each documented package, class and interface has its own Use page. This page describes what packages, classes, methods, constructors and fields use any part of the given class or package. Given a class or interface A, its Use page includes subclasses of A, fields declared as A, methods that return A, and methods and constructors with parameters of type A. You can access this page by first going to the package, class or interface, then clicking on the "Use" link in the navigation bar.
+
+Tree (Class Hierarchy)
+
+There is a Class Hierarchy page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces. The classes are organized by inheritance structure starting with java.lang.Object. The interfaces do not inherit from java.lang.Object.
+
When viewing the Overview page, clicking on "Tree" displays the hierarchy for all packages.
When viewing a particular package, class or interface page, clicking "Tree" displays the hierarchy for only that package.
+
+
+Deprecated API
+
+The Deprecated API page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.
+
+Index
+
+The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.
+
+Prev/Next
+These links take you to the next or previous class, interface, package, or related page.
+Frames/No Frames
+These links show and hide the HTML frames. All pages are available with or without frames.
+
+
+Serialized Form
+Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.
+
A helper class that parses Dates out of Strings with date time in RFC822 and W3CDateTime
+ formats plus the variants Atom (0.3) and RSS (0.9, 0.91, 0.92, 0.93, 0.94, 1.0 and 2.0)
+ specificators added to those formats.
Adds the ability to give a direct wire feed generator reference to plugin
+ modules that need to call back to their wire feed to complete
+ generation of their particular namespace.
Adds the ability to give a direct wire feed reference to plugin
+ modules that need to call back to their wire feed to complete
+ parsing of their particular namespace.
To address issue with certain feeds (brought up by Charles Miller):
+
+ "During the debacle that was the rollout of RSS2.0, this namespace was tried,
+ and even appeared in Dave Winer's Scripting News feed for a while.
Creates a SyndFeedImpl and populates all its properties out of the
+ given RSS Channel or Atom Feed properties, while optionally preserving
+ the WireFeed for access via the orignalWireFeed() method.
+
Character stream that handles (or at least attemtps to) all the necessary Voodo to figure out
+ the charset encoding of the XML document within the stream.
The XmlReaderException is thrown by the XmlReader constructors if the charset encoding
+ can not be determined according to the XML 1.0 specification and RFC 3023.
No transitive dependencies are required for this project.
+
+
Project Dependency Graph
+
+
+
Dependency Tree
+
+
org.rometools:rome:jar:1.1-SNAPSHOT
+
+
+
ROME, RSS and atOM utilitiEs for Java
+
+
+
Description: All Roads Lead to ROME. ROME is a set of Atom/RSS Java utilities that make it
+ easy to work in Java with most syndication formats. Today it accepts all flavors of RSS
+ (0.90, 0.91, 0.92, 0.93, 0.94, 1.0 and 2.0), Atom 0.3 and Atom 1.0 feeds. Rome includes
+ a set of parsers and generators for the various flavors of feeds, as well as converters
+ to convert from one format to another. The parsers can give you back Java objects that
+ are either specific for the format you want to work with, or a generic normalized
+ SyndFeed object that lets you work on with the data without bothering about the
+ underlying format.
Description: There is currently no description associated with this project.
+
Project License: No license is defined for this project.
+
junit:junit:jar:3.8.1 (test)
+
+
+
JUnit
+
+
+
Description: JUnit is a regression testing framework written by Erich Gamma and Kent Beck. It is used by the developer who implements unit tests in Java.
This automatic page generator is the easiest way to create beautiful pages for all of your projects. Author your page content here using GitHub Flavored Markdown, select a template crafted by a designer, and publish. After your page is generated, you can check out the new branch:
If you're using the GitHub for Mac, simply sync your repository and you'll see the new branch.
-
-
-Designer Templates
-
-
We've crafted some handsome templates for you to use. Go ahead and continue to layouts to browse through them. You can easily go back to edit your page before publishing. After publishing your page, you can revisit the page generator and switch to another theme. Your Page content will be preserved if it remained markdown format.
-
-
-Rather Drive Stick?
-
-
If you prefer to not use the automatic generator, push a branch named gh-pages to your repository to create a page manually. In addition to supporting regular HTML content, GitHub Pages support Jekyll, a simple, blog aware static site generator written by our own Tom Preston-Werner. Jekyll makes it easy to create site-wide headers and footers without having to copy them across every page. It also offers intelligent blog support and other advanced templating features.
-
-
-Authors and Contributors
-
-
You can @mention a GitHub username to generate a link to their profile. The resulting <a> element will link to the contributor's GitHub Profile. For example: In 2007, Chris Wanstrath (@defunkt), PJ Hyett (@pjhyett), and Tom Preston-Werner (@mojombo) founded GitHub.
+ 
+ 
+
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+
com.sun.syndication.feed.module.impl.ModuleUtils
+
+
+
+
+ 
+
+ 
junit.framework.Assert +
junit.framework.Assert +