diff --git a/build.xml b/build.xml index afb8994..0f697d0 100644 --- a/build.xml +++ b/build.xml @@ -444,8 +444,13 @@ + + + + + diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/ChainParameterInput.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/ChainParameterInput.java index c847000..cd58bdc 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/ChainParameterInput.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/ChainParameterInput.java @@ -33,7 +33,7 @@ import java.util.Collection; public interface ChainParameterInput { /** - * Returns a java.util.Collection 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 not be included in this list. * * @return The collection of parameter names. diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/ExternalAppAttributes.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/ExternalAppAttributes.java index c81b0f0..a425a13 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/ExternalAppAttributes.java +++ b/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 ServletContext) and not by Dynamo. This will often be needed, for instance, - * to interface with servlet-based APIs outside the scope of Dynamo. + * itself (through {@link javax.servlet.ServletContext ServletContext}) and not by 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 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 java.util.Collection 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 not be included in this list. * * @return The collection of attribute names. diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/ExternalSessionAttributes.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/ExternalSessionAttributes.java index e11afcb..32b7f13 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/ExternalSessionAttributes.java +++ b/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 HttpSession) and not by Dynamo. This will often be needed, for instance, - * to interface with servlet-based APIs outside the scope of Dynamo. + * itself (through {@link javax.servlet.http.HttpSession HttpSession}) and not by 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 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 java.util.Collection 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 not be included in this list. * * @return The collection of attribute names. diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLChecker.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLChecker.java index bc5d9bb..b888c24 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLChecker.java +++ b/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). + *

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 <erbo@silcom.com> + * @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 diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLCheckerConfigRegister.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLCheckerConfigRegister.java index 8cb039b..350f0d0 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLCheckerConfigRegister.java +++ b/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 HTMLCheckerConfigurator 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 HTMLCheckerConfigurator. + */ public ComponentShutdown registerConfigurator(HTMLCheckerConfigurator cfg); } // end interface HTMLCheckerConfigRegister diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLCheckerConfigurator.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLCheckerConfigurator.java index 75bd0b0..490dc8e 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLCheckerConfigurator.java +++ b/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 + * HTMLCheckerConfigurator 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 <erbo@silcom.com> + * @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 diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLCheckerProfile.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLCheckerProfile.java index ce9afda..724a27b 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLCheckerProfile.java +++ b/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 diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLCheckerService.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLCheckerService.java index b8af40d..aff823e 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLCheckerService.java +++ b/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 diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLOutputFilter.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLOutputFilter.java index 4e2e131..10b5755 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLOutputFilter.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLOutputFilter.java @@ -17,12 +17,42 @@ */ package com.silverwrist.dynamo.iface; +/** + * An interface implemented by HTML Checker output filters, which process all characters prior to their being + * placed in the output buffer. + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @version X + */ public interface HTMLOutputFilter { + /** + * Checks and possibly outputs a character. If the character ch is handled by this filter, it appends + * the encoded equivalent to the string buffer buf and returns true. If not, it returns + * false 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 true if the character matches and was output, false if not. + */ public boolean tryOutputCharacter(StringBuffer buf, char ch); + /** + * Returns true if the character ch is handled by this filter, false if not. + * + * @param ch The character to be tested. + * @return true if the character ch is handled by this filter, false 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 not handled by this filter before one that is 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 diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLRewriter.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLRewriter.java index 317ec49..e007b29 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLRewriter.java +++ b/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 rewriters, which rewrite specific sequences of text in the HTML + * Checker's input. + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @version X + */ public interface HTMLRewriter { + /** + * Returns the name of this rewriter. If this returns a value other than null, 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 null. + */ 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 null. + * @param suffix A string to be used as a suffix for the result; may be null. + * @param site Provides an interface for the rewriter to interact with the HTML Checker's context and attributes. + * @return null 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 diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLRewriterSite.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLRewriterSite.java index 75d1cac..e4452c1 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/HTMLRewriterSite.java +++ b/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 null if the configuration attribute did not exist. + */ public String getAttribute(String namespace, String name); } // end interface HTMLRewriterSite