src/content/tools/devel/generic.mdtext

Title: Apache Velocity Tools - Generic Tools

## Overview

GenericTools is the set of classes that provide basic infrastructure for using tools in standard Java SE Velocity projects, as well as a set of tools for use in generic Velocity templates. These tools have no Java EE dependencies and are often safe to use as "singletons".  Some of them are not thread-safe to allow both a no-arg constructor and configurability, but the state-changing methods are declared protected with the exception of configure(Map) which is--by default--rendered useless after being used just once.  If you require strict thread-safety, be cautious in using any configurable tools and consider [restricting the abilities of template authors](http://wiki.apache.org/velocity/BuildingSecureWebApplications) to prevent circumvention of the lockdown placed on configuration methods.

## Installation

For inclusion in a Maven project, use the following dependency block:

    :::xml
    <dependency>
        <groupId>org.apache.velocity.tools</groupId>
        <artifactId>velocity-tools-generic</artifactId>
        <version>3.0</version>
    </dependency>

Otherwise, see the [download page](/download.html#tools) for how to get the Velocity Generic Tools jar.

## Usage

+ Initialization with only standard generic tools, using the default configuration file:
    
        :::java
        /* Create tools initialization properties */
        Map<String, Object> properties = new HashMap<String, Object>();
        /* RenderTool needs to know the VelocityEngine. Setting the engine will also set the logger. */
        properties.put("engine", engine);
        /* If the render tool is not to be used, you can instead just set the logger if needed as follow:
         *
         *   properties.put("log", logger);
         *
         * Otherwise, the engine logger will be used.
         * 
         */
        
        /* Create the manager. autoConfigure and includeDefaults are both booleans which default to true. */
        ToolManager manager = new ToolManager(autoConfigure, includeDefaults);

+ Initialization using a provided configuration file (to customize tools or tune standard tools configuration):
    
        :::java
        /* Create tools initialization properties */
        Map<String, Object> properties = new HashMap<String, Object>();
        /* RenderTool needs to know the VelocityEngine. Setting the engine will also set the logger. */
        properties.put("engine", engine);
        /* If the render tool is not to be used, you can instead just set the logger if needed as follow:
         *
         *   properties.put("log", logger);
         *
         * Otherwise, the engine logger will be used.
         * 
         */
        
        /* Create the manager. includeDefaults is a boolean which defaults to true. */
        ToolManager manager = new ToolManager(false, includeDefaults);

        /* Configure the manager
         * toolsConfiguration is a filesystem- or class- path towards your tools configuration,
         * which can be a .xml, a .properties, or a .class of a configuration factory which
         * has a getConfiguration() method returning a FactoryConfiguration object.");
         */
        manager.configure(toolsConfiguration);

You can then create Velocity contexts with:
    
        :::java
        Context context = manager.createContext();


## Default Configuration

The default configuration provided for GenericTools is [here](http://svn.apache.org/viewvc/velocity/tools/trunk/velocity-tools-generic/src/main/resources/org/apache/velocity/tools/generic/tools.xml?view=markup). It includes all of the tools listed [below](#tools).

## Dependencies

The dependencies required for GenericTools vary somewhat depending on which tools you use, whether you will rely on core tool management infrastructure, and if so, how you choose to configure your toolbox.  More details can be found on the [dependencies chart](dependencies.html#GenericTools).

## Tools

+ [AlternatorTool](apidocs/org/apache/velocity/tools/generic/AlternatorTool.html) - For creating [Alternator](apidocs/org/apache/velocity/tools/generic/Alternator.html)s to easily alternate over a set of values.
+ [ClassTool](apidocs/org/apache/velocity/tools/generic/ClassTool.html) - For simplifying reflective lookup of information about Classes and their fields, methods and constructors.
+ [ContextTool](apidocs/org/apache/velocity/tools/generic/ContextTool.html) - For convenient access to Context data and meta-data.
+ [ConversionTool](apidocs/org/apache/velocity/tools/generic/ConversionTool.html) - For converting String values to richer object types.
+ [DateTool](apidocs/org/apache/velocity/tools/generic/DateTool.html) & [ComparisonDateTool](apidocs/org/apache/velocity/tools/generic/ComparisonDateTool.html) - For manipulating, formatting, and comparing dates.
+ [DisplayTool](apidocs/org/apache/velocity/tools/generic/DisplayTool.html) - For controlling display of references (e.g. truncating values, "pretty printing" lists, and displaying alternates when a reference is null).
+ [EscapeTool](apidocs/org/apache/velocity/tools/generic/EscapeTool.html) - For common escaping needs in Velocity templates (e.g. escaping html, xml, javascript etc.).
+ [FieldTool](apidocs/org/apache/velocity/tools/generic/FieldTool.html) - For (easy) access to static fields in a class, such as string constants.
+ [LoopTool](apidocs/org/apache/velocity/tools/generic/LoopTool.html) - A convenience tool to use with #foreach loops. It wraps a list with a custom iterator to provide greater control, allowing loops to end early, skip ahead and more.
+ [LinkTool](apidocs/org/apache/velocity/tools/generic/LinkTool.html) - For creating and manipulating URIs and URLs. The API for this tool is designed to closely resemble that of the VelocityView tool of the same name.
+ [ListTool](apidocs/org/apache/velocity/tools/generic/ListTool.html) - For working with arrays and lists, treats both transparently the same.
+ [MathTool](apidocs/org/apache/velocity/tools/generic/MathTool.html) - For performing math functions.
+ [NumberTool](apidocs/org/apache/velocity/tools/generic/NumberTool.html) - For formatting and converting numbers.
+ [RenderTool](apidocs/org/apache/velocity/tools/generic/RenderTool.html) - To evaluate and render arbitrary strings of VTL, including recursive rendering.
+ [ResourceTool](apidocs/org/apache/velocity/tools/generic/ResourceTool.html) - For simplified access to ResourceBundles for internationalization or other dynamic content needs.
+ [SortTool](apidocs/org/apache/velocity/tools/generic/SortTool.html) - Used to sort collections (or arrays, iterators, etc) on any arbitary set of properties exposed by the objects contained within the collection.
+ [XmlTool](apidocs/org/apache/velocity/tools/generic/XmlTool.html) - For reading/navigating XML files.  This uses dom4j under the covers and provides complete XPath support.