From 1cf199af05f8df418fd883e9843b6a6455654994 Mon Sep 17 00:00:00 2001 From: "Eric J. Bowersox" Date: Sun, 8 Jun 2003 03:08:28 +0000 Subject: [PATCH] more javadocs, bugfixes to dictionary code --- .../dynamo/dict/DatabaseDictionary.java | 2 +- .../dynamo/dict/ResourceDictionary.java | 2 +- .../dynamo/event/ScriptEngineStartEvent.java | 38 ++++++++++++++- .../event/ScriptEngineStartListener.java | 16 ++++++- .../silverwrist/dynamo/iface/BrowserData.java | 45 ++++++++++++++++- .../dynamo/iface/BrowserDataProvider.java | 14 +++++- .../dynamo/iface/ChainParameterInput.java | 24 ++++++++++ .../dynamo/iface/RenderImmediate.java | 19 +++++++- .../dynamo/iface/RendererRegistration.java | 32 ++++++++++++- .../iface/ScriptEngineRegisterObject.java | 19 +++++++- .../dynamo/iface/ScriptExecute.java | 48 +++++++++++++++++++ .../silverwrist/dynamo/iface/URLRewriter.java | 27 +++++++++++ 12 files changed, 276 insertions(+), 10 deletions(-) diff --git a/src/dynamo-framework/com/silverwrist/dynamo/dict/DatabaseDictionary.java b/src/dynamo-framework/com/silverwrist/dynamo/dict/DatabaseDictionary.java index dbd1125..206b2bd 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/dict/DatabaseDictionary.java +++ b/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"); diff --git a/src/dynamo-framework/com/silverwrist/dynamo/dict/ResourceDictionary.java b/src/dynamo-framework/com/silverwrist/dynamo/dict/ResourceDictionary.java index eec5e08..862f3f8 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/dict/ResourceDictionary.java +++ b/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"); diff --git a/src/dynamo-framework/com/silverwrist/dynamo/event/ScriptEngineStartEvent.java b/src/dynamo-framework/com/silverwrist/dynamo/event/ScriptEngineStartEvent.java index 17a4f5f..09f1935 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/event/ScriptEngineStartEvent.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/event/ScriptEngineStartEvent.java @@ -11,7 +11,7 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * 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 <erbo@silcom.com> + * @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 ScriptEngineStartEvent. + * + * @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 toString 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 ScriptEngineRegisterObject for the new script engine. + */ public ScriptEngineRegisterObject getRegistrar() { return m_registrar; diff --git a/src/dynamo-framework/com/silverwrist/dynamo/event/ScriptEngineStartListener.java b/src/dynamo-framework/com/silverwrist/dynamo/event/ScriptEngineStartListener.java index febf1ab..dd3ab77 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/event/ScriptEngineStartListener.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/event/ScriptEngineStartListener.java @@ -11,14 +11,28 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * 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 <erbo@silcom.com> + * @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 diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/BrowserData.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/BrowserData.java index 803e9e1..6d777a8 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/BrowserData.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/BrowserData.java @@ -11,7 +11,7 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * 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 <erbo@silcom.com> + * @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 diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/BrowserDataProvider.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/BrowserDataProvider.java index 11e7acb..9b70bbf 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/BrowserDataProvider.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/BrowserDataProvider.java @@ -11,14 +11,26 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * 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 <erbo@silcom.com> + * @version X + */ public interface BrowserDataProvider { + /** + * Returns the {@link com.silverwrist.dynamo.iface.BrowserData BrowserData} corresponding to the user's browser. + * + * @return The BrowserData corresponding to the user's browser. + */ public BrowserData getBrowserData(); } // end interface BrowserDataProvider diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/ChainParameterInput.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/ChainParameterInput.java index 14c63b6..c847000 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/ChainParameterInput.java +++ b/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. + *

N.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 <erbo@silcom.com> + * @version X + */ public interface ChainParameterInput { + /** + * Returns a java.util.Collection containing all names of external request parameters. + * Request parameters used internally by Dynamo itself will not 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 null. + * + * @param name The name of the parameter to retrieve. + * @return The parameter's value, or null if the parameter did not exist. + */ public Object getChainParameter(String name); } // end interface ChainParameterInput diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/RenderImmediate.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/RenderImmediate.java index 9219cbd..5e7e998 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/RenderImmediate.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/RenderImmediate.java @@ -11,7 +11,7 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * 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 <erbo@silcom.com> + * @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 diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/RendererRegistration.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/RendererRegistration.java index 1442239..81ca065 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/RendererRegistration.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/RendererRegistration.java @@ -11,7 +11,7 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * 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 dynamic classes (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 <erbo@silcom.com> + * @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 diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/ScriptEngineRegisterObject.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/ScriptEngineRegisterObject.java index 068fecb..06957d0 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/ScriptEngineRegisterObject.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/ScriptEngineRegisterObject.java @@ -11,14 +11,31 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * 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 bsf.lookupBean() script function (or equivalent + * in the scripting language).

+ * 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 <erbo@silcom.com> + * @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 diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/ScriptExecute.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/ScriptExecute.java index 42d9406..ac7405c 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/ScriptExecute.java +++ b/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}.

+ * Scripts return values by calling the dynamo.scriptReturn() or dynamo.scriptOutput() + * functions (or their equivalents in whatever scripting language). These values are returned by the various + * methods of this interface. + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @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 diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/URLRewriter.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/URLRewriter.java index 570a36f..7019a57 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/URLRewriter.java +++ b/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 dynamo.xml + * 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 <erbo@silcom.com> + * @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