153 lines
No EOL
13 KiB
HTML
153 lines
No EOL
13 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<!-- Generated by Apache Maven Doxia Site Renderer 1.4 at 2013-09-27 -->
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
|
<title>ROME - Rome API FAQ</title>
|
|
<style type="text/css" media="all">
|
|
@import url("./css/maven-base.css");
|
|
@import url("./css/maven-theme.css");
|
|
@import url("./css/site.css");
|
|
</style>
|
|
<link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
|
|
<meta name="author" content="mkurz" />
|
|
<meta name="Date-Creation-yyyymmdd" content="20110814" />
|
|
<meta name="Date-Revision-yyyymmdd" content="20130927" />
|
|
<meta http-equiv="Content-Language" content="en" />
|
|
|
|
</head>
|
|
<body class="composite">
|
|
<div id="banner">
|
|
<a href="http://github.com/rometools/" id="bannerLeft">
|
|
<img src="images/romelogo.png" alt="ROME" />
|
|
</a>
|
|
<div class="clear">
|
|
<hr/>
|
|
</div>
|
|
</div>
|
|
<div id="breadcrumbs">
|
|
|
|
|
|
<div class="xright">
|
|
|
|
<span id="publishDate">Last Published: 2013-09-27</span>
|
|
| <span id="projectVersion">Version: 1.1-SNAPSHOT</span>
|
|
</div>
|
|
<div class="clear">
|
|
<hr/>
|
|
</div>
|
|
</div>
|
|
<div id="leftColumn">
|
|
<div id="navcolumn">
|
|
|
|
|
|
<h5>Rome</h5>
|
|
<ul>
|
|
<li class="none">
|
|
<a href="index.html" title="Overview">Overview</a>
|
|
</li>
|
|
<li class="collapsed">
|
|
<a href="HowRomeWorks/index.html" title="How Rome Works">How Rome Works</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="RssAndAtOMUtilitiEsROMEV0.5AndAboveTutorialsAndArticles/index.html" title="Tutorials And Articles">Tutorials And Articles</a>
|
|
</li>
|
|
<li class="collapsed">
|
|
<a href="ROMEReleases/index.html" title="Releases">Releases</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="ROMEDevelopmentProposals/index.html" title="ROME Development Proposals">ROME Development Proposals</a>
|
|
</li>
|
|
</ul>
|
|
<h5>Project Documentation</h5>
|
|
<ul>
|
|
<li class="collapsed">
|
|
<a href="project-info.html" title="Project Information">Project Information</a>
|
|
</li>
|
|
<li class="collapsed">
|
|
<a href="project-reports.html" title="Project Reports">Project Reports</a>
|
|
</li>
|
|
</ul>
|
|
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
|
|
<img class="poweredBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />
|
|
</a>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
<div id="bodyColumn">
|
|
<div id="contentBox">
|
|
<div class="section">
|
|
<h2>Rome API FAQ<a name="Rome_API_FAQ"></a></h2>
|
|
<p>As we were designing and implementing Rome we had discusssions, brainstorming and code reviews on the API. We've captured them in this document.</p>
|
|
<div class="section">
|
|
<h3>Do SyndFeed support arbitrary Metadata?<a name="Do_SyndFeed_support_arbitrary_Metadata"></a></h3>
|
|
<p>Yes, using what we call Modules. Currently we support the 2 modules defined in RSS 1.0, <a class="externalLink" href="http://purl.org/rss/1.0/modules/dc/">Dublin Core</a> and <a class="externalLink" href="http://purl.org/rss/1.0/modules/syndication/">Syndication</a>. 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.</p>
|
|
<p>However we will develop, and encourage developers to develop Rome specific Modules to handle future RSS 2.0 and Atom extensions.</p>
|
|
<p>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.</p></div>
|
|
<div class="section">
|
|
<h3>Why those package, interfaces, classes and method names?<a name="Why_those_package_interfaces_classes_and_method_names"></a></h3>
|
|
<p>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.</p></div>
|
|
<div class="section">
|
|
<h3>Where are the parser, generator and converter implementations?<a name="Where_are_the_parser_generator_and_converter_implementations"></a></h3>
|
|
<p>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.</p></div>
|
|
<div class="section">
|
|
<h3>What are the interfaces and classes in the syndication.common package for? And why most bean (or interface) extend/implement them?<a name="What_are_the_interfaces_and_classes_in_the_syndication.common_package_for_And_why_most_bean_or_interface_extendimplement_them"></a></h3>
|
|
<p>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.</p>
|
|
<p>Later we did the same to handle equals/hashcode, which is very useful when using Maps.</p>
|
|
<p>To complete the task we did the same for cloning, providing deep cloning support.</p>
|
|
<p>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.</p></div>
|
|
<div class="section">
|
|
<h3>What are the property values when not set?<a name="What_are_the_property_values_when_not_set"></a></h3>
|
|
<p>For Boolean is <b>false</b>. 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.</p></div>
|
|
<div class="section">
|
|
<h3>Are properties copied by value or by reference when set or gotten?<a name="Are_properties_copied_by_value_or_by_reference_when_set_or_gotten"></a></h3>
|
|
<p>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.</p></div>
|
|
<div class="section">
|
|
<h3>What is with the interface and implementation names in the synd and module packages?<a name="What_is_with_the_interface_and_implementation_names_in_the_synd_and_module_packages"></a></h3>
|
|
<p>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.</p>
|
|
<p>We decided to use <NAME> for the default implementation classes as we think they'll be the implementation of choice most of the time.</p></div>
|
|
<div class="section">
|
|
<h3>Why the beans in the synd and module packages have interface and implementation versions of them?<a name="Why_the_beans_in_the_synd_and_module_packages_have_interface_and_implementation_versions_of_them"></a></h3>
|
|
<p>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.</p></div>
|
|
<div class="section">
|
|
<h3>Why the RSS and Atom beans don't have interface and implementation versions of it?<a name="Why_the_RSS_and_Atom_beans_dont_have_interface_and_implementation_versions_of_it"></a></h3>
|
|
<p>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.</p></div>
|
|
<div class="section">
|
|
<h3>How all the escaping for the description elements is handled for the different feed types as they keep changing their mind version after version?<a name="How_all_the_escaping_for_the_description_elements_is_handled_for_the_different_feed_types_as_they_keep_changing_their_mind_version_after_version"></a></h3>
|
|
<p>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.</p>
|
|
<p>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.</p></div>
|
|
<div class="section">
|
|
<h3>How does Rome handle Atom content elements that support encoding (Base64, XML, plain) using the mode attribute?<a name="How_does_Rome_handle_Atom_content_elements_that_support_encoding_Base64_XML_plain_using_the_mode_attribute"></a></h3>
|
|
<p>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.</p></div>
|
|
<div class="section">
|
|
<h3>What kind of input and output Rome supports?<a name="What_kind_of_input_and_output_Rome_supports"></a></h3>
|
|
<p>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.</p></div>
|
|
<div class="section">
|
|
<h3>What is the SyndFeedI.getSupportedFeedTypes() method for?<a name="What_is_the_SyndFeedI.getSupportedFeedTypes_method_for"></a></h3>
|
|
<p>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.</p></div>
|
|
<div class="section">
|
|
<h3>Are Rome beans Serializable? Why?<a name="Are_Rome_beans_Serializable_Why"></a></h3>
|
|
<p>Yes, the default bean implementations of SyndFeedI provided with Rome are Serializable.</p>
|
|
<p>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).</p></div>
|
|
<div class="section">
|
|
<h3>Why all those packages?<a name="Why_all_those_packages"></a></h3>
|
|
<p>TBD</p></div></div>
|
|
</div>
|
|
</div>
|
|
<div class="clear">
|
|
<hr/>
|
|
</div>
|
|
<div id="footer">
|
|
<div class="xright">
|
|
Copyright © 2004-2013
|
|
<a href="http://www.rometools.org">ROME Project</a>.
|
|
All Rights Reserved.
|
|
|
|
</div>
|
|
<div class="clear">
|
|
<hr/>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html> |