additional javadocs, and improved the javadoc generation rule in the build file
This commit is contained in:
Eric J. Bowersox
parent
1cf199af05
commit
e164b7d06f
|
|
@ -444,8 +444,13 @@
|
|||
<group title="Low-Level Dynamo Framework" packages="com.silverwrist.dynamo:com.silverwrist.dynamo.*"/>
|
||||
<group title="Mid-Level Venice Classes" packages="com.silverwrist.venice:com.silverwrist.venice.*"/>
|
||||
<link href="http://java.sun.com/j2se/1.4.1/docs/api/"/>
|
||||
<link href="http://java.sun.com/j2ee/sdk_1.3/techdocs/api/"/>
|
||||
<link href="http://java.sun.com/products/javabeans/glasgow/javadocs/"/>
|
||||
<link href="http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/"/>
|
||||
<link href="http://jakarta.apache.org/commons/collections/api/"/>
|
||||
<link href="http://jakarta.apache.org/commons/lang/api/"/>
|
||||
<link href="http://jakarta.apache.org/log4j/docs/api/"/>
|
||||
<link href="http://jakarta.apache.org/velocity/api/"/>
|
||||
</javadoc>
|
||||
</target>
|
||||
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ import java.util.Collection;
|
|||
public interface ChainParameterInput
|
||||
{
|
||||
/**
|
||||
* Returns a <CODE>java.util.Collection</CODE> containing all names of external request parameters.
|
||||
* Returns a {@link java.util.Collection Collection} containing all names of external request parameters.
|
||||
* Request parameters used internally by Dynamo itself will <EM>not</EM> be included in this list.
|
||||
*
|
||||
* @return The collection of parameter names.
|
||||
|
|
|
|||
|
|
@ -21,8 +21,8 @@ import java.util.Collection;
|
|||
|
||||
/**
|
||||
* A request service which provides access to "application attributes" managed by the servlet container
|
||||
* itself (through <CODE>ServletContext</CODE>) and not by Dynamo. This will often be needed, for instance,
|
||||
* 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.
|
||||
* <P><B>N.B.:</B> Dynamo itself requires several application-level attributes to manage its current state
|
||||
* (such as the {@link com.silverwrist.dynamo.app.ApplicationContainer ApplicationContainer} object). This
|
||||
* service will not permit access to those reserved application-level attributes.
|
||||
|
|
@ -33,7 +33,7 @@ import java.util.Collection;
|
|||
public interface ExternalAppAttributes
|
||||
{
|
||||
/**
|
||||
* Returns a <CODE>java.util.Collection</CODE> containing all names of external application attributes.
|
||||
* Returns a {@link java.util.Collection Collection} containing all names of external application attributes.
|
||||
* Application attributes used internally by Dynamo itself will <EM>not</EM> be included in this list.
|
||||
*
|
||||
* @return The collection of attribute names.
|
||||
|
|
|
|||
|
|
@ -21,8 +21,8 @@ import java.util.Collection;
|
|||
|
||||
/**
|
||||
* A request service which provides access to "session attributes" managed by the servlet container
|
||||
* itself (through <CODE>HttpSession</CODE>) and not by Dynamo. This will often be needed, for instance,
|
||||
* 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.
|
||||
* <P><B>N.B.:</B> Dynamo itself requires several session-level attributes to manage its current state
|
||||
* (such as the current {@link com.silverwrist.dynamo.iface.SessionInfo SessionInfo} object). This
|
||||
* service will not permit access to those reserved session-level attributes.
|
||||
|
|
@ -33,7 +33,7 @@ import java.util.Collection;
|
|||
public interface ExternalSessionAttributes
|
||||
{
|
||||
/**
|
||||
* Returns a <CODE>java.util.Collection</CODE> containing all names of external session attributes.
|
||||
* Returns a {@link java.util.Collection Collection} containing all names of external session attributes.
|
||||
* Session attributes used internally by Dynamo itself will <EM>not</EM> be included in this list.
|
||||
*
|
||||
* @return The collection of attribute names.
|
||||
|
|
|
|||
|
|
@ -19,22 +19,77 @@ package com.silverwrist.dynamo.iface;
|
|||
|
||||
import java.io.Reader;
|
||||
|
||||
/**
|
||||
* The public interface of the HTML Checker. It is used to preprocess text which comes from the user which may have
|
||||
* embedded HTML; it rejects HTML considered too dangerous, balances unclosed HTML tags, and can perform other actions
|
||||
* as well (such as checking spelling).
|
||||
* <P>The original HTML Checker was an ASP component created for Durand's CommunityWare in 1998. A workalike version
|
||||
* was written in Java, by Eric J. Bowersox, for a possible Java-based CommunityWare workalike; this code was
|
||||
* completely rewritten in 2001, using a new design, for the initial versions of Venice, and has been rewritten yet
|
||||
* again for Venice/Dynamo.
|
||||
*
|
||||
* @author Eric J. Bowersox <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
|
||||
|
|
|
|||
|
|
@ -17,8 +17,25 @@
|
|||
*/
|
||||
package com.silverwrist.dynamo.iface;
|
||||
|
||||
/**
|
||||
* An initialization service which is used to register new
|
||||
* {@link com.silverwrist.dynamo.iface.HTMLCheckerConfigurator HTMLCheckerConfigurator} objects to be called for
|
||||
* new HTML Checker profiles.
|
||||
*
|
||||
* @author Eric J. Bowersox <erbo@silcom.com>
|
||||
* @version X
|
||||
*/
|
||||
public interface HTMLCheckerConfigRegister
|
||||
{
|
||||
/**
|
||||
* Registers a new {@link com.silverwrist.dynamo.iface.HTMLCheckerConfigurator HTMLCheckerConfigurator} object to
|
||||
* be called on each new profile.
|
||||
*
|
||||
* @param cfg The <CODE>HTMLCheckerConfigurator</CODE> to register.
|
||||
* @return An instance of {@link com.silverwrist.dynamo.iface.ComponentShutdown ComponentShutdown}; this instance's
|
||||
* {@link com.silverwrist.dynamo.iface.ComponentShutdown#shutdown() shutdown()} method may be called to
|
||||
* unregister the <CODE>HTMLCheckerConfigurator</CODE>.
|
||||
*/
|
||||
public ComponentShutdown registerConfigurator(HTMLCheckerConfigurator cfg);
|
||||
|
||||
} // end interface HTMLCheckerConfigRegister
|
||||
|
|
|
|||
|
|
@ -17,8 +17,23 @@
|
|||
*/
|
||||
package com.silverwrist.dynamo.iface;
|
||||
|
||||
/**
|
||||
* An object which is used to configure new HTML Checker profiles after they're loaded from the database. When a
|
||||
* profile is loaded, its basic properties are loaded from the database, then all registered
|
||||
* <CODE>HTMLCheckerConfigurator</CODE> objects are called on the new profile; the objects can then read the
|
||||
* configuration properties and insert code objects into the profile as necessary.
|
||||
*
|
||||
* @author Eric J. Bowersox <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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -17,12 +17,42 @@
|
|||
*/
|
||||
package com.silverwrist.dynamo.iface;
|
||||
|
||||
/**
|
||||
* An interface implemented by HTML Checker <EM>output filters</EM>, which process all characters prior to their being
|
||||
* placed in the output buffer.
|
||||
*
|
||||
* @author Eric J. Bowersox <erbo@silcom.com>
|
||||
* @version X
|
||||
*/
|
||||
public interface HTMLOutputFilter
|
||||
{
|
||||
/**
|
||||
* Checks and possibly outputs a character. If the character <EM>ch</EM> is handled by this filter, it appends
|
||||
* the encoded equivalent to the string buffer <EM>buf</EM> and returns <CODE>true</CODE>. If not, it returns
|
||||
* <CODE>false</CODE> and leaves the buffer alone.
|
||||
*
|
||||
* @param buf The string buffer to append the character equivalent to.
|
||||
* @param ch The character to be checked and possibly output.
|
||||
* @return <CODE>true</CODE> if the character matches and was output, <CODE>false</CODE> if not.
|
||||
*/
|
||||
public boolean tryOutputCharacter(StringBuffer buf, char ch);
|
||||
|
||||
/**
|
||||
* Returns <CODE>true</CODE> if the character <EM>ch</EM> is handled by this filter, <CODE>false</CODE> if not.
|
||||
*
|
||||
* @param ch The character to be tested.
|
||||
* @return <CODE>true</CODE> if the character <EM>ch</EM> is handled by this filter, <CODE>false</CODE> if not.
|
||||
*/
|
||||
public boolean matchCharacter(char ch);
|
||||
|
||||
/**
|
||||
* Given a character string, returns the total number of characters in that string, starting from the beginning,
|
||||
* that are <I>not</I> handled by this filter before one that <I>is</I> appears. If none of the characters in this
|
||||
* string are handled by the filter, the length of the string is returned.
|
||||
*
|
||||
* @param s The string to scan through.
|
||||
* @return The length of the initial sequence of non-matching characters in this string.
|
||||
*/
|
||||
public int lengthNoMatch(String s);
|
||||
|
||||
} // end interface HTMLOutputFilter
|
||||
|
|
|
|||
|
|
@ -20,10 +20,36 @@ package com.silverwrist.dynamo.iface;
|
|||
import com.silverwrist.dynamo.htmlcheck.MarkupData;
|
||||
import com.silverwrist.dynamo.util.QualifiedNameKey;
|
||||
|
||||
/**
|
||||
* An interface implemented by HTML Checker <EM>rewriters</EM>, which rewrite specific sequences of text in the HTML
|
||||
* Checker's input.
|
||||
*
|
||||
* @author Eric J. Bowersox <erbo@silcom.com>
|
||||
* @version X
|
||||
*/
|
||||
public interface HTMLRewriter
|
||||
{
|
||||
/**
|
||||
* Returns the name of this rewriter. If this returns a value other than <CODE>null</CODE>, the HTML Checker will
|
||||
* create a counter with this name, which will count the number of times the rewriter chooses to rewrite the text.
|
||||
*
|
||||
* @return The namespace and name of this rewriter as a
|
||||
* {@link com.silverwrist.dynamo.util.QualifiedNameKey QualifiedNameKey}, or <CODE>null</CODE>.
|
||||
*/
|
||||
public QualifiedNameKey getName();
|
||||
|
||||
/**
|
||||
* Determines whether to rewrite the specified text, and rewrites it if necessary. The
|
||||
* {@link com.silverwrist.dynamo.htmlcheck.MarkupData MarkupData} object provides for beginning and ending markup
|
||||
* and text surrounding the text in question.
|
||||
*
|
||||
* @param data The text to be checked and possibly rewritten.
|
||||
* @param prefix A string to be used as a prefix for the result; may be <CODE>null</CODE>.
|
||||
* @param suffix A string to be used as a suffix for the result; may be <CODE>null</CODE>.
|
||||
* @param site Provides an interface for the rewriter to interact with the HTML Checker's context and attributes.
|
||||
* @return <CODE>null</CODE> if the text should not be rewritten, or a
|
||||
* {@link com.silverwrist.dynamo.htmlcheck.MarkupData MarkupData} object containing the rewritten text.
|
||||
*/
|
||||
public MarkupData rewrite(String data, String prefix, String suffix, HTMLRewriterSite site);
|
||||
|
||||
} // end interface HTMLRewriter
|
||||
|
|
|
|||
|
|
@ -17,8 +17,22 @@
|
|||
*/
|
||||
package com.silverwrist.dynamo.iface;
|
||||
|
||||
/**
|
||||
* An interface supplying services to an instance of {@link com.silverwrist.dynamo.iface.HTMLRewriter HTMLRewriter}.
|
||||
* It allows the rewriter to examine the context and configuration attributes of the HTML Checker.
|
||||
*
|
||||
* @author Eric J. Bowersox <erbo@silcom.com>
|
||||
* @version X
|
||||
*/
|
||||
public interface HTMLRewriterSite extends ObjectProvider
|
||||
{
|
||||
/**
|
||||
* Returns a configuration attribute of the HTML Checker.
|
||||
*
|
||||
* @param namespace Namespace URI of the configuration attribute to return.
|
||||
* @param name Name of the configuration attribute to return.
|
||||
* @return The configuration attribute value, or <CODE>null</CODE> if the configuration attribute did not exist.
|
||||
*/
|
||||
public String getAttribute(String namespace, String name);
|
||||
|
||||
} // end interface HTMLRewriterSite
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user