You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@velocity.apache.org by nb...@apache.org on 2008/04/30 07:48:46 UTC
svn commit: r652274 - in
/velocity/tools/trunk/src/main/java/org/apache/velocity/tools: config/ view/
Author: nbubna
Date: Tue Apr 29 22:48:45 2008
New Revision: 652274
URL: http://svn.apache.org/viewvc?rev=652274&view=rev
Log:
bunch of javadoc on configuration and whatnot
Modified:
velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/CompoundConfiguration.java
velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/Configuration.java
velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/Data.java
velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/FactoryConfiguration.java
velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/PropertiesFactoryConfiguration.java
velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/Property.java
velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/ToolConfiguration.java
velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/ToolboxConfiguration.java
velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/XmlFactoryConfiguration.java
velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/XmlFactoryConfigurationRuleSet.java
velocity/tools/trunk/src/main/java/org/apache/velocity/tools/view/VelocityView.java
Modified: velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/CompoundConfiguration.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/CompoundConfiguration.java?rev=652274&r1=652273&r2=652274&view=diff
==============================================================================
--- velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/CompoundConfiguration.java (original)
+++ velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/CompoundConfiguration.java Tue Apr 29 22:48:45 2008
@@ -24,7 +24,8 @@
import java.util.TreeSet;
/**
- *
+ * This class manages a {@link SortedSet} of child {@link Configuration}s
+ * as well as being a {@link Configuration} itself.
*
* @author Nathan Bubna
* @version $Id: Configuration.java 511959 2007-02-26 19:24:39Z nbubna $
Modified: velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/Configuration.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/Configuration.java?rev=652274&r1=652273&r2=652274&view=diff
==============================================================================
--- velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/Configuration.java (original)
+++ velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/Configuration.java Tue Apr 29 22:48:45 2008
@@ -26,7 +26,13 @@
import java.util.TreeSet;
/**
- *
+ * <p>This base configuration class manages a set of {@link Property}s
+ * for whatever thing the instance of this class represents. When
+ * combined with another {@link Configuration} instance via
+ * {@link #addConfiguration}, the {@link Property}s of both instances are
+ * combined.</p><p>NOTE: Though this class appears {@link Comparable},
+ * the {@link #compareTo} method is unsupported. Proper comparison is
+ * left up to subclasses.</p>
*
* @author Nathan Bubna
* @version $Id: Configuration.java 511959 2007-02-26 19:24:39Z nbubna $
Modified: velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/Data.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/Data.java?rev=652274&r1=652273&r2=652274&view=diff
==============================================================================
--- velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/Data.java (original)
+++ velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/Data.java Tue Apr 29 22:48:45 2008
@@ -30,7 +30,27 @@
import org.apache.velocity.tools.ConversionUtils;
/**
- *
+ * <p>This class represents configured data. If added to a
+ * {@link FactoryConfiguration}, its values will be made
+ * available in the application-scoped toolboxes
+ * produced by any ToolboxFactory configured using
+ * that configuration.</p>
+ * <p>This class also implements all the functionality of
+ * {@link Property}s, which may added to <strong>any</strong>
+ * {@link Configuration} subclass, including
+ * {@link ToolConfiguration}, {@link ToolboxConfiguration},
+ * and {@link FactoryConfiguration}. In other words,
+ * anything you can do in a {@link Data} configuration, you
+ * can do with a {@link Property}.</p>
+ * <p>Some features supported here are:
+ * <ul>
+ * <li>built in {@link Type}s for strings, booleans, numbers, fields
+ * and lists thereof</li>
+ * <li>auto-conversion of numbers, booleans and fields in data
+ * with no explicit type</li>
+ * <li>support for any Commons-BeanUtils {@link Converter} implementation</li>
+ * </ul>
+ * </p>
*
* @author Nathan Bubna
* @version $Id: Data.java 511959 2007-02-26 19:24:39Z nbubna $
Modified: velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/FactoryConfiguration.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/FactoryConfiguration.java?rev=652274&r1=652273&r2=652274&view=diff
==============================================================================
--- velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/FactoryConfiguration.java (original)
+++ velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/FactoryConfiguration.java Tue Apr 29 22:48:45 2008
@@ -27,8 +27,37 @@
import org.apache.velocity.tools.ToolboxFactory;
/**
- * //TODO: add ability to log all this stuff and/or
- * keep a running, ordered list of sources
+ * <p>This class serves to define configuration info for a {@link ToolboxFactory}.
+ * It contains the {@link ToolboxConfiguration}s for the factory as well
+ * as any {@link Data} which is to be made available in the application scope
+ * by the factory and any {@link Property}s which you intend to be available
+ * to <strong>all</strong> tools managed by the factory, regardless of
+ * toolbox or scope.
+ * </p><p>
+ * Most users will not find themselves directly using the API of this class,
+ * as its subclasses generally provide much simpler means of inputting
+ * the actual configuration info whether from XML, Java or a Properties files.
+ * </p><p>
+ * When combining any {@link Configuration}s via the various
+ * {@link #addConfiguration} methods in each class, it is
+ * <strong>essential</strong> to remember that subsequent configurations
+ * always override previous ones. This is a "last entry wins" approach
+ * to configuration!
+ * </p><p>
+ * For debugging, this class tracks its "sources", keeping a chronological list
+ * of all sources for configuration data. When you add configuration info
+ * to this class via {@link #addConfiguration}, the source lists from those
+ * {@link FactoryConfiguration}s is appended to this instance's list. The
+ * initial item in this list will typically be the name of the FactoryConfiguration
+ * class (or subclass) along with a caller-provided string identifying where
+ * this instance was created. This aids greatly in debugging combined, complex
+ * configurations. You may add further sources at any time via
+ * {@link #addSource}.
+ * </p><p>
+ * The {@link #toString()} method of this class provides a complete and
+ * well-formatted listing of the configuration info contained within this
+ * instance and is also very useful for debugging.
+ * </p>
*
* @author Nathan Bubna
* @version $Id: FactoryConfiguration.java 511959 2007-02-26 19:24:39Z nbubna $
Modified: velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/PropertiesFactoryConfiguration.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/PropertiesFactoryConfiguration.java?rev=652274&r1=652273&r2=652274&view=diff
==============================================================================
--- velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/PropertiesFactoryConfiguration.java (original)
+++ velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/PropertiesFactoryConfiguration.java Tue Apr 29 22:48:45 2008
@@ -26,8 +26,8 @@
import org.apache.commons.collections.ExtendedProperties;
/**
- * NOTE: "property", "data", and "toolbox" are essentially reserved words
- * do not use them as tool keys or toolbox scopes.
+ * <p> This reads in configuration info formatted as a property
+ * file using {@link ExtendedProperties} from Commons-Collections.</p>
* <p>This reads in a configuration such as:
* <code>
* tools.toolbox = request,application
@@ -47,7 +47,9 @@
* tools.data.version.type = number
* tools.data.debug = false
* tools.data.debug.type = boolean
- * </code></p>
+ * </code>
+ * <strong>NOTE</strong>: "property", "data", and "toolbox" are
+ * reserved words do not use them as tool keys or toolbox scopes.</p>
*
* @author Nathan Bubna
* @version $Id: PropertiesFactoryConfiguration.java 511959 2007-02-26 19:24:39Z nbubna $
Modified: velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/Property.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/Property.java?rev=652274&r1=652273&r2=652274&view=diff
==============================================================================
--- velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/Property.java (original)
+++ velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/Property.java Tue Apr 29 22:48:45 2008
@@ -21,7 +21,7 @@
/**
* Simple extension of {@link Data} that treats "name" as an alias
- * for "key".
+ * for "key". See {@link Data} for a description and feature list.
*
* @author Nathan Bubna
* @version $Id: Property.java 511959 2007-02-26 19:24:39Z nbubna $
Modified: velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/ToolConfiguration.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/ToolConfiguration.java?rev=652274&r1=652273&r2=652274&view=diff
==============================================================================
--- velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/ToolConfiguration.java (original)
+++ velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/ToolConfiguration.java Tue Apr 29 22:48:45 2008
@@ -25,7 +25,15 @@
import org.apache.velocity.tools.ClassUtils;
/**
- *
+ * <p>This class handles configuration info for tools, including their key,
+ * classname, path restriction, and properties. It also does fairly
+ * aggresive validation and is able to identify if the tool is "old"
+ * (i.e. designed for VelocityTools 1.x). Once configuration is
+ * complete, a {@link ToolInfo} instance can be created by calling
+ * {@link #createInfo}.</p>
+ * <p>
+ * Most users will not find themselves directly using the API of this class.
+ * </p>
*
* @author Nathan Bubna
* @version $Id: ToolConfiguration.java 511959 2007-02-26 19:24:39Z nbubna $
Modified: velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/ToolboxConfiguration.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/ToolboxConfiguration.java?rev=652274&r1=652273&r2=652274&view=diff
==============================================================================
--- velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/ToolboxConfiguration.java (original)
+++ velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/ToolboxConfiguration.java Tue Apr 29 22:48:45 2008
@@ -25,7 +25,19 @@
import org.apache.velocity.tools.ToolboxFactory;
/**
- *
+ * <p>This class handles configuration info for the Toolbox instances
+ * that will eventually be produced by {@link ToolboxFactory}.
+ * It contains {@link ToolConfiguration}s for tools which will be managed
+ * by those toolboxes, as well the toolboxes' scope and
+ * any other {@link Property}s which you intend to be available
+ * to all the tools in the toolbox.</p>
+ * <p>
+ * Most users will not find themselves directly using the API of this class.
+ * </p>
+ * <p>NOTE: Two instances of this class are considered equal() if their scopes
+ * are equal. This is not the intuitive behavior at this level but is done
+ * to facilitate intuitive behavior in the higher APIs, which are much more
+ * likely to be used directly.</p>
*
* @author Nathan Bubna
* @version $Id: ToolboxConfiguration.java 511959 2007-02-26 19:24:39Z nbubna $
Modified: velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/XmlFactoryConfiguration.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/XmlFactoryConfiguration.java?rev=652274&r1=652273&r2=652274&view=diff
==============================================================================
--- velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/XmlFactoryConfiguration.java (original)
+++ velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/XmlFactoryConfiguration.java Tue Apr 29 22:48:45 2008
@@ -26,7 +26,13 @@
import org.apache.commons.digester.RuleSet;
/**
- *
+ * <p>This reads in configuration info formatted as an XML file
+ * using Commons-{@link Digester}. This uses
+ * {@link XmlFactoryConfigurationRuleSet} as the default set of rules
+ * for processing the XML. However, you may always change this by
+ * passing a new {@link RuleSet} to the {@link #setRuleSet} method.
+ * See the configuration documentation on the main web site for
+ * instructions on the XML format supported by the default rules.</p>
*
* @author Nathan Bubna
* @version $Id: XmlFactoryConfiguration.java 511959 2007-02-26 19:24:39Z nbubna $
Modified: velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/XmlFactoryConfigurationRuleSet.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/XmlFactoryConfigurationRuleSet.java?rev=652274&r1=652273&r2=652274&view=diff
==============================================================================
--- velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/XmlFactoryConfigurationRuleSet.java (original)
+++ velocity/tools/trunk/src/main/java/org/apache/velocity/tools/config/XmlFactoryConfigurationRuleSet.java Tue Apr 29 22:48:45 2008
@@ -25,7 +25,31 @@
import org.xml.sax.Attributes;
/**
- *
+ * <p>This provides set of {@link Rule}s used by
+ * Commons-{@link Digester} to process configuration info
+ * formatted as XML. This is the default RuleSet used by
+ * {@link XmlFactoryConfiguration}.</p>
+ * <p>Here is a short example XML:
+ * <code>
+ * <tools>
+ * <data type="number" key="version" value="1.1"/>
+ * <data key="isConvertedProp" value="false" class="java.lang.Boolean" converter="org.apache.commons.beanutils.converters.BooleanConverter"/>
+ * <data type="boolean" key="isKnownType" value="true"/>
+ * <data key="isAutoType" value="true"/>
+ * <data key="foo" value="this is foo."/>
+ * <data key="bar">this is bar.</data>
+ * <toolbox scope="request" xhtml="true">
+ * <tool key="toytool" class="ToyTool" restrictTo="index.vm"/>
+ * </toolbox>
+ * <toolbox scope="session">
+ * <property name="createSession" value="true" type="boolean"/>
+ * <tool key="map" class="java.util.HashMap"/>
+ * </toolbox>
+ * <toolbox scope="application">
+ * <tool class="org.apache.velocity.tools.generic.DateTool"/>
+ * </toolbox>
+ * </tools>
+ * </code></p>
*
* @author Nathan Bubna
* @version $Id: XmlConfiguration.java 511959 2007-02-26 19:24:39Z nbubna $
@@ -57,26 +81,6 @@
this.propertyClass = clazz;
}
-/*
-<tools>
- <data type="number" key="version" value="1.1"/>
- <data key="isConvertedProp" value="false" class="java.lang.Boolean" converter="org.apache.commons.beanutils.converters.BooleanConverter"/>
- <data type="boolean" key="isSimple" value="true"/>
- <data key="foo" value="this is foo."/>
- <data key="bar">this is bar.</data>
- <toolbox scope="request" xhtml="true">
- <tool key="toytool" class="ToyTool" restrictTo="index.vm"/>
- </toolbox>
- <toolbox scope="session">
- <property name="create-session" value="true" type="boolean"/>
- <tool key="map" class="java.util.HashMap"/>
- </toolbox>
- <toolbox scope="application">
- <tool key="date" class="org.apache.velocity.tools.generic.DateTool"/>
- </toolbox>
-</tools>
-*/
-
/**
* <p>Add the set of Rule instances defined in this RuleSet to the
* specified <code>Digester</code> instance, associating them with
Modified: velocity/tools/trunk/src/main/java/org/apache/velocity/tools/view/VelocityView.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/src/main/java/org/apache/velocity/tools/view/VelocityView.java?rev=652274&r1=652273&r2=652274&view=diff
==============================================================================
--- velocity/tools/trunk/src/main/java/org/apache/velocity/tools/view/VelocityView.java (original)
+++ velocity/tools/trunk/src/main/java/org/apache/velocity/tools/view/VelocityView.java Tue Apr 29 22:48:45 2008
@@ -274,7 +274,7 @@
/**
* Simplifies process of getting a property from VelocityEngine,
* because the VelocityEngine interface sucks compared to the singleton's.
- * Use of this method assumes that {@link #init(ServletConfig,VelocityEngine)}
+ * Use of this method assumes that {@link #init(JeeConfig,VelocityEngine)}
* has already been called.
*/
protected String getProperty(String key, String alternate)