more javadocs, bugfixes to dictionary code

src/dynamo-framework/com/silverwrist/dynamo/dict/DatabaseDictionary.java

@@ -92,7 +92,7 @@ public class DatabaseDictionary
     String conn_name = null;
     try
     { // verify the right node name
-      loader.verifyNodeName(config_root,"object");
+      loader.verifyNodeName(config_root,"dictionary");
 
       // get the object's name
       m_name = loader.getAttribute(config_root,"name");

src/dynamo-framework/com/silverwrist/dynamo/dict/ResourceDictionary.java

@@ -215,7 +215,7 @@ public class ResourceDictionary implements NamedObject, ComponentInitialize, Com
     String resource_name = null;
     try
     { // verify the right node name
-      loader.verifyNodeName(config_root,"object");
+      loader.verifyNodeName(config_root,"dictionary");
 
       // get the object's name
       m_name = loader.getAttribute(config_root,"name");

src/dynamo-framework/com/silverwrist/dynamo/event/ScriptEngineStartEvent.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,6 +20,16 @@ package com.silverwrist.dynamo.event;
 import com.silverwrist.dynamo.iface.Request;
 import com.silverwrist.dynamo.iface.ScriptEngineRegisterObject;
 
+/**
+ * An event which is posted to all registered
+ * {@link com.silverwrist.dynamo.event.ScriptEngineStartListener ScriptEngineStartListener} objects when a new
+ * instance of a script engine is started.  It passes along an instance of
+ * {@link com.silverwrist.dynamo.iface.ScriptEngineRegisterObject ScriptEngineRegisterObject} so that new
+ * objects can be registered with the new script engine.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public class ScriptEngineStartEvent extends DynamoEventObject
 {
   /*--------------------------------------------------------------------------------
@@ -27,13 +37,20 @@ public class ScriptEngineStartEvent extends DynamoEventObject
    *--------------------------------------------------------------------------------
    */
 
-  private transient ScriptEngineRegisterObject m_registrar;
+  private transient ScriptEngineRegisterObject m_registrar;  // allows registering new objects
 
   /*--------------------------------------------------------------------------------
    * Constructor
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Constructs a new <CODE>ScriptEngineStartEvent</CODE>.
+   *
+   * @param request The current request.
+   * @param registrar The script engine's
+   *        {@link com.silverwrist.dynamo.iface.ScriptEngineRegisterObject ScriptEngineRegisterObject} interface.
+   */
   public ScriptEngineStartEvent(Request request, ScriptEngineRegisterObject registrar)
   {
     super(request);
@@ -46,6 +63,12 @@ public class ScriptEngineStartEvent extends DynamoEventObject
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Returns a string representation of the object. In general, the <CODE>toString</CODE> method returns a string
+   * that "textually represents" this object. 
+   *
+   * @return A string representation of the object.
+   */
   public String toString()
   {
     return "ScriptEngineStartEvent: request = " + source + ", registrar = " + m_registrar;
@@ -57,12 +80,23 @@ public class ScriptEngineStartEvent extends DynamoEventObject
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Returns the current {@link com.silverwrist.dynamo.iface.Request Request} associated with the event.
+   *
+   * @return The current request associated with the event.
+   */
   public Request getRequest()
   {
     return (Request)getSource();
 
   } // end getRequest
 
+  /**
+   * Returns the instance of {@link com.silverwrist.dynamo.iface.ScriptEngineRegisterObject ScriptEngineRegisterObject}
+   * associated with the script engine that's currently starting up.
+   *
+   * @return The instance of <CODE>ScriptEngineRegisterObject</CODE> for the new script engine.
+   */
   public ScriptEngineRegisterObject getRegistrar()
   {
     return m_registrar;

src/dynamo-framework/com/silverwrist/dynamo/event/ScriptEngineStartListener.java

@@ -11,14 +11,28 @@
  * 
  * 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.event;
 
+/**
+ * A listener interface which is registered to receive
+ * {@link com.silverwrist.dynamo.event.ScriptEngineStartEvent ScriptEngineStartEvent} objects.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ * @see com.silverwrist.dynamo.iface.ScriptEngineConfig#addStartListener(com.silverwrist.dynamo.event.ScriptEngineStartListener)
+ */
 public interface ScriptEngineStartListener extends DynamoEventListener
 {
+  /**
+   * Called when a new script engine instance is started.
+   *
+   * @param event The {@link com.silverwrist.dynamo.event.ScriptEngineStartEvent ScriptEngineStartEvent} posted by the
+   *              script engine when it starts.
+   */
   public void scriptEngineStarting(ScriptEngineStartEvent event);
 
 } // end interface ScriptEngineStartListener

src/dynamo-framework/com/silverwrist/dynamo/iface/BrowserData.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,24 +19,67 @@ package com.silverwrist.dynamo.iface;
 
 import java.util.Set;
 
+/**
+ * The detected information about the user's browser, based on the "User-agent" string it sends.  This information
+ * is looked up in an internal database and formatted in a convenient manner for use by scripting or other code.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface BrowserData
 {
+  /**
+   * Browser attribute key for the name of the browser.
+   */
   public static final String KEY_BROWSER_NAME = "Browser";
 
+  /**
+   * Browser attribute key for the version number of the browser.
+   */
   public static final String KEY_VERSION = "Version";
 
+  /**
+   * Browser attribute key for the major version number of the browser.
+   */
   public static final String KEY_MAJOR_VERSION = "MajorVer";
 
+  /**
+   * Browser attribute key for the minor version number of the browser.
+   */
   public static final String KEY_MINOR_VERSION = "MinorVer";
 
+  /**
+   * Browser attribute key for the platform on which the browser is running.
+   */
   public static final String KEY_PLATFORM = "Platform";
 
+  /**
+   * Browser attribute key for the version number of the Common Language Runtime underlying the browser.  (Only
+   * applicable for instances of Microsoft Internet Explorer running on a CLR-supported platform such as Windows.)
+   */
   public static final String KEY_CLR_VERSION = "CLR_Version";
 
+  /**
+   * Returns the User-agent string supplied by the browser.
+   *
+   * @return The User-agent string supplied by the browser.
+   */
   public String getUserAgent();
 
+  /**
+   * Returns a defined attribute of the browser.
+   *
+   * @param key The name of the attribute to be returned.
+   * @return The specified attribute.
+   */
   public String getBrowserAttribute(String key);
 
+  /**
+   * Returns a {@link java.util.Set Set} of flags for the browser.  Each flag is a
+   * {@link com.silverwrist.dynamo.BrowserFlag BrowserFlag} object.
+   *
+   * @return The set of flags for the current browser.
+   */
   public Set getBrowserFlags();
 
 } // end interface BrowserData

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

@@ -11,14 +11,26 @@
  * 
  * 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 request service which gets the {@link com.silverwrist.dynamo.iface.BrowserData BrowserData} corresponding to the
+ * user's browser.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface BrowserDataProvider
 {
+  /**
+   * Returns the {@link com.silverwrist.dynamo.iface.BrowserData BrowserData} corresponding to the user's browser.
+   *
+   * @return The <CODE>BrowserData</CODE> corresponding to the user's browser.
+   */
   public BrowserData getBrowserData();
 
 } // end interface BrowserDataProvider

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

@@ -19,10 +19,34 @@ package com.silverwrist.dynamo.iface;
 
 import java.util.Collection;
 
+/**
+ * A request service interface which allows access to parameters passed to the request through the
+ * {@link javax.servlet.ServletRequest ServletRequest} object, and not via Dynamo.  This will often be needed, for
+ * instance, to interface with servlet-based APIs outside the scope of Dynamo.
+ * <P><B>N.B.:</B> Dynamo itself requires several request-level parameters to manage its current state
+ * (such as the {@link com.silverwrist.dynamo.iface.Request Request} object).  This service will not permit access
+ * to those reserved request-level parameters.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface ChainParameterInput
 {
+  /**
+   * Returns a <CODE>java.util.Collection</CODE> 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.
+   */
   public Collection getChainParameterNames();
 
+  /**
+   * Returns the value of an external request parameter.  Attempts to get the value of a request parameter used
+   * internally by Dynamo itself will return <CODE>null</CODE>.
+   *
+   * @param name The name of the parameter to retrieve.
+   * @return The parameter's value, or <CODE>null</CODE> if the parameter did not exist.
+   */
   public Object getChainParameter(String name);
 
 } // end interface ChainParameterInput

src/dynamo-framework/com/silverwrist/dynamo/iface/RenderImmediate.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,25 @@ package com.silverwrist.dynamo.iface;
 import java.io.IOException;
 import com.silverwrist.dynamo.except.RenderingException;
 
+/**
+ * A service interface which is used to render an object's text to an intermediate buffer and return its
+ * text representation as a string.  The object must have a registered
+ * {@link com.silverwrist.dynamo.iface.TextRenderer TextRenderer} for its class, or be otherwise renderable in text
+ * format.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface RenderImmediate
 {
+  /**
+   * Renders the specified object and returns its text equivalent.
+   *
+   * @param obj The object to be rendered.
+   * @return The text that results from rendering the object.
+   * @exception java.io.IOException If there's an I/O error rendering the object.
+   * @exception com.silverwrist.dynamo.except.RenderingException If there was another problem rendering the object.
+   */
   public String renderTextObject(Object obj) throws IOException, RenderingException;
 
 } // end interface RenderImmediate

src/dynamo-framework/com/silverwrist/dynamo/iface/RendererRegistration.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,40 @@ package com.silverwrist.dynamo.iface;
 
 import com.silverwrist.dynamo.except.ConfigException;
 
+/**
+ * An initialization service which allows renderers to be registered for specific object classes.  Renderers may be
+ * registered for either normal Java classes or <EM>dynamic classes</EM> (specified by a
+ * {@link com.silverwrist.dynamo.iface.DynamicClass DynamicClass} object).  This renderer will also be used for all
+ * derived classes of the object class for which it is registered, unless a more-specific registration is made for a
+ * class at a lower level.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface RendererRegistration
 {
+  /**
+   * Register a renderer for a Java class.
+   *
+   * @param klass The Java class to register the renderer for.
+   * @param renderer The renderer to be registered for this class.
+   * @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 this renderer.
+   * @exception com.silverwrist.dynamo.except.ConfigException If the renderer could not be registered.
+   */
   public ComponentShutdown registerRenderer(Class klass, Renderer renderer) throws ConfigException;
 
+  /**
+   * Register a renderer for a dynamic class.
+   *
+   * @param dclass The dynamic class to register the renderer for.
+   * @param renderer The renderer to be registered for this dynamic class.
+   * @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 this renderer.
+   * @exception com.silverwrist.dynamo.except.ConfigException If the renderer could not be registered.
+   */
   public ComponentShutdown registerRenderer(DynamicClass dclass, Renderer renderer) throws ConfigException;
   
 } // end interface RendererRegistration

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

@@ -11,14 +11,31 @@
  * 
  * 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 initialization service which allows objects to be registered with a newly-created scripting engine.  Objects
+ * registered via this service may be retrieved via the <CODE>bsf.lookupBean()</CODE> script function (or equivalent
+ * in the scripting language).<P>
+ * This interface is passed as part of the
+ * {@link com.silverwrist.dynamo.event.ScriptEngineStartEvent ScriptEngineStartEvent} object, where it may be retrieved
+ * by an event listener.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface ScriptEngineRegisterObject
 {
+  /**
+   * Registers a new object with the scripting engine.
+   *
+   * @param name Name that this object is to be accessible under.
+   * @param obj The object to be registered.
+   */
   public void registerObject(String name, Object obj);
 
 } // end interface ScriptEngineRegisterObject

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

@@ -20,17 +20,65 @@ package com.silverwrist.dynamo.iface;
 import java.io.InputStream;
 import com.silverwrist.dynamo.except.ScriptingException;
 
+/**
+ * The runtime service through which scripts are executed.  Scripts may be loaded from the system
+ * {@link com.silverwrist.dynamo.iface.ResourceProvider ResourceProvider}, or through some other means.
+ * They are always executed in the context of a {@link com.silverwrist.dynamo.iface.Request Request}.<P>
+ * Scripts return values by calling the <CODE>dynamo.scriptReturn()</CODE> or <CODE>dynamo.scriptOutput()</CODE>
+ * functions (or their equivalents in whatever scripting language).  These values are returned by the various
+ * methods of this interface.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface ScriptExecute
 {
+  /**
+   * Execute a script contained in a string.
+   *
+   * @param request The request context this script is executed under.
+   * @param language The scripting language the script is written in.
+   * @param source_name The name of the script source.
+   * @param code The script code.
+   * @return The return value from the script.
+   * @exception com.silverwrist.dynamo.except.ScriptingException If there was an error parsing or executing the script.
+   */
   public Object executeScript(Request request, String language, String source_name, String code)
       throws ScriptingException;
 
+  /**
+   * Execute a script loaded from an external source.
+   *
+   * @param request The request context this script is executed under.
+   * @param language The scripting language the script is written in.
+   * @param source_name The name of the script source.
+   * @param code A stream from which the script code is loaded.
+   * @return The return value from the script.
+   * @exception com.silverwrist.dynamo.except.ScriptingException If there was an error parsing or executing the script.
+   */
   public Object executeScript(Request request, String language, String source_name, InputStream code)
       throws ScriptingException;
 
+  /**
+   * Execute a script loaded from the resources.
+   *
+   * @param request The request context this script is executed under.
+   * @param language The scripting language the script is written in.
+   * @param resource_name The name of the resource to load and execute.
+   * @return The return value from the script.
+   * @exception com.silverwrist.dynamo.except.ScriptingException If there was an error parsing or executing the script.
+   */
   public Object executeScript(Request request, String language, String resource_name)
       throws ScriptingException;
 
+  /**
+   * Execute a script loaded from the resources.  The language of the script is inferred from the resource name.
+   *
+   * @param request The request context this script is executed under.
+   * @param resource_name The name of the resource to load and execute.
+   * @return The return value from the script.
+   * @exception com.silverwrist.dynamo.except.ScriptingException If there was an error parsing or executing the script.
+   */
   public Object executeScript(Request request, String resource_name) throws ScriptingException;
 
 } // end interface ScriptExecute

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

@@ -19,12 +19,39 @@ package com.silverwrist.dynamo.iface;
 
 import java.util.List;
 
+/**
+ * A service interface which rewrites URLs for output.  The URL types are defined in the <CODE>dynamo.xml</CODE>
+ * configuration file, which specifies a replacement template for the URL data, and also whether to "encode" the URL
+ * with the session ID information (assuming cookies are not supported).
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface URLRewriter
 {
+  /**
+   * Rewrite the specified URL for inclusion in an HTML page.
+   *
+   * @param type The URL type to use when rewriting the URL.
+   * @param url The input URL data.
+   * @return The formatted URL.
+   */
   public String rewriteURL(String type, String url);
 
+  /**
+   * Rewrite the specified URL for use in a redirection.
+   *
+   * @param type The URL type to use when rewriting the URL.
+   * @param url The input URL data.
+   * @return The formatted URL.
+   */
   public String rewriteRedirectURL(String type, String url);
 
+  /**
+   * Gets the list of allowed "type" values for URL rewriting.
+   *
+   * @return A list of strings, each of which is an allowed URL rewrite "type."
+   */
   public List getRewriteTypes();
 
 } // end interface URLRewriter