sidler 02/04/03 01:10:03
Added: tools README.txt build.xml
tools/lib jdbc2_0-stdext.jar servlet.jar struts.jar
velocity-tools-view-0.4.jar
tools/src/conf MANIFEST.MF
tools/src/java/org/apache/velocity/tools/tools DateTool.java
MathTool.java ParameterParser.java ToolLoader.java
package.html
tools/xdocs DateTool.xml MathTool.xml ParameterParser.xml
ToolLoader.xml
Log:
Added package tools. This is intended to host various reusable context
tools. Currently hosted tools are DateTool, MathTool, RequestParser and
ToolLoader. All tools are optimized to be used with an auto-loading toolbox
manager and come with documentation for the template designers. A
documentation snapshot is online at:
http://www.teamup.com/jakarta-velocity-tools/docs/vellibrary.html
Revision Changes Path
1.1 jakarta-velocity-tools/tools/README.txt
Index: README.txt
===================================================================
R E A D M E
===========
This package contains a collection of general purpose context tools.
Most tools are optimized for use with an automatic toolbox manager.
Build and JAR
-------------
An ant script is provided to build and jar the package.
> ant compile
> ant jar
Documentation
-------------
To generate the documentation for this package, call:
> ant docs
Then look for the generated documentation in the 'docs' subdirectory.
Please send your feedback to [EMAIL PROTECTED]
1.1 jakarta-velocity-tools/tools/build.xml
Index: build.xml
===================================================================
<project name="velocity-tools-library" default="all" basedir=".">
<!-- ========== Initialize Properties ===================================== -->
<property file="build/build.properties"/> <!-- Component local -->
<property file="../build.properties"/> <!-- Commons local -->
<property file="${user.home}/.build.properties"/> <!-- User local -->
<!-- ========== External Dependencies ===================================== -->
<!-- the local repository -->
<property name="local.repository" value="./lib" />
<property name="project.repository" value="../lib" />
<!-- ========== Component Declarations ==================================== -->
<!-- The name of this component -->
<property name="project.name" value="velocity-tools-library" />
<!-- The title of this component -->
<property name="project.title" value=""/>
<!-- The current version number of this component -->
<property name="project.version" value="0.1"/>
<!-- The current version number of this component -->
<property name="project.date" value="24-Mar-2002"/>
<!-- The base directory for compilation targets -->
<property name="build.home" value="target"/>
<!-- The base directory for distribution targets -->
<property name="dist.home" value="dist"/>
<!-- The base directory for component sources -->
<property name="source.home" value="src"/>
<!-- The base directory for component sources -->
<property name="conf.home" value="src/conf"/>
<!-- The docs source directory -->
<property name="docs.src" value="xdocs"/>
<!-- The docs destination directory -->
<property name="docs.dest" value="docs"/>
<!-- The docs destination directory -->
<property name="examples.home" value="examples"/>
<!-- ========== Compiler Defaults ========================================= -->
<!-- Should Java compilations set the 'debug' compiler option? -->
<property name="compile.debug" value="true"/>
<!-- Should Java compilations set the 'deprecation' compiler option? -->
<property name="compile.deprecation" value="true"/>
<!-- Should Java compilations set the 'optimize' compiler option? -->
<property name="compile.optimize" value="true"/>
<!-- Construct compile classpath -->
<path id="classpath">
<fileset dir="${local.repository}">
<include name="**/*.jar"/>
</fileset>
<fileset dir="${project.repository}">
<include name="**/*.jar"/>
</fileset>
</path>
<!-- ========== Executable Targets ======================================== -->
<!-- ================================================================== -->
<!-- I N I T -->
<!-- ================================================================== -->
<target name="init"
description="Initialize and evaluate conditionals">
<echo message="-------- ${project.name} ${project.version} --------"/>
<filter token="name" value="${project.name}"/>
<filter token="version" value="${project.version}"/>
</target>
<!-- ================================================================== -->
<!-- P R E P A R E -->
<!-- ================================================================== -->
<target name="prepare" depends="init"
description="Prepare build directory">
<mkdir dir="${build.home}"/>
<mkdir dir="${build.home}/classes"/>
<mkdir dir="${build.home}/conf"/>
<mkdir dir="${build.home}/javadoc"/>
</target>
<!-- ================================================================== -->
<!-- S T A T I C -->
<!-- ================================================================== -->
<target name="static" depends="prepare"
description="Copy static files to build directory">
<tstamp/>
<copy todir="${build.home}/conf" filtering="on">
<fileset dir="${conf.home}" includes="*.MF"/>
</copy>
</target>
<!-- ================================================================== -->
<!-- C O M P I L E -->
<!-- ================================================================== -->
<target name="compile" depends="static" description="Compile">
<javac srcdir="${source.home}/java"
destdir="${build.home}/classes"
debug="${compile.debug}"
deprecation="${compile.deprecation}"
optimize="${compile.optimize}">
<classpath refid="classpath"/>
</javac>
<copy todir="${build.home}/classes" filtering="on">
<fileset dir="${source.home}/java" excludes="**/*.java"/>
</copy>
</target>
<!-- ================================================================== -->
<!-- C L E A N -->
<!-- ================================================================== -->
<target name="clean"
description="Clean build and distribution directories">
<delete dir="${build.home}"/>
<delete dir="${dist.home}"/>
<delete>
<fileset dir="${basedir}" includes="*.jar"/>
</delete>
<delete>
<fileset dir="${docs.dest}" includes="**/*.html"/>
</delete>
<delete dir="${examples.home}/velstruts"/>
<delete>
<fileset dir="${examples.home}" includes="*.war"/>
</delete>
<delete>
<fileset dir="${basedir}" includes="**/*.bak"/>
</delete>
</target>
<!-- ================================================================== -->
<!-- A L L -->
<!-- ================================================================== -->
<target name="all" depends="clean,jar,docs,javadocs"
description="Clean and compile all components"/>
<!-- ================================================================== -->
<!-- J A V A D O C S -->
<!-- ================================================================== -->
<target name="javadocs" depends="compile"
description="Create Javadoc documentation">
<javadoc sourcepath="${source.home}/java"
destdir="${build.home}/javadoc"
packagenames="org.apache.velocity.tools.struts.*"
author="true"
private="true"
version="true"
doctitle="<h1>${project.title}</h1>"
windowtitle="${project.title} (Version ${project.version})"
bottom="Copyright (c) 2002 Apache Software Foundation" >
<classpath refid="classpath"/>
</javadoc>
</target>
<!-- ================================================================== -->
<!-- J A R -->
<!-- ================================================================== -->
<target name="jar" depends="compile">
<jar jarfile="${project.name}-${project.version}.jar"
basedir="${build.home}/classes"
manifest="${conf.home}/MANIFEST.MF"/>
</target>
<!-- ================================================================== -->
<!-- D O C S -->
<!-- ================================================================== -->
<target name="docs">
<taskdef name="dvsl" classname="org.apache.tools.dvsl.DVSLTask">
<classpath>
<path refid="classpath"/>
</classpath>
</taskdef>
<dvsl
basedir="${docs.src}"
destdir="${docs.dest}/"
toolboxfile="../xdocs/toolbox.props"
extension=".html"
style="../xdocs/site.dvsl"
excludes="*menue.xml"
includes="**/*.xml"
/>
<replace dir="${docs.dest}">
<replacefilter token="@@@version@@@" value="${project.version}"/>
<replacefilter token="@@@date@@@" value="${project.date}"/>
</replace>
</target>
<!-- ================================================================== -->
<!-- I N S T A L L J A R -->
<!-- ================================================================== -->
<target name="install-jar" depends="jar"
description="--> Installs .jar file in ${lib.repo}">
<copy todir="${lib.repo}" filtering="no">
<fileset dir="${basedir}">
<include name="${project.name}-${project.version}.jar"/>
</fileset>
</copy>
</target>
<!-- ================================================================== -->
<!-- D E P L O Y J A R -->
<!-- ================================================================== -->
<target name="deploy-jar" depends="compile, jar"
description="Deploy jar to example applications">
<delete>
<fileset dir="${examples.home}/struts/WEB-INF/lib"
includes="${project.name}-*.jar"/>
</delete>
<copy todir="${examples.home}/struts/WEB-INF/lib" filtering="no">
<fileset dir="${basedir}">
<include name="${project.name}-*.jar"/>
</fileset>
</copy>
</target>
</project>
1.1 jakarta-velocity-tools/tools/lib/jdbc2_0-stdext.jar
<<Binary file>>
1.1 jakarta-velocity-tools/tools/lib/servlet.jar
<<Binary file>>
1.1 jakarta-velocity-tools/tools/lib/struts.jar
<<Binary file>>
1.1 jakarta-velocity-tools/tools/lib/velocity-tools-view-0.4.jar
<<Binary file>>
1.1 jakarta-velocity-tools/tools/src/conf/MANIFEST.MF
Index: MANIFEST.MF
===================================================================
Extension-Name: @package@
Specification-Vendor: Apache Software Foundation
Specification-Version: 1.0
Implementation-Vendor: Apache Software Foundation
Implementation-Version: @version@
1.1
jakarta-velocity-tools/tools/src/java/org/apache/velocity/tools/tools/DateTool.java
Index: DateTool.java
===================================================================
/*
* The Apache Software License, Version 1.1
*
* Copyright (c) 2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Velocity", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.velocity.tools.tools;
import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.Calendar;
import java.util.Locale;
import org.apache.velocity.tools.view.tools.ThreadSafeContextTool;
/**
* <p>Tool for manipulating {@link Date} and {@link Calendar}
* objects in Velocity templates.</p>
*
* <p>The tool is tread-safe and implements interface
* ThreadSafeContextTool. This allows a compatible toolbox
* manager like {@link org.apache.velocity.tools.view.servlet.ServletToolboxManager}
* to automatically load the tool into the context and reuse
* the same instance for the entire runtime.</p>
*
* @author <a href="mailto:[EMAIL PROTECTED]";>Gabriel Sidler</a>
* @author <a href="mailto:[EMAIL PROTECTED]";>Nathan Bubna</a>
* @version $Revision: 1.1 $
*/
public class DateTool implements ThreadSafeContextTool
{
/**
* Default constructor.
*/
public DateTool()
{}
/**
* Returns a Date object. The default Locale is used.
*
* @return a <code>java.util.Date</code> object representing the time at
* which this method was invoked
*/
public static Date getDate()
{
return getDate();
}
/**
* Returns a Date object representing the time at which this method was
* invoked in the specified locale.
*
* @param locale the {@link java.util.Locale} to use to generate the Date
*
* @return a {@link java.util.Date} object representing the time at which
* this method was invoked in the specified locale
*/
public static Date getDate(Locale locale)
{
return getCalendar(locale).getTime();
}
/**
* Returns a Calendar object representing the time at which this method was
* invoked and in the default Locale.
*
* @return a {@link java.util.Calendar} object representing the time at which
* this method was invoked using the default Locale
*/
public static Calendar getCalendar()
{
return Calendar.getInstance();
}
/**
* Returns a Calendar object representing the time at which this method was
* invoked and in the specified locale.
*
* @param locale the {@link java.util.Locale} to use to create a Calendar
* @return a {@link java.util.Calendar} object representing the time at which
* this method was invoked and in the specified locale
*/
public static Calendar getCalendar(Locale locale)
{
return Calendar.getInstance(locale);
}
/**
* Returns a formatted string representing the specified date
* in the default locale.
*
* <p>
* This method uses the same formatting instructions as
* {@link SimpleDateFormat}:
* <pre>
* Symbol Meaning Presentation Example
* ------ ------- ------------ -------
* G era designator (Text) AD
* y year (Number) 1996
* M month in year (Text & Number) July & 07
* d day in month (Number) 10
* h hour in am/pm (1~12) (Number) 12
* H hour in day (0~23) (Number) 0
* m minute in hour (Number) 30
* s second in minute (Number) 55
* S millisecond (Number) 978
* E day in week (Text) Tuesday
* D day in year (Number) 189
* F day of week in month (Number) 2 (2nd Wed in July)
* w week in year (Number) 27
* W week in month (Number) 2
* a am/pm marker (Text) PM
* k hour in day (1~24) (Number) 24
* K hour in am/pm (0~11) (Number) 0
* z time zone (Text) Pacific Standard Time
* ' escape for text (Delimiter)
* '' single quote (Literal) '
*
* Examples: "E, MMMM d" will result in "Tue, July 24"
* "EEE, M-d (H:m)" will result in "Tuesday, 7-24 (14:12)"
* </pre>
*
* @param format the formatting instructions
* @param obj the date to format
*
* @return a formatted string representing the specified date or
* <code>null</code> if the parameters are invalid
*/
public static String format(String format, Object obj)
{
Date date = toDate(obj);
if (date == null || format == null)
{
return null;
}
SimpleDateFormat formatter = new SimpleDateFormat(format);
return formatter.format(date);
}
/**
* Returns a formatted string representing the specified date and locale.
*
* This method uses the same formatting instructions as
* {@link SimpleDateFormat}:
*
* @param format the formatting instructions
* @param obj the date to format
* @param locale the {@link java.util.Locale} to format the date for
*
* @return a formatted string representing the specified date or
* <code>null</code> if the parameters are invalid
* @see #format
*/
public static String format(String format, Object obj, Locale locale)
{
Date date = toDate(obj);
if (date == null || format == null || locale == null)
{
return null;
}
SimpleDateFormat formatter = new SimpleDateFormat(format, locale);
return formatter.format(date);
}
/**
* Returns a Date object representing the specified date.
*
* @param obj the date to convert
*
* @return the converted date
*/
public static Date toDate(Object obj)
{
if (obj == null)
{
return null;
}
if (obj instanceof Date)
{
return (Date)obj;
}
if (obj instanceof Calendar)
{
return ((Calendar)obj).getTime();
}
try
{
//try treating obj as a string and parsing it
DateFormat format = DateFormat.getInstance();
return format.parse(String.valueOf(obj));
}
catch (Exception e)
{
return null;
}
}
/**
* Returns a Calendar object representing the specified date.
*
* @param obj the date to convert
*
* @return the converted date
*/
public static Calendar toCalendar(Object obj)
{
if (obj == null)
{
return null;
}
if (obj instanceof Calendar)
{
return (Calendar)obj;
}
//try to get a date out of it
Date date = toDate(obj);
if (date == null)
{
return null;
}
//convert the date to a calendar
Calendar cal = Calendar.getInstance();
cal.setTime(date);
//Force fields to update.
cal.getTime();
return cal;
}
}
1.1
jakarta-velocity-tools/tools/src/java/org/apache/velocity/tools/tools/MathTool.java
Index: MathTool.java
===================================================================
/*
* The Apache Software License, Version 1.1
*
* Copyright (c) 2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Velocity", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.velocity.tools.tools;
import org.apache.velocity.tools.view.tools.ThreadSafeContextTool;
import java.lang.Math;
/**
* <p>Tool for performing floating point math in Velocity.</p>
*
* <p>Several things should be noted here:</p>
*
* <ol>
* <li>This class does not have methods that take
* primitives. This is simply because Velocity
* wraps all primitives for us automagically.</li>
*
* <li>Most methods return {@link Double} wrappers
* which automatically render the decimal places even
* for whole numbers (e.g. new Double(1).toString() -> '1.0')
* This is intentional. This tool is for floating
* point arithmetic. Integer arithmetic is already supported
* in Velocity syntax. if you really need '1' instead of '1.0',
* just call intValue() on the result.</li>
*
* <li>No null pointer, number format, or divide by zero
* exceptions are thrown here. This is because such exceptions
* thrown in template halt rendering. It should be sufficient
* debugging feedback that Velocity will render the reference
* literally. (e.g. $math.div(1, 0) renders as '$math.div(1, 0)')</li>
* </ul>
*
* @author <a href="mailto:[EMAIL PROTECTED]";>Nathan Bubna</a>
* @version $Revision: 1.1 $ $Date: 2002/04/03 09:10:03 $
*/
public class MathTool implements ThreadSafeContextTool
{
/**
* @param num1 the first number
* @param num2 the second number
* @return the sum of the numbers or
* <code>null</code> if they're invalid
* @see #toDouble
*/
public static Double add(Object num1, Object num2)
{
Double d1 = toDouble(num1);
Double d2 = toDouble(num2);
if (d1 == null || d2 == null)
{
return null;
}
return new Double(d1.doubleValue() + d2.doubleValue());
}
/**
* @param num1 the first number
* @param num2 the second number
* @return the difference of the numbers or
* <code>null</code> if they're invalid
* @see #toDouble
*/
public static Double sub(Object num1, Object num2)
{
Double d1 = toDouble(num1);
Double d2 = toDouble(num2);
if (d1 == null || d2 == null)
{
return null;
}
return new Double(d1.doubleValue() - d2.doubleValue());
}
/**
* @param num1 the first number
* @param num2 the second number
* @return the product of the numbers or
* <code>null</code> if they're invalid
* @see #toDouble
*/
public static Double mul(Object num1, Object num2)
{
Double d1 = toDouble(num1);
Double d2 = toDouble(num2);
if (d1 == null || d2 == null)
{
return null;
}
return new Double(d1.doubleValue() * d2.doubleValue());
}
/**
* @param num1 the first number
* @param num2 the second number
* @return the quotient of the numbers or
* <code>null</code> if they're invalid
* @see #toDouble
*/
public static Double div(Object num1, Object num2)
{
Double d1 = toDouble(num1);
Double d2 = toDouble(num2);
if (d1 == null || d2 == null || d2.doubleValue() == 0.0)
{
return null;
}
return new Double(d1.doubleValue() / d2.doubleValue());
}
/**
* @param num1 the first number
* @param num2 the second number
* @return the first number raised to the power of the
* second or <code>null</code> if they're invalid
* @see #toDouble
*/
public static Double pow(Object num1, Object num2)
{
Double d1 = toDouble(num1);
Double d2 = toDouble(num2);
if (d1 == null || d2 == null)
{
return null;
}
return new Double(Math.pow(d1.doubleValue(), d2.doubleValue()));
}
/**
* @param num1 the first number
* @param num2 the second number
* @return the largest of the numbers or
* <code>null</code> if they're invalid
* @see #toDouble
*/
public static Double max(Object num1, Object num2)
{
Double d1 = toDouble(num1);
Double d2 = toDouble(num2);
if (d1 == null || d2 == null)
{
return null;
}
return new Double(Math.max(d1.doubleValue(), d2.doubleValue()));
}
/**
* @param num1 the first number
* @param num2 the second number
* @return the smallest of the numbers or
* <code>null</code> if they're invalid
* @see #toDouble
*/
public static Double min(Object num1, Object num2)
{
Double d1 = toDouble(num1);
Double d2 = toDouble(num2);
if (d1 == null || d2 == null)
{
return null;
}
return new Double(Math.min(d1.doubleValue(), d2.doubleValue()));
}
/**
* @param num1 the number
* @return the absolute value of the number
* <code>null</code> if it's invalid
* @see #toDouble
*/
public static Double abs(Object num)
{
Double d = toDouble(num);
if (d == null)
{
return null;
}
return new Double(Math.abs(d.doubleValue()));
}
/**
* Converts an object with a numeric value into a Double
* Valid formats are {@link Number} or a {@link String}
* representation of a number
*
* @param num the number to be converted
* @return a {@link Double} representation of the number
* or <code>null</code> if it's invalid
*/
public static Double toDouble(Object num)
{
double value;
try
{
if (num instanceof Number)
{
value = ((Number)num).doubleValue();
}
else
{
value = Double.parseDouble(String.valueOf(num));
}
}
catch (NumberFormatException nfe)
{
return null;
}
return new Double(value);
}
/**
* Converts an object with a numeric value into an Integer
* Valid formats are {@link Number} or a {@link String}
* representation of a number
*
* @param num the number to be converted
* @return a {@link Integer} representation of the number
* or <code>null</code> if it's invalid
*/
public static Integer toInteger(Object num)
{
Double d = toDouble(num);
if (d == null)
{
return null;
}
return new Integer(d.intValue());
}
/**
* Rounds a number to the specified number of decimal places.
* This is particulary useful for simple display formatting.
* If you want to round an number to the nearest integer, it
* is better to use {@link #roundToInt}, as that will return
* an {@link Integer} rather than a {@link Double}.
*
* @param decimals the number of decimal places
* @param value the number to round
* @return the value rounded to the specified number of
* decimal places or <code>null</code> if it's invalid
* @see #toDouble
* @see #toInteger
*/
public static Double roundTo(Object decimals, Object num)
{
Integer i = toInteger(decimals);
Double d = toDouble(num);
if (i == null || d == null)
{
return null;
}
//ok, go ahead and do the rounding
int places = i.intValue();
double value = d.doubleValue();
if (places == 0)
{
value = (int)(value + .5);
}
else
{
double shift = Math.pow(10, places);
value = value * shift;
value = (int)(value + .5);
value = value / shift;
}
return new Double(value);
}
/**
* Rounds a number to the nearest whole Integer
*
* @param num the number to round
* @return the number rounded to the nearest whole Integer
* or <code>null</code> if it's invalid
* @see #toDouble
*/
public static Integer roundToInt(Object num)
{
Double d = toDouble(num);
if (d == null)
{
return null;
}
return new Integer((int)Math.rint(d.doubleValue()));
}
/**
* @returns a pseudo-random {@link Double} greater
* than or equal to 0.0 and less than 1.0
* @see Math#random()
*/
public static Double getRandom()
{
return new Double(Math.random());
}
/**
* This returns a random {@link Integer} within the
* specified range. The return Integer will have a
* value greater than or equal to the first number
* and less than the second number.
*
* @param num1 the first number
* @param num2 the second number
* @return a pseudo-random {@link Integer} greater than
* or equal to the first number and less than
* the second
* @see #toInteger
* @see Math#random()
*/
public static Integer random(Object num1, Object num2)
{
Integer i1 = toInteger(num1);
Integer i2 = toInteger(num2);
if (i1 == null || i2 == null)
{
return null;
}
//get the difference
double diff = i2.intValue() - i1.intValue();
//multiply the difference by a pseudo-random
//double from 0.0 to 1.0 and round to the nearest int
int random = (int)Math.rint(diff * Math.random());
//add the first value to the random int and return as an Integer
return new Integer(random + i1.intValue());
}
}
1.1
jakarta-velocity-tools/tools/src/java/org/apache/velocity/tools/tools/ParameterParser.java
Index: ParameterParser.java
===================================================================
/*
* The Apache Software License, Version 1.1
*
* Copyright (c) 2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Velocity", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.velocity.tools.tools;
import org.apache.velocity.tools.view.tools.ThreadSafeContextTool;
import javax.servlet.ServletRequest;
/**
* Utility class for easy parsing of {@link ServletRequest} parameters
*
* @author <a href="mailto:[EMAIL PROTECTED]";>Gabriel Sidler</a>
* @author <a href="mailto:[EMAIL PROTECTED]";>Nathan Bubna</a>
* @version $Revision: 1.1 $ $Date: 2002/04/03 09:10:03 $
*/
public class ParameterParser implements ThreadSafeContextTool
{
/**
* Constructs a new instance
*/
public ParameterParser()
{}
/**
* @param request the servlet request
* @param key the parameter's key
* @return parameter matching the specified key or
* <code>null</code> if there is no matching
* parameter
*/
public static String getString(ServletRequest request, String key)
{
return request.getParameter(key);
}
/**
* @param request the servlet request
* @param the desired parameter's key
* @param the alternate value
* @return parameter matching the specified key or the
* specified alternate String if there is no matching
* parameter
*/
public static String getString(ServletRequest request, String key, String
alternate)
{
String s = getString(request, key);
return (s != null) ? s : alternate;
}
/**
* @param request the servlet request
* @param the desired parameter's key
* @return a {@link Boolean} object for the specified key or
* <code>null</code> if no matching parameter is found
*/
public static Boolean getBoolean(ServletRequest request, String key)
{
String s = getString(request, key);
return (s != null) ? Boolean.valueOf(s) : null;
}
/**
* @param request the servlet request
* @param the desired parameter's key
* @param the alternate boolean value
* @return boolean value for the specified key or the
* alternate boolean is no value is found
*/
public static boolean getBoolean(ServletRequest request, String key, boolean
alternate)
{
Boolean bool = getBoolean(request, key);
return (bool != null) ? bool.booleanValue() : alternate;
}
/**
* @param request the servlet request
* @param the desired parameter's key
* @param the alternate {@link Boolean}
* @return a {@link Boolean} for the specified key or the specified
* alternate if no matching parameter is found
*/
public static Boolean getBoolean(ServletRequest request, String key, Boolean
alternate)
{
Boolean bool = getBoolean(request, key);
return (bool != null) ? bool : alternate;
}
/**
* @param request the servlet request
* @param the desired parameter's key
* @return a {@link Number} for the specified key or
* <code>null</code> if no matching parameter is found
*/
public static Number getNumber(ServletRequest request, String key)
{
String s = getString(request, key);
if (s == null || s.length() == 0)
{
return null;
}
if (s.indexOf('.') >= 0)
{
return new Double(s);
}
return new Long(s);
}
/**
* @param request the servlet request
* @param the desired parameter's key
* @param the alternate Number
* @return a Number for the specified key or the specified
* alternate if no matching parameter is found
*/
public static Number getNumber(ServletRequest request, String key, Number
alternate)
{
Number n = getNumber(request, key);
return (n != null) ? n : alternate;
}
/**
* @param request the servlet request
* @param the desired parameter's key
* @param the alternate int value
* @return the int value for the specified key or the specified
* alternate value if no matching parameter is found
*/
public static int getInt(ServletRequest request, String key, int alternate)
{
Number n = getNumber(request, key);
return (n != null) ? n.intValue() : alternate;
}
/**
* @param request the servlet request
* @param the desired parameter's key
* @param the alternate double value
* @return the double value for the specified key or the specified
* alternate value if no matching parameter is found
*/
public static double getDouble(ServletRequest request, String key, double
alternate)
{
Number n = getNumber(request, key);
return (n != null) ? n.doubleValue() : alternate;
}
/**
* @param request the servlet request
* @param the key for the desired parameter
* @return an array of String objects containing all of the values
* the given request parameter has, or <code>null</code>
* if the parameter does not exist
*/
public static String[] getStrings(ServletRequest request, String key)
{
return request.getParameterValues(key);
}
/**
* @param request the servlet request
* @param the key for the desired parameter
* @return an array of Number objects for the specified key or
* <code>null</code> if the parameter does not exist or the
* parameter does not contain Numbers.
*/
public static Number[] getNumbers(ServletRequest request, String key)
{
String[] strings = getStrings(request, key);
if (strings == null)
{
return null;
}
Number[] nums = new Number[strings.length];
try
{
for(int i=0; i<nums.length; i++)
{
if (strings[i] != null && strings[i].length() > 0)
{
if (strings[i].indexOf('.') >= 0)
{
nums[i] = new Double(strings[i]);
}
else
{
nums[i] = new Long(strings[i]);
}
}
}
}
catch (NumberFormatException nfe)
{
return null;
}
return nums;
}
/**
* @param request the servlet request
* @param the key for the desired parameter
* @return an array of int values for the specified key or
* <code>null</code> if the parameter does not exist or the
* parameter does not contain ints.
*/
public static int[] getInts(ServletRequest request, String key)
{
String[] strings = getStrings(request, key);
if (strings == null)
{
return null;
}
int[] ints = new int[strings.length];
try
{
for(int i=0; i<ints.length; i++)
{
if (strings[i] != null && strings[i].length() > 0)
{
ints[i] = Integer.parseInt(strings[i]);
}
}
}
catch (NumberFormatException nfe)
{
return null;
}
return ints;
}
/**
* @param request the servlet request
* @param the key for the desired parameter
* @return an array of double values for the specified key or
* <code>null</code> if the parameter does not exist or the
* parameter does not contain doubles.
*/
public static double[] getDoubles(ServletRequest request, String key)
{
String[] strings = getStrings(request, key);
if (strings == null)
{
return null;
}
double[] doubles = new double[strings.length];
try
{
for(int i=0; i<doubles.length; i++)
{
if (strings[i] != null && strings[i].length() > 0)
{
doubles[i] = Double.parseDouble(strings[i]);
}
}
}
catch (NumberFormatException nfe)
{
return null;
}
return doubles;
}
}
1.1
jakarta-velocity-tools/tools/src/java/org/apache/velocity/tools/tools/ToolLoader.java
Index: ToolLoader.java
===================================================================
/*
* The Apache Software License, Version 1.1
*
* Copyright (c) 2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Velocity", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.velocity.tools.tools;
import org.apache.velocity.tools.view.context.ViewContext;
import org.apache.velocity.tools.view.tools.ContextContextTool;
import org.apache.velocity.tools.view.tools.LogEnabledContextToolImpl;
import org.apache.velocity.context.Context;
/**
* <p>A context tool that allows template designers to load
* other context tools from within the template. Any object
* with a public constructor without parameters can be used
* as a context tool.</p>
*
* <p>Example: Assuming that an instance of this class has
* been loaded into the Velocity context under key "toolloader",
* then from within a template a designer would call:<br>
* <br>
* <code>$toolloader.load("math", "xxx.yyy.zzz.MathTool")</code><br>
* <br>
* to load a math tool into the context under key "math". This tool
* is then available for use within the template, for example:<br>
* <br>
* <code>$math.random(1, 100)</code><br>
* </p>
*
* <p>THIS CLASS IS HERE AS A PROOF OF CONCEPT ONLY. IT NEEDS TO BE
* REFACTORED.</p>
*
* @author <a href="mailto:[EMAIL PROTECTED]";>Gabe Sidler</a>
* @author <a href="mailto:[EMAIL PROTECTED]";>Geir Magnusson Jr.</a>
*
* @version $Id: ToolLoader.java,v 1.1 2002/04/03 09:10:03 sidler Exp $
*
*/
public class ToolLoader extends LogEnabledContextToolImpl
implements ContextContextTool
{
// -------------------------------------------- Properties ----------------
/**
* <p>A reference to the Velocity context.</p>
*/
private Context ctx;
// -------------------------------------------- Constructors --------------
/**
* Returns a factory for instances of this class. Use method
* {@link #getInstance(Context context)} to obtain instances
* of this class. Do not use instance obtained from this method
* in templates. They are not properly initialized.
*/
public ToolLoader()
{
}
/**
* Contructor for internal use only.
*/
private ToolLoader(Context context)
{
this.ctx = context;
}
// --------------------------------------- Interface ContextContextTool ---
/**
* Returns an initialized instance of this context tool.
*/
public Object getInstance(Context context)
{
return new ToolLoader(context);
}
// -------------------------------------------- Public Utility Methods ----
/**
* <p>Loads a context tool of class <i>clazz</i> and inserts it
* into the Velocity context with key <i>key</i>. On order to be
* loadable, context tools must provide a constructor with no
* parameters. The life cycle of a context tool loaded using
* this method is the current request.</p>
*
* @param key the key used to add the tool to the context
* @param clazz the fully qualified class name of the tool that
* is to be instantiated and added to the context
*/
public void load(String key, String clazz)
{
try
{
Object tool = Class.forName(clazz).newInstance();
ctx.put(key, tool);
log(INFO, "Loaded tool: Key: " + key + " Class: " + clazz);
}
catch (Exception e)
{
log(ERROR, "Error loading context tool: " + clazz + " with key: " + key
+ ". " + e);
}
}
}
1.1
jakarta-velocity-tools/tools/src/java/org/apache/velocity/tools/tools/package.html
Index: package.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
These are Javadoc package comments.
-->
</head>
<body bgcolor="white">
Contains a collection of reusable, general-purpose Velocity context tools. Where
applicable
tools are optimized to be used in conjunction with a toolbox manager.
<!--
##### THIS IS THE TEMPLATE FOR THE PACKAGE DOC COMMENTS. #####
##### TYPE YOUR PACKAGE COMMENTS HERE. BEGIN WITH A #####
##### ONE-SENTENCE SUMMARY STARTING WITH A VERB LIKE: #####
Provides for....
-->
<h2>Package Specification</h2>
<!--
##### FILL IN ANY SPECS NEEDED BY JAVA COMPATIBILITY KIT #####
<ul>
<li><a href="">##### REFER TO ANY FRAMEMAKER SPECIFICATION HERE #####</a>
</ul>
-->
<h2>Related Documentation</h2>
<!--
For overviews, tutorials, examples, guides, and tool documentation, please see:
<ul>
<li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>
</ul>
-->
<!-- Put @see and @since tags down here. -->
</body>
</html>
1.1 jakarta-velocity-tools/tools/xdocs/DateTool.xml
Index: DateTool.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>DateTool</title>
<author email="[EMAIL PROTECTED]">Gabriel Sidler</author>
<projectfile>../xdocs/vellibrary-menue.xml</projectfile>
</properties>
<body>
<section name="DateTool Reference Documentation">
<p>
Tool for manipulating <code>java.util.Date</code> and
<code>java.util.Calendar</code>
objects in Velocity templates. It supports locales to format dates language
and country specific.
</p>
<toolinfo>
<version>@@@version@@@, @@@date@@@</version>
<jar>velocity-tools-library-@@@version@@@.jar</jar>
<clazz>org.apache.velocity.tools.tools.DateTool</clazz>
<name>$dateTool</name>
<author email="[EMAIL PROTECTED]">Gabriel Sidler</author>
<author email="[EMAIL PROTECTED]">Nathan Bubna</author>
<config-example><tool>
<key>dateTool</key>
<class>org.apache.velocity.tools.tools.DateTool</class>
</tool></config-example>
</toolinfo>
<methods/>
</section>
<section name="getDate()">
<method name="getDate()">
<abstract>
Returns a Date object representing the time at which this
method was invoked.
</abstract>
<signature>
String getDate()
</signature>
<signature>
String getDate(Locale locale)
</signature>
<parameters>
<parameter name="locale">
An object of class <code>java.util.Locale</code> that represents
the locale
to be used to create the date.
</parameter>
</parameters>
<returns>
An object of class <code>java.util.Date</code> representing the time
at which this
method was invoked in the specified locale. If no locale is
specified,
the system's default locale is used.
</returns>
</method>
</section>
<section name="getCalendar()">
<method name="getCalendar()">
<abstract>
Returns a Calendar object representing the time at which this
method was invoked.
</abstract>
<signature>
String getCalendar()
</signature>
<signature>
String getCalendar(Locale locale)
</signature>
<parameters>
<parameter name="locale">
An object of class <code>java.util.Locale</code> that represents
the locale
to be used to create the calendar.
</parameter>
</parameters>
<returns>
An object of class <code>java.util.Calendar</code> representing the
time at which this
method was invoked in the specified locale. If no locale is
specified,
the system's default locale is used.
</returns>
</method>
</section>
<section name="format()">
<method name="format()">
<abstract>
Returns a formatted string representing the specified date.
</abstract>
<signature>
String format(String format, Object obj)
</signature>
<signature>
String format(String format, Object obj, Locale locale)
</signature>
<parameters>
<parameter name="format">
A string that represents the formatting instructions according to
<code>java.text.SimpleDateFormat</code>. See also below.
</parameter>
<parameter name="obj">
An object of class <code>java.util.Date</code> or
<code>java.util.Calendar</code>. It is
also possible to pass a string that represents a parsable date
according to <code>java.text.DateFormat</code>.
</parameter>
<parameter name="locale">
An object of class <code>java.util.Locale</code> that represents
the locale
to format the date for.
</parameter>
</parameters>
<returns>
The formatted date string in the specified locale or
<code>null</code>
if one or several input parameters are invalid. If no locale is
specified,
the system's default locale is used instead.
</returns>
<description>
<p>This methods use the same formatting instructions as class
<code>java.text.SimpleDateFormat</code>.</p>
<sourcecode>
Symbol Meaning Presentation Example
------ ------- ------------ -------
G era designator (Text) AD
y year (Number) 1996
M month in year (Text & Number) July & 07
d day in month (Number) 10
h hour in am/pm (1~12) (Number) 12
H hour in day (0~23) (Number) 0
m minute in hour (Number) 30
s second in minute (Number) 55
S millisecond (Number) 978
E day in week (Text) Tuesday
D day in year (Number) 189
F day of week in month (Number) 2 (2nd Wed in July)
w week in year (Number) 27
W week in month (Number) 2
a am/pm marker (Text) PM
k hour in day (1~24) (Number) 24
K hour in am/pm (0~11) (Number) 0
z time zone (Text) Pacific Standard Time
' escape for text (Delimiter)
'' single quote (Literal) '
Examples: "E, MMMM d" will result in "Tue, July 24"
"EEE, M-d (H:m)" will result in "Tuesday, 7-24 (14:12)"
</sourcecode>
</description>
</method>
</section>
<section name="toDate()">
<method name="toDate()">
<abstract>
Returns a Date object representing the specified date.
</abstract>
<signature>
Date toDate(Object obj)
</signature>
<parameters>
<parameter name="obj">
The date to convert. The parameter can be an object of class
<code>java.util.Date</code> or <code>java.util.Calendar</code>.
It is also possible to
pass a string that represents a parsable date according to
<code>java.text.DateFormat</code>.
</parameter>
</parameters>
<returns>
An object of class <code>java.util.Date</code> representing the
converted date
or <null></null> of the input parameter is invalid.
</returns>
</method>
</section>
<section name="toCalendar()">
<method name="toCalendar()">
<abstract>
Returns a Calendar object representing the specified date.
</abstract>
<signature>
Calendar toCalendar(Object obj)
</signature>
<parameters>
<parameter name="obj">
The date to convert. The parameter can be an object of class
<code>java.util.Date</code> or <code>java.util.Calendar</code>.
It is also possible to
pass a string that represents a parsable date according to
<code>java.text.DateFormat</code>.
</parameter>
</parameters>
<returns>
An object of class <code>java.util.Calendar</code> representing the
converted date
or <null></null> of the input parameter is invalid.
</returns>
</method>
</section>
</body>
</document>
1.1 jakarta-velocity-tools/tools/xdocs/MathTool.xml
Index: MathTool.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>MathTool</title>
<author email="[EMAIL PROTECTED]">Gabriel Sidler</author>
<projectfile>../xdocs/vellibrary-menue.xml</projectfile>
</properties>
<body>
<section name="MathTool Reference Documentation">
<p>Tool for performing floating point math in Velocity.</p>
<p>A few things to note:</p>
<ul>
<li>Most methods return numbers wrapped as Double
which automatically render the decimal places even
for whole numbers (e.g. new Double(1).toString() -> '1.0').
This is intentional. This tool is for floating
point arithmetic. Integer arithmetic is already supported
by the Velocity template language. If you really need '1'
instead of '1.0', just call intValue() on the result.</li>
<li>No null pointer, number format, or divide by zero
exceptions are thrown here. This is because such exceptions
halt template rendering. It should be sufficient debugging
feedback that Velocity will render the reference
literally. (e.g. $math.div(1, 0) renders as '$math.div(1, 0)')</li>
<li>Class <code>java.lang.Math</code> is used to perform the
mathematical operations.</li>
</ul>
<toolinfo>
<version>@@@version@@@, @@@date@@@</version>
<jar>velocity-tools-library-@@@version@@@.jar</jar>
<clazz>org.apache.velocity.tools.tools.MathTool</clazz>
<name>$math</name>
<author email="[EMAIL PROTECTED]">Nathan Bubna</author>
<config-example><tool>
<key>math</key>
<class>org.apache.velocity.tools.tools.MathTool</class>
</tool></config-example>
</toolinfo>
<methods/>
</section>
<section name="add()">
<method name="add()">
<abstract>
Addition
</abstract>
<signature>
Double add(Object num1, Object num2)
</signature>
<parameters>
<parameter name="num1, num2">
Operands of the addition. Valid input is any number (primitive
types or objects, Velocity automatically converts primitives
types
to objects) or a string representation of a number.
</parameter>
</parameters>
<returns>
A <code>java.lang.Double</code> representing the sum or
<code>null</code> if the input
paramters are not valid.
</returns>
</method>
</section>
<section name="sub()">
<method name="sub()">
<abstract>
Subtraction
</abstract>
<signature>
Double sub(Object num1, Object num2)
</signature>
<parameters>
<parameter name="num1, num2">
Operands of the subtraction. Valid input is any number (primitive
types or objects, Velocity automatically converts primitives
types
to objects) or a string representation of a number.
</parameter>
</parameters>
<returns>
A <code>java.lang.Double</code> representing the result of the
subtraction
or <code>null</code> if the input paramters are not valid.
</returns>
</method>
</section>
<section name="mul()">
<method name="mul()">
<abstract>
Multiplication
</abstract>
<signature>
Double mul(Object num1, Object num2)
</signature>
<parameters>
<parameter name="num1, num2">
Factors of the multiplication. Valid input is any number
(primitive
types or objects, Velocity automatically converts primitives
types
to objects) or a string representation of a number.
</parameter>
</parameters>
<returns>
A <code>java.lang.Double</code> representing the result of the
multiplication
or <code>null</code> if the input paramters are not valid.
</returns>
</method>
</section>
<section name="div()">
<method name="div()">
<abstract>
Division
</abstract>
<signature>
Double div(Object num1, Object num2)
</signature>
<parameters>
<parameter name="num1, num2">
Input for the division. Valid input is any number (primitive
types or objects, Velocity automatically converts primitives
types
to objects) or a string representation of a number.
</parameter>
</parameters>
<returns>
A <code>java.lang.Double</code> representing the result of the
division
or <code>null</code> if the input paramters are not valid.
</returns>
</method>
</section>
<section name="pow()">
<method name="pow()">
<abstract>
Power of
</abstract>
<signature>
Double pow(Object num1, Object num2)
</signature>
<parameters>
<parameter name="num1, num2">
Operands. Valid input is any number (primitive
types or objects, Velocity automatically converts primitives
types
to objects) or a string representation of a number.
</parameter>
</parameters>
<returns>
A <code>java.lang.Double</code> representing the first number raised
to
the power of the second or <code>null</code> if the input paramters
are not valid.
</returns>
</method>
</section>
<section name="max()">
<method name="max()">
<abstract>
Maximum of two numbers
</abstract>
<signature>
Double max(Object num1, Object num2)
</signature>
<parameters>
<parameter name="num1, num2">
Operands. Valid input is any number (primitive
types or objects, Velocity automatically converts primitives
types
to objects) or a string representation of a number.
</parameter>
</parameters>
<returns>
A <code>java.lang.Double</code> representing the maximum of the two
numbers or <code>null</code> if the input paramters are not valid.
</returns>
</method>
</section>
<section name="min()">
<method name="min()">
<abstract>
Minimum of two numbers
</abstract>
<signature>
Double min(Object num1, Object num2)
</signature>
<parameters>
<parameter name="num1, num2">
Operands. Valid input is any number (primitive
types or objects, Velocity automatically converts primitives
types
to objects) or a string representation of a number.
</parameter>
</parameters>
<returns>
A <code>java.lang.Double</code> representing the minimum of the two
numbers or <code>null</code> if the input paramters are not valid.
</returns>
</method>
</section>
<section name="abs()">
<method name="max()">
<abstract>
Absolute value of a number
</abstract>
<signature>
Double abs(Object num)
</signature>
<parameters>
<parameter name="num1, num2">
Operand. Valid input is any number (primitive
types or objects, Velocity automatically converts primitives
types
to objects) or a string representation of a number.
</parameter>
</parameters>
<returns>
A <code>java.lang.Double</code> representing the absolute value of
the
input or <code>null</code> if the input paramter is not valid.
</returns>
</method>
</section>
<section name="toDouble()">
<method name="toDouble()">
<abstract>
Converts a number into a double.
</abstract>
<signature>
Double toDouble(Object num)
</signature>
<parameters>
<parameter name="num">
Operand. Valid input is any number (primitive
types or objects, Velocity automatically converts primitives
types
to objects) or a string representation of a number.
</parameter>
</parameters>
<returns>
A <code>java.lang.Double</code> representing the input number or
<code>null</code> if the input paramter is not valid.
</returns>
</method>
</section>
<section name="toInteger()">
<method name="toInteger()">
<abstract>
Converts a number into an integer
</abstract>
<signature>
Integer toInteger(Object num)
</signature>
<parameters>
<parameter name="num">
Operand. Valid input is any number (primitive
types or objects, Velocity automatically converts primitives
types
to objects) or a string representation of a number.
</parameter>
</parameters>
<returns>
A <code>java.lang.Integer</code> representing the input number or
<code>null</code> if the input paramter is not valid.
</returns>
</method>
</section>
<section name="roundTo()">
<method name="roundTo()">
<abstract>
Rounds a number to the specified number of decimal places
</abstract>
<signature>
Double roundTo(Object decimals, Object num)
</signature>
<parameters>
<parameter name="decimals">
The number of decimal places. Valid input is any number
(primitive
types or objects, Velocity automatically converts primitives
types
to objects) or a string representation of a number.
</parameter>
<parameter name="num">
The number to round. Valid input is any number (primitive
types or objects, Velocity automatically converts primitives
types
to objects) or a string representation of a number.
</parameter>
</parameters>
<returns>
A <code>java.lang.Double</code> representing the input number
rounded to the specified number of decimal places or
<code>null</code> if the input paramter is not valid.
</returns>
<description>
<p>This method is particulary useful for simple display formatting.
If you want to round an number to the nearest integer, it
is better to use method <code><a
href="#roundToInt()">roundToInt()</a></code>,
as that will return an <code>java.lang.Integer</code> rather than
a <code>java.lang.Double</code>.</p>
</description>
</method>
</section>
<section name="roundToInt()">
<method name="roundToInt()">
<abstract>
Rounds a number to the nearest whole Integer
</abstract>
<signature>
Integer roundToInt(Object num)
</signature>
<parameters>
<parameter name="num">
The number to round. Valid input is any number (primitive
types or objects, Velocity automatically converts primitives
types
to objects) or a string representation of a number.
</parameter>
</parameters>
<returns>
A <code>java.lang.Integer</code> representing the input number
rounded to nearest whole Integer or <code>null</code> if the input
paramter is not valid.
</returns>
</method>
</section>
<section name="getRandom()">
<method name="getRandom()">
<abstract>
Returns a pseudo-random number
</abstract>
<signature>
Double getRandom()
</signature>
<returns>
A <code>java.lang.Double</code>
greater than or equal to 0.0 and less than 1.0.
</returns>
</method>
</section>
<section name="random()">
<method name="random()">
<abstract>
Returns a pseudo-random number in a configurable range
</abstract>
<signature>
Integer random(Object num1, Object num2)
</signature>
<parameters>
<parameter name="num1, num2">
First and last number of range. Valid input is any number
(primitive
types or objects, Velocity automatically converts primitives
types
to objects) or a string representation of a number.
</parameter>
</parameters>
<returns>
A <code>java.lang.Integer</code> greater than or equal to the first
number and less than the second number or <code>null</code> if the
input paramter
is not valid.
</returns>
</method>
</section>
</body>
</document>
1.1 jakarta-velocity-tools/tools/xdocs/ParameterParser.xml
Index: ParameterParser.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>ParameterParser</title>
<author email="[EMAIL PROTECTED]">Gabriel Sidler</author>
<projectfile>../xdocs/vellibrary-menue.xml</projectfile>
</properties>
<body>
<section name="ParameterParser Reference Documentation">
<p>Context tool for easy parsing of ServletRequest parameters.</p>
<toolinfo>
<version>@@@version@@@, @@@date@@@</version>
<jar>velocity-tools-library-@@@version@@@.jar</jar>
<clazz>org.apache.velocity.tools.tools.ParameterParser</clazz>
<name>$reqParser</name>
<author email="[EMAIL PROTECTED]">Nathan Bubna</author>
<config-example><tool>
<key>reqParser</key>
<class>org.apache.velocity.tools.tools.RequestParser</class>
</tool></config-example>
</toolinfo>
<methods/>
</section>
<section name="getString()">
<method name="getString()">
<abstract>
Returns the specified servlet request parameter as a String
</abstract>
<signature>
String getString(ServletRequest request, String key)
</signature>
<signature>
String getString(ServletRequest request, String key, String
alternate)
</signature>
<parameters>
<parameter name="request">
The servlet request of class
<code>javax.servlet.ServletRequest</code>
</parameter>
<parameter name="key">
The key of the desired string parameter
</parameter>
<parameter name="alternate">
An alternate value
</parameter>
</parameters>
<returns>
The value of the parameter matching the specified key or the
specified alternate String if there is no matching parameter.
A value of <code>null</code> is returned if no alternate value
is defined and the desired parameter is not found.
</returns>
</method>
</section>
<section name="getBoolean()">
<method name="getBoolean()">
<abstract>
Returns the specified servlet request parameter as a Boolean object
or
a boolean primitive type
</abstract>
<signature>
Boolean getBoolean(ServletRequest request, String key)
</signature>
<signature>
Boolean getBoolean(ServletRequest request, String key, Boolean
alternate)
</signature>
<signature>
boolean getBoolean(ServletRequest request, String key, boolean
alternate)
</signature>
<parameters>
<parameter name="request">
The servlet request of class
<code>javax.servlet.ServletRequest</code>
</parameter>
<parameter name="key">
The key of the desired string parameter
</parameter>
<parameter name="alternate">
An alternate value
</parameter>
</parameters>
<returns>
A Boolean object or boolean primitive type that represents the
value of the servlet request parameter matching the specified key
or the specified alternate boolean if there is no matching parameter.
A value of <code>null</code> is returned if no alternate value
is defined and the desired parameter is not found.
</returns>
</method>
</section>
<section name="getNumber()">
<method name="getNumber()">
<abstract>
Returns the specified servlet request parameter as a Number object
</abstract>
<signature>
Number getNumber(ServletRequest request, String key)
</signature>
<signature>
Number getNumber(ServletRequest request, String key, Number
alternate)
</signature>
<parameters>
<parameter name="request">
The servlet request of class
<code>javax.servlet.ServletRequest</code>
</parameter>
<parameter name="key">
The key of the desired string parameter
</parameter>
<parameter name="alternate">
An alternate value
</parameter>
</parameters>
<returns>
A <code>java.lang.Number</code> object that represents the
value of the servlet request parameter matching the specified key
or the specified alternate Number if there is no matching parameter.
A value of <code>null</code> is returned if no alternate value
is defined and the desired parameter is not found.
</returns>
</method>
</section>
<section name="getInt()">
<method name="getInt()">
<abstract>
Returns the specified servlet request parameter as an integer
</abstract>
<signature>
int getInt(ServletRequest request, String key, int alternate)
</signature>
<parameters>
<parameter name="request">
The servlet request of class
<code>javax.servlet.ServletRequest</code>
</parameter>
<parameter name="key">
The key of the desired string parameter
</parameter>
<parameter name="alternate">
An alternate value
</parameter>
</parameters>
<returns>
An integer that represents the
value of the servlet request parameter matching the specified key
or the specified alternate value if there is no matching parameter.
</returns>
</method>
</section>
<section name="getDouble()">
<method name="getDouble()">
<abstract>
Returns the specified servlet request parameter as a double
</abstract>
<signature>
double getDouble(ServletRequest request, String key, double
alternate)
</signature>
<parameters>
<parameter name="request">
The servlet request of class
<code>javax.servlet.ServletRequest</code>
</parameter>
<parameter name="key">
The key of the desired string parameter
</parameter>
<parameter name="alternate">
An alternate value
</parameter>
</parameters>
<returns>
An double that represents the
value of the servlet request parameter matching the specified key
or the specified alternate value if there is no matching parameter.
</returns>
</method>
</section>
<section name="getStrings()">
<method name="getStrings()">
<abstract>
Returns an array of Strings of all the values of the specified
servlet
request parameter
</abstract>
<signature>
String[] getStrings(ServletRequest request, String key)
</signature>
<parameters>
<parameter name="request">
The servlet request of class
<code>javax.servlet.ServletRequest</code>
</parameter>
<parameter name="key">
The key of the desired string parameter
</parameter>
</parameters>
<returns>
A array of Strings that represent all the values of the desired
request parameter or <code>null</code> if the parameter does not
exist.
</returns>
</method>
</section>
<section name="getNumbers()">
<method name="getNumbers()">
<abstract>
Returns an array of Numbers of all the values of the specified
servlet
request parameter
</abstract>
<signature>
Number[] getNumbers(ServletRequest request, String key)
</signature>
<parameters>
<parameter name="request">
The servlet request of class
<code>javax.servlet.ServletRequest</code>
</parameter>
<parameter name="key">
The key of the desired string parameter
</parameter>
</parameters>
<returns>
A array of <code>java.lang.Number</code> that represent all the
values of the desired request parameter or <code>null</code> if
the parameter does not exist.
</returns>
</method>
</section>
<section name="getInts()">
<method name="getInts()">
<abstract>
Returns an array of integers of all the values of the specified
servlet
request parameter
</abstract>
<signature>
int[] getInts(ServletRequest request, String key)
</signature>
<parameters>
<parameter name="request">
The servlet request of class
<code>javax.servlet.ServletRequest</code>
</parameter>
<parameter name="key">
The key of the desired string parameter
</parameter>
</parameters>
<returns>
A array of integer primitive types that represent all the
values of the desired request parameter or <code>null</code> if
the parameter does not exist.
</returns>
</method>
</section>
<section name="getDoubles()">
<method name="getDoubles()">
<abstract>
Returns an array of doubles of all the values of the specified
servlet
request parameter
</abstract>
<signature>
double[] getDoubles(ServletRequest request, String key)
</signature>
<parameters>
<parameter name="request">
The servlet request of class
<code>javax.servlet.ServletRequest</code>
</parameter>
<parameter name="key">
The key of the desired string parameter
</parameter>
</parameters>
<returns>
A array of double primitive types that represent all the
values of the desired request parameter or <code>null</code> if
the parameter does not exist.
</returns>
</method>
</section>
</body>
</document>
1.1 jakarta-velocity-tools/tools/xdocs/ToolLoader.xml
Index: ToolLoader.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>ToolLoader</title>
<author email="[EMAIL PROTECTED]">Gabriel Sidler</author>
<projectfile>../xdocs/vellibrary-menue.xml</projectfile>
</properties>
<body>
<section name="ToolLoader Reference Documentation">
<p>
A context tool that allows template designers to load context tools
from within the template. Any object with a public constructor without
parameters can be loaded into the context.
</p>
<toolinfo>
<version>@@@version@@@, @@@date@@@</version>
<jar>velocity-tools-library-@@@version@@@.jar</jar>
<clazz>org.apache.velocity.tools.tools.ToolLoader</clazz>
<name>$toolLoader</name>
<author email="[EMAIL PROTECTED]">Gabriel Sidler</author>
<config-example><tool>
<key>toolLoader</key>
<class>org.apache.velocity.tools.tools.ToolLoader</class>
</tool></config-example>
</toolinfo>
<methods/>
</section>
<section name="load()">
<method name="load()">
<abstract>
Loads a context tool and inserts it into the Velocity context.
</abstract>
<signature>
void load(String key, String class)
</signature>
<parameters>
<parameter name="key">
The key string used to insert to newly instantiated tool
into the Velocity context.
</parameter>
<parameter name="class">
The name of the class to instantiate.
</parameter>
</parameters>
<description>
<p>Loads a context tool of class <i>class</i> and inserts it
into the Velocity context with key <i>key</i>. On order to be
loadable, context tools must provide a public constructor with no
parameters.</p>
<p>The life cycle of a context tool loaded using this method is
the current template request. The instance is processing of the
current template has been completet.</p>
<p>If the specified class cannot be found or does not have a
public contructor without parameters, then the tool is not loaded
and an error message is written to the log.</p>
<p>Application example:</p>
<sourcecode>$toolLoader("math", "org.apache.velocity.tools.tools.MathTool")
$math.random(1,1000)</sourcecode>
<p>Loads MathTool with name $math into the context. Then, its
random() function is
used to generate a random number betweenn 1 and 1000.</p>
</description>
</method>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
