svn commit: r468540 - in /incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser: NamedParser.java Parser.java ParserFactory.java ParserOptions.java

[jm...@apache.org]

Author: jmsnell
Date: Fri Oct 27 14:02:34 2006
New Revision: 468540

URL: http://svn.apache.org/viewvc?view=rev&rev=468540
Log:
Update Javadocs.
Remove unnecessary throws statements

Modified:
    incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/NamedParser.java
    incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/Parser.java
    incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/ParserFactory.java
    incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/ParserOptions.java

Modified: incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/NamedParser.java
URL: http://svn.apache.org/viewvc/incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/NamedParser.java?view=diff&rev=468540&r1=468539&r2=468540
==============================================================================
--- incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/NamedParser.java (original)
+++ incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/NamedParser.java Fri Oct 27 14:02:34 2006
@@ -17,18 +17,39 @@
 */
 package org.apache.abdera.parser;
 
+/**
+ * Abdera's abstract parsing model allows developers to implement parsers 
+ * capable of translating non-Atom formats into Abdera objects.  For instance,
+ * a developer could create an RDF, RSS, JSON or hAtom microformat parser that 
+ * automatically converted to Atom.  Alternative parsers are made available
+ * via the ParserFactory interface.
+ * 
+ * <pre>
+ *   Parser parser = abdera.getParserFactory().getParser("json");
+ *   Document&lt;Feed> doc = parser.parse(...);
+ *   
+ *   Parser parser = abdera.getParserFactory().getParser("hatom");
+ *   Document&lt;Feed> doc = parser.parse(...);
+ * </pre>
+ */
 public interface NamedParser extends Parser {
 
+  /**
+   * Returns the name used to retrieve this parser (case insensitive)
+   * @return The name of this parser
+   */
   String getName();
   
   /**
-   * Return the media type of the format consumed by this parser
+   * Returns a listing of media type of the format consumed by this parser
+   * @return An array of MIME Media Types
    */
   String[] getInputFormats();
   
   /**
-   * Returns true if the format consumed by this parser matches the specified
-   * media type
+   * Returns true if this parser is capable of consuming the specified media type
+   * @param mediatype The MIME media type to check
+   * @return True if the media type is supported
    */
   boolean parsesFormat(String mediatype);
 }

Modified: incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/Parser.java
URL: http://svn.apache.org/viewvc/incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/Parser.java?view=diff&rev=468540&r1=468539&r2=468540
==============================================================================
--- incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/Parser.java (original)
+++ incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/Parser.java Fri Oct 27 14:02:34 2006
@@ -19,49 +19,113 @@
 
 import java.io.InputStream;
 import java.io.Reader;
-import java.net.URISyntaxException;
 
 import org.apache.abdera.model.Document;
 import org.apache.abdera.model.Element;
 import org.apache.abdera.util.iri.IRISyntaxException;
 
-/**
- * The Parser is the interface through which developers parse feed documents. 
- */
 public interface Parser {
-  
+
+  /**
+   * Parse the input stream using the default character set encoding (UTF-8)
+   * @param in The input stream to parse
+   * @return The parsed Abdera Document
+   * @throws ParseException if the parse failed
+   */
   <T extends Element>Document<T> parse(
     InputStream in) 
       throws ParseException, IRISyntaxException;
   
+  /**
+   * Parse the input stream using the default character set encoding (UTF-8).
+   * The specified Base URI is used to resolve relative references contained
+   * in the document
+   * @param in The input stream to parse
+   * @param base The Base URI of the document
+   * @return The parsed Abdera Document
+   * @throws ParseException if the parse failed
+   * @throws IRISyntaxException if the Base URI is malformed
+   */
   <T extends Element>Document<T> parse(
     InputStream in, 
     String base) 
       throws ParseException, IRISyntaxException;
   
+  /**
+   * Parse the input stream using using the specified Parse options.  The 
+   * parse options can be used to control various aspects of the parsing
+   * process such as the character set encoding to use and whether certain
+   * elements should be ignored.  The specified Base URI is used to resolve
+   * relative references contained in the document.
+   * @param in The input stream to parse
+   * @param base The Base URI of the document
+   * @param options The Parse Options
+   * @return The parsed Abdera Document
+   * @throws ParseException if the parse failed
+   * @throws IRISyntaxException if the Base URI is malformed
+   */
   <T extends Element>Document<T> parse(
     InputStream in, 
     String base, 
     ParserOptions options) 
       throws ParseException, IRISyntaxException;
 
+  /**
+   * Parse the reader using the default Base URI and options
+   * @param in The Reader to parse
+   * @return The parsed Abdera Document
+   * @throws ParseException if the parse failed
+   * @throws IRISyntaxException if the Base URI is malformed
+   */
   <T extends Element>Document<T> parse(
       Reader in) 
-        throws ParseException, URISyntaxException, IRISyntaxException;
+        throws ParseException, IRISyntaxException;
     
+  /**
+   * Parse the reader using the specified Base URI
+   * @param in The Reader to parse
+   * @param base The Base URI
+   * @return The parsed Abdera Document
+   * @throws ParseException if the parse failed
+   * @throws IRISyntaxException if the Base URI is malformed
+   */
   <T extends Element>Document<T> parse(
     Reader in, 
     String base) 
-      throws ParseException, IRISyntaxException, URISyntaxException;
+      throws ParseException, IRISyntaxException;
   
+  /**
+   * Parse the reader using using the specified Parse options.  The 
+   * parse options can be used to control various aspects of the parsing
+   * process such as the character set encoding to use and whether certain
+   * elements should be ignored.  The specified Base URI is used to resolve
+   * relative references contained in the document.
+   * @param in The reader to parse
+   * @param base The Base URI of the document
+   * @param options The Parse Options
+   * @return The parsed Abdera Document
+   * @throws ParseException if the parse failed
+   * @throws IRISyntaxException if the Base URI is malformed
+   */
   <T extends Element>Document<T> parse(
     Reader in, 
     String base, 
     ParserOptions options) 
       throws ParseException, IRISyntaxException;
   
+  /**
+   * Return the default parser options for this Parser. This method 
+   * returns a copy of the default options.  Changes to this instance
+   * will not affect the defaults returned by subsequent requests.
+   * @return The default ParserOptions
+   */
   ParserOptions getDefaultParserOptions();
   
+  /**
+   * Set the default parser options for this Parser.  This method 
+   * copies the specified options.
+   * @param options The Parser Options to use as the default
+   */
   void setDefaultParserOptions(ParserOptions options);
   
 }

Modified: incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/ParserFactory.java
URL: http://svn.apache.org/viewvc/incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/ParserFactory.java?view=diff&rev=468540&r1=468539&r2=468540
==============================================================================
--- incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/ParserFactory.java (original)
+++ incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/ParserFactory.java Fri Oct 27 14:02:34 2006
@@ -17,10 +17,24 @@
 */
 package org.apache.abdera.parser;
 
+/**
+ * The ParserFactory is used a acquire instances of alternative 
+ * parsers registered with Abdera.  
+ * @see org.apache.abdera.parser.NamedParser 
+ */
 public interface ParserFactory {
   
+  /**
+   * Get the default parser.  This is equivalent to calling Abdera.getParser()
+   * @return The default parser implementation
+   */
   Parser getParser();
   
+  /**
+   * Get the named parser
+   * @param name The name of the parser instance to retrieve
+   * @return The Named parser instance
+   */
   Parser getParser(String name); 
   
 }

Modified: incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/ParserOptions.java
URL: http://svn.apache.org/viewvc/incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/ParserOptions.java?view=diff&rev=468540&r1=468539&r2=468540
==============================================================================
--- incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/ParserOptions.java (original)
+++ incubator/abdera/java/trunk/core/src/main/java/org/apache/abdera/parser/ParserOptions.java Fri Oct 27 14:02:34 2006
@@ -27,9 +27,6 @@
  */
 public interface ParserOptions extends Cloneable {
 
-  /**
-   * Return a duplicate of this options object.
-   */
   Object clone() throws CloneNotSupportedException;
 
   /**