added javadocs to more of the Dynamo interfaces

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

@@ -11,16 +11,33 @@
  * 
  * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
  * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
- * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
+ * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
  * 
  * Contributor(s): 
  */
 package com.silverwrist.dynamo.iface;
 
+/**
+ * An extension of {@link com.silverwrist.dynamo.iface.AuditRecord AuditRecord} used for audit records that are
+ * being composed and written into the database.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface AuditRecordCompose extends AuditRecord
 {
+  /**
+   * Sets a property on an audit record.  A property is like an "argument" to the audit record,
+   * and may be of any type that can be serialized by the Dynamo PropertySerializer.
+   *
+   * @param index Index of the property to set (0-based).  Up to 8 properties are supported.
+   * @param value Value of the property to be set.
+   */
   public void setProperty(int index, Object value);
 
+  /**
+   * Writes this audit record to the database.
+   */
   public void write();
   
 } // end interface AuditRecordCompose

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

@@ -11,19 +11,53 @@
  * 
  * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
  * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
- * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
+ * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
  * 
  * Contributor(s): 
  */
 package com.silverwrist.dynamo.iface;
 
+/**
+ * An interface which is used to create new audit records for insertion into the database.  The new audit records
+ * have all their basic data items filled in, but none of their optional properties, and are not written to the
+ * database until their {@link com.silverwrist.dynamo.iface.AuditRecordCompose#write() write()} method is called.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface AuditRecordFactory
 {
+  /**
+   * Creates a new audit record.
+   *
+   * @param r The current {@link com.silverwrist.dynamo.iface.Request Request} we are processing.
+   * @param user The user that has perfomed the request.
+   * @param namespace The namespace URI of the audit record type to be written.
+   * @param name The name of the audit record type to be written.
+   * @return The new audit record.
+   */
   public AuditRecordCompose createAuditRecord(Request r, DynamoUser user, String namespace, String name);
 
+  /**
+   * Creates a new audit record.
+   *
+   * @param r The current {@link com.silverwrist.dynamo.iface.Request Request} we are processing.
+   * @param user The user that has perfomed the request.
+   * @param subid The subidentifier value for this audit record.
+   * @param namespace The namespace URI of the audit record type to be written.
+   * @param name The name of the audit record type to be written.
+   * @return The new audit record.
+   */
   public AuditRecordCompose createAuditRecord(Request r, DynamoUser user, int subid, String namespace,
 					      String name);
 
+  /**
+   * Creates a new "system-level" audit record, which is normally used only for system-level events.
+   *
+   * @param namespace The namespace URI of the audit record type to be written.
+   * @param name The name of the audit record type to be written.
+   * @return The new audit record.
+   */
   public AuditRecordCompose createSystemAuditRecord(String namespace, String name);
 
 } // end interface AuditRecordFactory

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

@@ -11,7 +11,7 @@
  * 
  * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
  * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
- * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
+ * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
  * 
  * Contributor(s): 
  */
@@ -20,11 +20,34 @@ package com.silverwrist.dynamo.iface;
 import java.util.Date;
 import com.silverwrist.dynamo.except.DatabaseException;
 
+/**
+ * An interface which is used to retrieve audit records from the database by date and time.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface AuditRecordRetrieval
 {
+  /**
+   * Retrieves a set of audit records from the database.
+   *
+   * @param start_date Starting date/time of the audit records to retrieve.
+   * @param end_date Ending date/time of the audit records to retrieve.
+   * @return An {@link com.silverwrist.dynamo.iface.AuditRecordSet} containing the audit records.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was a problem retrieving the audit records.
+   */
   public AuditRecordSet getAuditRecords(java.util.Date start_date, java.util.Date end_date)
       throws DatabaseException;
 
+  /**
+   * Retrieves a set of audit records from the database.
+   *
+   * @param start_date Starting date/time of the audit records to retrieve.
+   * @param end_date Ending date/time of the audit records to retrieve.
+   * @param subid Subidentifier that all retrieved audit records must match.
+   * @return An {@link com.silverwrist.dynamo.iface.AuditRecordSet} containing the audit records.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was a problem retrieving the audit records.
+   */
   public AuditRecordSet getAuditRecords(java.util.Date start_date, java.util.Date end_date, int subid)
       throws DatabaseException;
 

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

@@ -11,7 +11,7 @@
  * 
  * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
  * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
- * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
+ * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
  * 
  * Contributor(s): 
  */
@@ -19,10 +19,29 @@ package com.silverwrist.dynamo.iface;
 
 import com.silverwrist.dynamo.except.DatabaseException;
 
+/**
+ * An interface wrapping a set of audit records.  This is returned by the methods of the
+ * {@link com.silverwrist.dynamo.iface.AuditRecordRetrieval AuditRecordRetrieval} interface.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface AuditRecordSet
 {
+  /**
+   * Returns the number of audit records in this set.
+   *
+   * @return The number of audit records in this set.
+   */
   public int getRecordCount();
 
+  /**
+   * Returns a specific {@link com.silverwrist.dynamo.iface.AuditRecord AuditRecord} from this set.
+   *
+   * @param index 0-based index of the audit record to be retrieved.
+   * @return The audit record.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was a problem retrieving the audit record.
+   */
   public AuditRecord getRecord(int index) throws DatabaseException;
 
 } // end interface AuditRecordSet

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

@@ -11,7 +11,7 @@
  * 
  * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
  * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
- * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
+ * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
  * 
  * Contributor(s): 
  */
@@ -19,10 +19,43 @@ package com.silverwrist.dynamo.iface;
 
 import com.silverwrist.dynamo.except.AuthenticationException;
 
+/**
+ * The public intrface implemented by all Dynamo <EM>authenticators</EM>.  An <EM>authenticator</EM> is a piece of
+ * code that handles two tasks:
+ * <OL>
+ *   <LI>The transformation of private authentication data into a format suitable for storing in the database.</LI>
+ *   <LI>The comparison of that private data to private data obtained from the user, and returning whether or not
+ *     it matches.</LI>
+ * </OL>
+ * For example, in the {@link com.silverwrist.dynamo.db.DefaultHashAuthenticator DefaultHashAuthenticator}, the
+ * former task consists of taking a password and processing it through a secure one-way hash function to produce a
+ * string which may be stored in the database, and the latter task consists of applying the same function to a user-
+ * supplied password and comparing the resulting hash value against the one retrieved from the database.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface Authenticator
 {
+  /**
+   * Given a piece of stored authentication data (which has been transformed with
+   * {@link #processInputData(java.lang.String) processInputData()}) and a piece of user-supplied authentication
+   * data (which has not), returns whether or not they match.
+   *
+   * @param stored_data The stored authentication data from the database.
+   * @param input_data The input authentication data from the user,
+   * @return <CODE>true</CODE> if the two pieces of data match, <CODE>false</CODE> if not.
+   * @exception com.silverwrist.dynamo.except.AuthenticationException If there was a problem with the authenticator.
+   */
   public boolean authenticate(String stored_data, String input_data) throws AuthenticationException;
 
+  /**
+   * Transforms a piece of input data, such as a password, into a format suitable for storing in the database.
+   *
+   * @param input_data Input data to be transformed.
+   * @return The transformed input data.
+   * @exception com.silverwrist.dynamo.except.AuthenticationException If there was a problem with the authenticator.
+   */
   public String processInputData(String input_data) throws AuthenticationException;
 
 } // end interface Authenticator

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

@@ -11,14 +11,30 @@
  * 
  * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
  * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
- * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
+ * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
  * 
  * Contributor(s): 
  */
 package com.silverwrist.dynamo.iface;
 
+/**
+ * A service interface which permits the retrieval of registered
+ * {@link com.silverwrist.dynamo.iface.Authenticator Authenticator} objects.  Authenticators are identified by
+ * namespace URI and name.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface AuthenticatorLookup
 {
+  /**
+   * Retrieves an authenticator that has been registered with the system.
+   *
+   * @param method_namespace Namespace URI of the authenticator to be retrieved.
+   * @param method Name of the authenticator to be retrieved.
+   * @return The registered {@link com.silverwrist.dynamo.iface.Authenticator Authenticator}, or <CODE>null</CODE>
+   *         if no such registered authenticator exists.
+   */
   public Authenticator findAuthenticator(String method_namespace, String method);
 
 } // end interface AuthenticatorLookup

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

@@ -11,7 +11,7 @@
  * 
  * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
  * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
- * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
+ * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
  * 
  * Contributor(s): 
  */
@@ -19,8 +19,26 @@ package com.silverwrist.dynamo.iface;
 
 import com.silverwrist.dynamo.except.ConfigException;
 
+/**
+ * A service interface which allows Dynamo components or modules to register an authentication method for
+ * use by the system.  Authenticators are identified by namespace URI and name.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface AuthenticatorRegistration extends AuthenticatorLookup
 {
+  /**
+   * Registers an instance of an {@link com.silverwrist.dynamo.iface.Authenticator Authenticator} with the system.
+   *
+   * @param method_namespace Namespace URI of the authentication method to register.
+   * @param method Name of the authentication method to register.
+   * @param auth The <CODE>Authenticator</CODE> which implements the authentication method.
+   * @return An instance of {@link com.silverwrist.dynamo.iface.ComponentShutdown ComponentShutdown} whose
+   *         {@link com.silverwrist.dynamo.iface.ComponentShutdown#shutdown() shutdown()} method may be called
+   *         to unregister the authenticator.
+   * @exception com.silverwrist.dynamo.except.ConfigException If there was an error registering the authenticator.
+   */
   public ComponentShutdown registerAuthenticator(String method_namespace, String method, Authenticator auth)
       throws ConfigException;
 

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

@@ -11,7 +11,7 @@
  * 
  * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
  * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
- * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
+ * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
  * 
  * Contributor(s): 
  */
@@ -22,8 +22,23 @@ import java.io.OutputStream;
 import javax.servlet.http.HttpServletResponse;
 import com.silverwrist.dynamo.except.RenderingException;
 
+/**
+ * The interface implemented by the rendering control object used with
+ * {@link com.silverwrist.dynamo.iface.BinaryRenderer BinaryRenderer}.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface BinaryRenderControl extends RenderControl
 {
+  /**
+   * Returns an {@link java.io.OutputStream OutputStream} which may be used to output the binary data of the rendering.
+   *
+   * @return The output stream.
+   * @exception java.io.IOException If there was an I/O error getting the output stream.
+   * @exception com.silverwrist.dynamo.except.RenderingException If there was another problem getting the output
+   *            stream.
+   */
   public OutputStream getStream() throws IOException, RenderingException;
 
 } // end interface BinaryRenderControl

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

@@ -11,7 +11,7 @@
  * 
  * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
  * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
- * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
+ * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
  * 
  * Contributor(s): 
  */
@@ -20,8 +20,28 @@ package com.silverwrist.dynamo.iface;
 import java.io.IOException;
 import com.silverwrist.dynamo.except.RenderingException;
 
+/**
+ * An interface implemented by <EM>rendering objects</EM> which renders the specified object as a binary object
+ * (such as an image, file attachment, or similar).  The rendering object uses the data in the supplied object, as
+ * well as the methods supplied in the {@link com.silverwrist.dynamo.iface.BinaryRenderControl BinaryRenderControl}
+ * interface, to generate an output rendering.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface BinaryRenderer extends Renderer
 {
+  /**
+   * Renders the specified object to the output in binary mode.
+   *
+   * @param obj The object to be rendered.
+   * @param control A rendering control object that provides the means to render this object to the output, as
+   *                well as providing "output services" (through the
+   *                {@link com.silverwrist.dynamo.iface.ServiceProvider ServiceProvider} interface) for the
+   *                rendering process to use.
+   * @exception java.io.IOException If an I/O error occurs while writing the output.
+   * @exception com.silverwrist.dynamo.except.RenderingException If the rendering process fails.
+   */
   public void render(Object obj, BinaryRenderControl control) throws IOException, RenderingException;
   
 } // end interface BinaryRenderer

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

@@ -11,7 +11,7 @@
  * 
  * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
  * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
- * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
+ * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
  * 
  * Contributor(s): 
  */
@@ -22,10 +22,31 @@ import java.io.PrintWriter;
 import javax.servlet.http.HttpServletResponse;
 import com.silverwrist.dynamo.except.RenderingException;
 
+/**
+ * The parent interface of <EM>rendering control objects</EM>, which provide the means by which rendering objects can
+ * output their renderings to the user's browser.  All rendering control objects incorporate a
+ * {@link com.silverwrist.dynamo.iface.ServiceProvider ServiceProvider} interface, which supplies "output services"
+ * for the use of the rendering object.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface RenderControl extends ServiceProvider
 {
+  /**
+   * Sets the content type (MIME type) of the output.
+   *
+   * @param type The content type to be set.
+   * @exception com.silverwrist.dynamo.except.RenderingException If there was a problem setting the content type.
+   */
   public void setContentType(String type) throws RenderingException;
 
+  /**
+   * Sets the content length (in bytes) for the output.
+   *
+   * @param length The content length to be set.
+   * @exception com.silverwrist.dynamo.except.RenderingException If there was a problem setting the content length.
+   */
   public void setContentLength(int length) throws RenderingException;
 
 } // end interface RenderControl

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

@@ -11,12 +11,21 @@
  * 
  * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
  * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
- * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
+ * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
  * 
  * Contributor(s): 
  */
 package com.silverwrist.dynamo.iface;
 
+/**
+ * An interface which is implemented by all <EM>rendering objects</EM>, whose function is to take objects returned
+ * by the processing phase of Dynamo operation and turn them into HTML, which is output to the browser.  Rendering
+ * objects are registered to handle objects of a specific class (and all subclasses thereof, where applicable),
+ * and are looked up as part of the output phase.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface Renderer
 { // no methods of its own - used only to identify TextRenderers and BinaryRenderers
 } // end interface Renderer

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

@@ -11,7 +11,7 @@
  * 
  * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
  * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
- * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
+ * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
  * 
  * Contributor(s): 
  */
@@ -21,18 +21,77 @@ import java.io.IOException;
 import com.silverwrist.dynamo.HttpStatusCode;
 import com.silverwrist.dynamo.except.RenderingException;
 
+/**
+ * The interface implemented by the rendering control object used by
+ * {@link com.silverwrist.dynamo.iface.SelfRenderable SelfRenderable} objects.<P>
+ * Note that this interface, unlike the other rendering control interfaces, does not extend
+ * {@link com.silverwrist.dynamo.iface.RenderControl RenderControl}; however, its
+ * {@link #getTextRender() getTextRender()} and {@link #getBinaryRender() getBinaryRender()} methods return objects
+ * that do.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface SelfRenderControl extends ServiceProvider
 {
+  /**
+   * Sends an HTTP status code to the browser.  This may be combined with other output methods to write a specific
+   * message.
+   *
+   * @param code The status code to be sent to the browser.
+   * @exception java.io.IOException If there was an I/O error sending the status code.
+   * @exception com.silverwrist.dynamo.except.RenderingException If there was another error sending the status code
+   *            (for example, if the code has already been set).
+   */
   public void status(HttpStatusCode code) throws RenderingException;
 
+  /**
+   * Causes the browser to redirect to another URL.  Sends a "302 Redirect" status code to the browser.
+   *
+   * @param location URL to redirect the browser to.
+   * @exception java.io.IOException If there was an I/O error sending the redirect.
+   * @exception com.silverwrist.dynamo.except.RenderingException If there was another error sending the redirect
+   *            (for example, if text has already been written).
+   */
   public void redirect(String location) throws IOException, RenderingException;
 
+  /**
+   * Sends an HTTP error message to the browser.
+   *
+   * @param code The status code to be sent to the browser.
+   * @exception java.io.IOException If there was an I/O error sending the error message.
+   * @exception com.silverwrist.dynamo.except.RenderingException If there was another error sending the error message
+   *            (for example, if text has already been written).
+   */
   public void error(HttpStatusCode code) throws IOException, RenderingException;
 
+  /**
+   * Sends an HTTP error message to the browser.
+   *
+   * @param code The status code to be sent to the browser.
+   * @param message The error message to be sent to the browser.
+   * @exception java.io.IOException If there was an I/O error sending the error message.
+   * @exception com.silverwrist.dynamo.except.RenderingException If there was another error sending the error message
+   *            (for example, if text has already been written).
+   */
   public void error(HttpStatusCode code, String message) throws IOException, RenderingException;
 
+  /**
+   * Returns a rendering control interface suitable for rendering an object in text mode.
+   *
+   * @return An instance of {@link com.silverwrist.dynamo.iface.TextRenderControl TextRenderControl}.
+   * @exception com.silverwrist.dynamo.except.RenderingException If the text rendering interface cannot be returned
+   *            (for instance, if this object is already rendering in binary mode).
+   */
   public TextRenderControl getTextRender() throws RenderingException;
 
+  /**
+   * Returns a rendering control interface suitable for rendering an object in binary mode.
+   *
+   * @return An instance of {@link com.silverwrist.dynamo.iface.BinaryRenderControl BinaryRenderControl}.
+   * @exception com.silverwrist.dynamo.except.RenderingException If the binary rendering interface cannot be returned
+   *            (for instance, if this object is already rendering in text mode).
+   */
   public BinaryRenderControl getBinaryRender() throws RenderingException;
 
 } // end interface SelfRenderControl

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

@@ -11,7 +11,7 @@
  * 
  * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
  * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
- * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
+ * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
  * 
  * Contributor(s): 
  */
@@ -22,8 +22,9 @@ import com.silverwrist.dynamo.except.RenderingException;
 
 /**
  * An interface implemented on Dynamo output objects to indicate that they are capable of rendering themselves
- * to the output.  <CODE>SelfRenderable</CODE> objects have access to greater capability (afforded them by
- * the {@link com.silverwrist.dynamo.iface.SelfRenderControl SelfRenderControl} interface) than ordinary text or
+ * to the output, without the use of a {@link com.silverwrist.dynamo.iface.Renderer Renderer} object.
+ * <CODE>SelfRenderable</CODE> objects have access to greater capability (afforded them by the
+ * {@link com.silverwrist.dynamo.iface.SelfRenderControl SelfRenderControl} interface) than ordinary text or
  * binary renderable objects do, and are frequently used to perform "special" operations.
  *
  * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;

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

@@ -11,7 +11,7 @@
  * 
  * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
  * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
- * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
+ * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
  * 
  * Contributor(s): 
  */
@@ -21,10 +21,37 @@ import java.io.IOException;
 import java.io.PrintWriter;
 import com.silverwrist.dynamo.except.RenderingException;
 
+/**
+ * The interface implemented by the rendering control object used with
+ * {@link com.silverwrist.dynamo.iface.TextRenderer TextRenderer}.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface TextRenderControl extends RenderControl
 {
+  /**
+   * Returns a {@link java.io.PrintWriter PrintWriter} which may be used to output the textual data of the rendering.
+   *
+   * @return The output writer.
+   * @exception java.io.IOException If there was an I/O error getting the output writer.
+   * @exception com.silverwrist.dynamo.except.RenderingException If there was another problem getting the output
+   *            writer.
+   */
   public PrintWriter getWriter() throws IOException, RenderingException;
 
+  /**
+   * Renders another object to the output at the output's current position.  The object to be rendered must be
+   * renderable in text format, either by means of a registered
+   * {@link com.silverwrist.dynamo.iface.TextRenderer TextRenderer} object, by means of implementing
+   * {@link com.silverwrist.dynamo.iface.SelfRenderable SelfRenderable} (which implementation cannot use the
+   * binary or special rendering methods of {@link com.silverwrist.dynamo.iface.SelfRenderControl SelfRenderControl}),
+   * or by default (via the object's {@link java.lang.Object#toString() toString()} method).
+   *
+   * @param obj The subobject to be rendered.
+   * @exception java.io.IOException If there was an I/O error rendering the object.
+   * @exception com.silverwrist.dynamo.except.RenderingException If there was another problem rendering the object.
+   */
   public void renderSubObject(Object obj) throws IOException, RenderingException;
 
 } // end interface TextRenderControl

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

@@ -11,7 +11,7 @@
  * 
  * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
  * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
- * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
+ * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
  * 
  * Contributor(s): 
  */
@@ -20,8 +20,28 @@ package com.silverwrist.dynamo.iface;
 import java.io.IOException;
 import com.silverwrist.dynamo.except.RenderingException;
 
+/**
+ * An interface implemented by <EM>rendering objects</EM> which renders the specified object as a text object
+ * (such as an HTML page).  The rendering object uses the data in the supplied object, as well as the methods
+ * supplied in the {@link com.silverwrist.dynamo.iface.TextRenderControl TextRenderControl} interface, to generate
+ * an output rendering.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface TextRenderer extends Renderer
 {
+  /**
+   * Renders the specified object to the output in text mode.
+   *
+   * @param obj The object to be rendered.
+   * @param control A rendering control object that provides the means to render this object to the output, as
+   *                well as providing "output services" (through the
+   *                {@link com.silverwrist.dynamo.iface.ServiceProvider ServiceProvider} interface) for the
+   *                rendering process to use.
+   * @exception java.io.IOException If an I/O error occurs while writing the output.
+   * @exception com.silverwrist.dynamo.except.RenderingException If the rendering process fails.
+   */
   public void render(Object obj, TextRenderControl control) throws IOException, RenderingException;
   
 } // end interface TextRenderer