additional javadocs, and improved the javadoc generation rule in the build file

build.xml

@@ -444,8 +444,13 @@
       <group title="Low-Level Dynamo Framework" packages="com.silverwrist.dynamo:com.silverwrist.dynamo.*"/>
       <group title="Mid-Level Venice Classes" packages="com.silverwrist.venice:com.silverwrist.venice.*"/>
       <link href="http://java.sun.com/j2se/1.4.1/docs/api/"/>
+      <link href="http://java.sun.com/j2ee/sdk_1.3/techdocs/api/"/>
+      <link href="http://java.sun.com/products/javabeans/glasgow/javadocs/"/>
+      <link href="http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/"/>
       <link href="http://jakarta.apache.org/commons/collections/api/"/>
       <link href="http://jakarta.apache.org/commons/lang/api/"/>
+      <link href="http://jakarta.apache.org/log4j/docs/api/"/>
+      <link href="http://jakarta.apache.org/velocity/api/"/>
     </javadoc>
   </target>
 

src/dynamo-framework/com/silverwrist/dynamo/iface/ChainParameterInput.java

@@ -33,7 +33,7 @@ import java.util.Collection;
 public interface ChainParameterInput
 {
   /**
-   * Returns a <CODE>java.util.Collection</CODE> containing all names of external request parameters.
+   * Returns a {@link java.util.Collection Collection} containing all names of external request parameters.
    * Request parameters used internally by Dynamo itself will <EM>not</EM> be included in this list.
    *
    * @return The collection of parameter names.

src/dynamo-framework/com/silverwrist/dynamo/iface/ExternalAppAttributes.java

@@ -21,8 +21,8 @@ import java.util.Collection;
 
 /**
  * A request service which provides access to "application attributes" managed by the servlet container
- * itself (through <CODE>ServletContext</CODE>) and not by Dynamo.  This will often be needed, for instance,
+ * itself (through {@link javax.servlet.ServletContext ServletContext}) and not by Dynamo.  This will often be needed,
- * to interface with servlet-based APIs outside the scope of Dynamo.
+ * for instance, to interface with servlet-based APIs outside the scope of Dynamo.
  * <P><B>N.B.:</B> Dynamo itself requires several application-level attributes to manage its current state
  * (such as the {@link com.silverwrist.dynamo.app.ApplicationContainer ApplicationContainer} object).  This
  * service will not permit access to those reserved application-level attributes.
@@ -33,7 +33,7 @@ import java.util.Collection;
 public interface ExternalAppAttributes
 {
   /**
-   * Returns a <CODE>java.util.Collection</CODE> containing all names of external application attributes.
+   * Returns a {@link java.util.Collection Collection} containing all names of external application attributes.
    * Application attributes used internally by Dynamo itself will <EM>not</EM> be included in this list.
    *
    * @return The collection of attribute names.

src/dynamo-framework/com/silverwrist/dynamo/iface/ExternalSessionAttributes.java

@@ -21,8 +21,8 @@ import java.util.Collection;
 
 /**
  * A request service which provides access to "session attributes" managed by the servlet container
- * itself (through <CODE>HttpSession</CODE>) and not by Dynamo.  This will often be needed, for instance,
+ * itself (through {@link javax.servlet.http.HttpSession HttpSession}) and not by Dynamo.  This will often be needed,
- * to interface with servlet-based APIs outside the scope of Dynamo.
+ * for instance, to interface with servlet-based APIs outside the scope of Dynamo.
  * <P><B>N.B.:</B> Dynamo itself requires several session-level attributes to manage its current state
  * (such as the current {@link com.silverwrist.dynamo.iface.SessionInfo SessionInfo} object).  This
  * service will not permit access to those reserved session-level attributes.
@@ -33,7 +33,7 @@ import java.util.Collection;
 public interface ExternalSessionAttributes
 {
   /**
-   * Returns a <CODE>java.util.Collection</CODE> containing all names of external session attributes.
+   * Returns a {@link java.util.Collection Collection} containing all names of external session attributes.
    * Session attributes used internally by Dynamo itself will <EM>not</EM> be included in this list.
    *
    * @return The collection of attribute names.

src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLChecker.java

@@ -19,22 +19,77 @@ package com.silverwrist.dynamo.iface;
 
 import java.io.Reader;
 
+/**
+ * The public interface of the HTML Checker.  It is used to preprocess text which comes from the user which may have
+ * embedded HTML; it rejects HTML considered too dangerous, balances unclosed HTML tags, and can perform other actions
+ * as well (such as checking spelling).
+ * <P>The original HTML Checker was an ASP component created for Durand's CommunityWare in 1998.  A workalike version
+ * was written in Java, by Eric J. Bowersox, for a possible Java-based CommunityWare workalike; this code was
+ * completely rewritten in 2001, using a new design, for the initial versions of Venice, and has been rewritten yet
+ * again for Venice/Dynamo.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface HTMLChecker extends ObjectStore
 {
+  /**
+   * Appends the text contained in the string to the HTML Checker.
+   *
+   * @param str The text to be added to the HTML Checker.
+   */
   public void append(String str);
 
+  /**
+   * Appends the text contained in a {@link java.io.Reader Reader} to the HTML Checker.
+   *
+   * @param r Contains the text to be appended to the HTML Checker.
+   */
   public void append(Reader r);
 
+  /**
+   * Completes processing of the HTML Checker.  All internal parser states are resolved, all opened but unclosed HTML
+   * tags are closed, and the output is made available.
+   */
   public void finish();
 
+  /**
+   * Resets this instance of the HTML Checker.  All internal state is reset and the output is cleared.
+   */
   public void reset();
 
+  /**
+   * Returns the text value of this HTML Checker.  Can only be called after the {@link #finish() finish()} method
+   * is called on this instance of the HTML Checker.
+   *
+   * @return The text in this HTML Checker.
+   */
   public String getValue();
 
+  /**
+   * Returns the number of characters stored in this instance of the HTML Checker.  Can only be called after the
+   * {@link #finish() finish()} method is called on this instance of the HTML Checker.
+   *
+   * @return The number of characters stored in this instance of the HTML Checker.
+   */
   public int getLength();
 
+  /**
+   * Returns the number of lines of text stored in this instance of the HTML Checker.  Can only be called after the
+   * {@link #finish() finish()} method is called on this instance of the HTML Checker.
+   *
+   * @return The number of lines of text stored in this instance of the HTML Checker.
+   */
   public int getLines();
 
+  /**
+   * Returns the value of a registered counter on this instance of the HTML Checker.  Can only be called after the
+   * {@link #finish() finish()} method is called on this instance of the HTML Checker.
+   *
+   * @param namespace Namespace of the counter to read.
+   * @param name Name of the counter to read.
+   * @return The value of the counter.
+   */
   public int getCounter(String namespace, String name);
 
 } // end interface HTMLChecker

src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLCheckerConfigRegister.java

@@ -17,8 +17,25 @@
  */
 package com.silverwrist.dynamo.iface;
 
+/**
+ * An initialization service which is used to register new
+ * {@link com.silverwrist.dynamo.iface.HTMLCheckerConfigurator HTMLCheckerConfigurator} objects to be called for
+ * new HTML Checker profiles.
+ *
+ * @author Eric J. Bowersox <erbo@silcom.com>
+ * @version X
+ */
 public interface HTMLCheckerConfigRegister
 {
+  /**
+   * Registers a new {@link com.silverwrist.dynamo.iface.HTMLCheckerConfigurator HTMLCheckerConfigurator} object to
+   * be called on each new profile.
+   *
+   * @param cfg The <CODE>HTMLCheckerConfigurator</CODE> to register.
+   * @return An instance of {@link com.silverwrist.dynamo.iface.ComponentShutdown ComponentShutdown}; this instance's
+   *         {@link com.silverwrist.dynamo.iface.ComponentShutdown#shutdown() shutdown()} method may be called to
+   *         unregister the <CODE>HTMLCheckerConfigurator</CODE>.
+   */
   public ComponentShutdown registerConfigurator(HTMLCheckerConfigurator cfg);
 
 } // end interface HTMLCheckerConfigRegister

src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLCheckerConfigurator.java

@@ -17,8 +17,23 @@
  */
 package com.silverwrist.dynamo.iface;
 
+/**
+ * An object which is used to configure new HTML Checker profiles after they're loaded from the database.  When a
+ * profile is loaded, its basic properties are loaded from the database, then all registered
+ * <CODE>HTMLCheckerConfigurator</CODE> objects are called on the new profile; the objects can then read the
+ * configuration properties and insert code objects into the profile as necessary.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface HTMLCheckerConfigurator
 {
+  /**
+   * Use this configurator to configure the supplied
+   * {@link com.silverwrist.dynamo.iface.HTMLCheckerProfile HTMLCheckerProfile}.
+   *
+   * @param profile The profile to be configured.
+   */
   public void configure(HTMLCheckerProfile profile);
 
 } // end interface HTMLCheckerConfigurator

src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLCheckerProfile.java

@@ -17,22 +17,74 @@
  */
 package com.silverwrist.dynamo.iface;
 
+/**
+ * The interface which is used to configure the HTML Checker.  An instance of this interface is passed to all
+ * registered {@link com.silverwrist.dynamo.iface.HTMLCheckerConfigurator HTMLCheckerConfigurator} objects, allowing
+ * them to read off the configuration variables (as loaded from the database) and add active code to the HTML Checker
+ * by means of this interface's methods.
+ *
+ * @author Eric J. Bowersox <erbo@silcom.com>
+ * @version X
+ */
 public interface HTMLCheckerProfile extends ObjectProvider
 {
+  /**
+   * Adds a new output filter which is called to process both non-markup data.  Markup data does not pass through
+   * this filter.
+   *
+   * @param filter The output filter to add.
+   */
   public void addOutputFilter(HTMLOutputFilter filter);
 
+  /**
+   * Adds a new output filter which is called to process both markup and non-markup data.
+   *
+   * @param filter The output filter to add.
+   */
   public void addRawOutputFilter(HTMLOutputFilter filter);
 
+  /**
+   * Adds a new rewriter which can rewrite text strings in the input.  A "string" is a series of non-whitespace
+   * characters delimited by whitespace.
+   *
+   * @param rewriter The rewriter to add.
+   */
   public void addStringRewriter(HTMLRewriter rewriter);
 
+  /**
+   * Adds a new rewriter which can rewrite text words in the input.  A "word" is a series of word characters (letters,
+   * apostrophe, hyphen) delimited by non-word characters or whitespace.
+   *
+   * @param rewriter The rewriter to add.
+   */
   public void addWordRewriter(HTMLRewriter rewriter);
 
+  /**
+   * Adds a new rewriter which can rewrite text contained within angle brackets in the HTML Checker input.
+   *
+   * @param rewriter The rewriter to add.
+   */
   public void addTagRewriter(HTMLRewriter rewriter);
 
+  /**
+   * Adds a new rewriter which can rewrite text contained within parentheses in the HTML Checker input.
+   *
+   * @param rewriter The rewriter to add.
+   */
   public void addParenRewriter(HTMLRewriter rewriter);
 
+  /**
+   * Adds a new rewriter which can rewrite text contained within square brackets in the HTML Checker input.
+   *
+   * @param rewriter The rewriter to add.
+   */
   public void addBracketRewriter(HTMLRewriter rewriter);
 
+  /**
+   * Adds a new rewriter which can rewrite text contained within curly braces in the HTML Checker input.
+   *
+   * @param rewriter The rewriter to add.
+   */
   public void addBraceRewriter(HTMLRewriter rewriter);
 
 } // end interface HTMLCheckerProfile

src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLCheckerService.java

@@ -19,8 +19,26 @@ package com.silverwrist.dynamo.iface;
 
 import com.silverwrist.dynamo.except.DatabaseException;
 
+/**
+ * A runtime service interface which is used to create new instances of the HTML CHecker.  Instances of the
+ * HTML Checker are identified by the namespace URI and name of their profiles, which are loaded from the
+ * database.
+ *
+ * @author Eric J. Bowersox <erbo@silcom.com>
+ * @version X
+ */
 public interface HTMLCheckerService
 {
+  /**
+   * Creates a new instance of the HTML Checker with a specified profile and returns a reference to its
+   * {@link com.silverwrist.dynamo.iface.HTMLChecker HTMLChecker} interface.
+   *
+   * @param profile_namespace Namespace URI for the profile to use.
+   * @param profile_name Name of the profile to use.
+   * @return Reference to the newly-created HTML Checker object.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error retrieving the specified profile
+   *            information from the database.
+   */
   public HTMLChecker createHTMLChecker(String profile_namespace, String profile_name) throws DatabaseException;
 
 } // end interface HTMLCheckerService

src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLOutputFilter.java

@@ -17,12 +17,42 @@
  */
 package com.silverwrist.dynamo.iface;
 
+/**
+ * An interface implemented by HTML Checker <EM>output filters</EM>, which process all characters prior to their being
+ * placed in the output buffer.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface HTMLOutputFilter
 {
+  /**
+   * Checks and possibly outputs a character.  If the character <EM>ch</EM> is handled by this filter, it appends
+   * the encoded equivalent to the string buffer <EM>buf</EM> and returns <CODE>true</CODE>.  If not, it returns
+   * <CODE>false</CODE> and leaves the buffer alone.
+   *
+   * @param buf The string buffer to append the character equivalent to.
+   * @param ch The character to be checked and possibly output.
+   * @return <CODE>true</CODE> if the character matches and was output, <CODE>false</CODE> if not.
+   */
   public boolean tryOutputCharacter(StringBuffer buf, char ch);
 
+  /**
+   * Returns <CODE>true</CODE> if the character <EM>ch</EM> is handled by this filter, <CODE>false</CODE> if not.
+   *
+   * @param ch The character to be tested.
+   * @return <CODE>true</CODE> if the character <EM>ch</EM> is handled by this filter, <CODE>false</CODE> if not.
+   */
   public boolean matchCharacter(char ch);
 
+  /**
+   * Given a character string, returns the total number of characters in that string, starting from the beginning,
+   * that are <I>not</I> handled by this filter before one that <I>is</I> appears.  If none of the characters in this
+   * string are handled by the filter, the length of the string is returned.
+   *
+   * @param s The string to scan through.
+   * @return The length of the initial sequence of non-matching characters in this string.
+   */
   public int lengthNoMatch(String s);
 
 } // end interface HTMLOutputFilter

src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLRewriter.java

@@ -20,10 +20,36 @@ package com.silverwrist.dynamo.iface;
 import com.silverwrist.dynamo.htmlcheck.MarkupData;
 import com.silverwrist.dynamo.util.QualifiedNameKey;
 
+/**
+ * An interface implemented by HTML Checker <EM>rewriters</EM>, which rewrite specific sequences of text in the HTML
+ * Checker's input.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface HTMLRewriter
 {
+  /**
+   * Returns the name of this rewriter.  If this returns a value other than <CODE>null</CODE>, the HTML Checker will
+   * create a counter with this name, which will count the number of times the rewriter chooses to rewrite the text.
+   *
+   * @return The namespace and name of this rewriter as a
+   *         {@link com.silverwrist.dynamo.util.QualifiedNameKey QualifiedNameKey}, or <CODE>null</CODE>.
+   */
   public QualifiedNameKey getName();
 
+  /**
+   * Determines whether to rewrite the specified text, and rewrites it if necessary.  The
+   * {@link com.silverwrist.dynamo.htmlcheck.MarkupData MarkupData} object provides for beginning and ending markup
+   * and text surrounding the text in question.
+   *
+   * @param data The text to be checked and possibly rewritten.
+   * @param prefix A string to be used as a prefix for the result; may be <CODE>null</CODE>.
+   * @param suffix A string to be used as a suffix for the result; may be <CODE>null</CODE>.
+   * @param site Provides an interface for the rewriter to interact with the HTML Checker's context and attributes.
+   * @return <CODE>null</CODE> if the text should not be rewritten, or a
+   *         {@link com.silverwrist.dynamo.htmlcheck.MarkupData MarkupData} object containing the rewritten text.
+   */
   public MarkupData rewrite(String data, String prefix, String suffix, HTMLRewriterSite site);
 
 } // end interface HTMLRewriter

src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLRewriterSite.java

@@ -17,8 +17,22 @@
  */
 package com.silverwrist.dynamo.iface;
 
+/**
+ * An interface supplying services to an instance of {@link com.silverwrist.dynamo.iface.HTMLRewriter HTMLRewriter}.
+ * It allows the rewriter to examine the context and configuration attributes of the HTML Checker.
+ *
+ * @author Eric J. Bowersox <erbo@silcom.com>
+ * @version X
+ */
 public interface HTMLRewriterSite extends ObjectProvider
 {
+  /**
+   * Returns a configuration attribute of the HTML Checker.
+   *
+   * @param namespace Namespace URI of the configuration attribute to return.
+   * @param name Name of the configuration attribute to return.
+   * @return The configuration attribute value, or <CODE>null</CODE> if the configuration attribute did not exist.
+   */
   public String getAttribute(String namespace, String name);
 
 } // end interface HTMLRewriterSite