CollectionTool (VelocityTools 3.0 API)

java.lang.Object
- org.apache.velocity.tools.generic.SafeConfig
- - org.apache.velocity.tools.generic.CollectionTool

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

SortTool
```
@DefaultKey(value="collection")
public class CollectionTool
extends SafeConfig
implements Serializable
```
CollectionTool allows a user to sort a collection (or array, iterator, etc) on any arbitrary set of properties exposed by the objects contained within the collection, and to generate arrays by splitting strings.

The sort functionality is specifically designed to use within a #foreach but you may find other uses for it.

The sort methods can handle all of the collection types supported by #foreach and the same constraints apply as well as the following. Every object in the collection must support the set of properties selected to sort on. Each property which is to be sorted on must return one of the follow:
- Primitive type: e.g. int, char, long etc
- Standard Object: e.g. String, Integer, Long etc
- Object which implements the Comparable interface.
During the sort operation all properties are compared by calling compareTo() with the exception of Strings for which compareToIgnoreCase() is called.

The sort is performed by calling Collections.sort() after marshalling the collection to sort into an appropriate collection type. The original collection will not be re-ordered; a new list containing the sorted elements will always be returned.

The tool is used as follows:
```
 Single Property Sort
 #foreach($obj in $sorter.sort($objects, "name"))
   $obj.name Ordinal= $obj.ordinal
 #end
 End

 Multiple Property Sort
 #foreach($obj in $sorter.sort($objects, ["name", "ordinal"]))
   $obj.name, $obj.ordinal
 #end
 End
 
```
The sort method takes two parameters, a collection and a property name or an array of property names. The property names and corresponding methods must conform to java bean standards since commons-beanutils is used to extract the property values.

By default the sort tool sorts ascending, you can override this by adding a sort type suffix to any property name.

The supported suffixes are:
```
 For ascending
 :asc
 For descending
 :desc

 Example
 #foreach($obj in $sorter.sort($objects, ["name:asc", "ordinal:desc"]))
   $obj.name, $obj.ordinal
 #end
 
```
This will sort first by Name in ascending order and then by Ordinal in descending order, of course you could have left the :asc off of the 'Name' property as ascending is always the default.

Example tools.xml config (if you want to use this with VelocityView):
```
 <tools>
   <toolbox scope="application">
     <tool class="org.apache.velocity.tools.generic.SortTool"/>
   </toolbox>
 </tools>
 
```
Since:

VelocityTools 3.0

Version:

$Id: CollectionTool.java 1842514 2018-10-01 16:09:11Z cbrisson $

Author:

S. Brett Sutton, Nathan Bubna

See Also:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class CollectionTool.PropertiesComparator
Does all of the comparisons

Nested Classes
Modifier and Type	Class and Description
`static class`	`CollectionTool.PropertiesComparator` Does all of the comparisons

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`DEFAULT_STRINGS_DELIMITER`
`static boolean`	`DEFAULT_STRINGS_TRIM`
`static String`	`STRINGS_DELIMITER_FORMAT_KEY`
`static String`	`STRINGS_TRIM_KEY`

Fields inherited from class org.apache.velocity.tools.generic.SafeConfig
LOCK_CONFIG_KEY, log, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY

Constructor Summary

Constructors
Constructor and Description

CollectionTool()

Constructors
Constructor and Description
`CollectionTool()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`configure(ValueParser values)` Does the actual configuration.
`protected static Comparable`	`getComparable(Object object, String property)` Safely retrieves the comparable value for the specified property from the specified object.
`String`	`getStringsDelimiter()` Gets the configured strings delimiter
`boolean`	`getStringsTrim()` Gets whether to trim strings
`protected Collection`	`internalSort(List list, List properties)` Internal sorting method.
`protected void`	`setStringsDelimiter(String stringsDelimiter)` Sets the delimiter used for separating values in a single String value.
`protected void`	`setStringsTrim(boolean stringsTrim)` Sets whether strings should be trimmed when separated from a delimited string value.
`Collection`	`sort(Collection collection)` Sort a collection
`<T> Collection<T>`	`sort(Collection<T> c, Comparator<T> comparator)` Sorts a Collection using a Comparator.
`Collection`	`sort(Collection collection, List properties)` Sorts the collection on several properties.
`Collection`	`sort(Map map)` Sort map values
`<T> Collection<T>`	`sort(Map<?,T> map, Comparator<T> comparator)` Sorts a Map's values using a Comparator.
`Collection`	`sort(Map map, List properties)` Sorts map values on several properties.
`Collection`	`sort(Object object)` Sort a collection, array or map
`Collection`	`sort(Object[] array)` Sort an array
`Collection`	`sort(Object[] array, List properties)` Sorts array on several properties.
`Collection<?>`	`sort(Object o, Comparator<?> comparator)` Sorts a Collection (or array, or Map's values) using a Comparator.
`Collection`	`sort(Object object, String property)` Sorts the collection on a single property.
`<T> T[]`	`sort(T[] a, Comparator<T> comparator)` Sorts an array using a Comparator.
`String[]`	`split(String value)`

Methods inherited from class org.apache.velocity.tools.generic.SafeConfig
configure, getLog, initLogger, isConfigLocked, isSafeMode, setLockConfig, setSafeMode

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - STRINGS_DELIMITER_FORMAT_KEY
```
public static final String STRINGS_DELIMITER_FORMAT_KEY
```
    See Also:
    
    Constant Field Values
  - STRINGS_TRIM_KEY
```
public static final String STRINGS_TRIM_KEY
```
    See Also:
    
    Constant Field Values
  - DEFAULT_STRINGS_DELIMITER
```
public static final String DEFAULT_STRINGS_DELIMITER
```
    See Also:
    
    Constant Field Values
  - DEFAULT_STRINGS_TRIM
```
public static final boolean DEFAULT_STRINGS_TRIM
```
    See Also:
    
    Constant Field Values
- Constructor Detail
  - CollectionTool
```
public CollectionTool()
```
- Method Detail
  - setStringsDelimiter
```
protected final void setStringsDelimiter(String stringsDelimiter)
```
    Sets the delimiter used for separating values in a single String value. The default string delimiter is a comma.
    
    Parameters:
    
    stringsDelimiter - strings delimiter
    
    See Also:
    
    split(String)
  - getStringsDelimiter
```
public final String getStringsDelimiter()
```
    Gets the configured strings delimiter
    
    Returns:
    
    strings delimiter
  - setStringsTrim
```
protected final void setStringsTrim(boolean stringsTrim)
```
    Sets whether strings should be trimmed when separated from a delimited string value. The default is true.
    
    Parameters:
    
    stringsTrim - flag value
    
    See Also:
    
    split(String)
  - getStringsTrim
```
public final boolean getStringsTrim()
```
    Gets whether to trim strings
    
    Returns:
    
    whether to trim strings
  - configure
```
protected void configure(ValueParser values)
```
    Does the actual configuration. This is protected, so subclasses may share the same ValueParser and call configure at any time, while preventing templates from doing so when configure(Map) is locked.
    
    Overrides:
    
    configure in class SafeConfig
    
    Parameters:
    
    values - configuration values
  - split
```
public String[] split(String value)
```
    Parameters:
    
    value - the value to be converted
    
    Returns:
    
    an array of String objects containing all of the values derived from the specified array, Collection, or delimited String
  - sort
```
public <T> Collection<T> sort(Collection<T> c,
                              Comparator<T> comparator)
```
    Sorts a Collection using a Comparator. A defensive copy is made of the Collection beforehand, so the original Collection is left untouched and null elements filtered out.
    
    Type Parameters:
    
    T - collection content class
    
    Parameters:
    
    c - The Collection to sort.
    
    comparator - The comparator to use for sorting.
    
    Returns:
    
    A copy of the original Collection, sorted using the supplied Comparator.
    
    Since:
    
    VelocityTools 2.0.1
  - sort
```
public <T> T[] sort(T[] a,
                    Comparator<T> comparator)
```
    Sorts an array using a Comparator. A defensive copy is made of the array beforehand, so the original array is left untouched and null elements filtered out.
    
    Type Parameters:
    
    T - array content class
    
    Parameters:
    
    a - The array to sort.
    
    comparator - The comparator to use for sorting.
    
    Returns:
    
    A copy of the original array, sorted using the supplied Comparator.
    
    Since:
    
    VelocityTools 2.0.1
  - sort
```
public <T> Collection<T> sort(Map<?,T> map,
                              Comparator<T> comparator)
```
    Sorts a Map's values using a Comparator. A defensive copy is made of the values beforehand, so the original Map is left untouched.
    
    Type Parameters:
    
    T - Map values class
    
    Parameters:
    
    map - The Map whose values should be sorted.
    
    comparator - The comparator to use for sorting.
    
    Returns:
    
    A copy of the original Map's values, sorted using the supplied Comparator.
    
    Since:
    
    VelocityTools 2.0.1
  - sort
```
public Collection<?> sort(Object o,
                          Comparator<?> comparator)
```
    Sorts a Collection (or array, or Map's values) using a Comparator. A defensive copy is made of the original beforehand, so the original is left untouched. Unsupported collection objects result in a null return value.
    
    Parameters:
    
    o - The Collection to sort.
    
    comparator - The comparator to use for sorting.
    
    Returns:
    
    A copy of the original Collection, sorted using the supplied Comparator.
    
    Since:
    
    VelocityTools 2.0.1
  - sort
```
public Collection sort(Collection collection)
```
    Sort a collection
    
    Parameters:
    
    collection - collection to sort, left unchanged
    
    Returns:
    
    new sorted collection
  - sort
```
public Collection sort(Object[] array)
```
    Sort an array
    
    Parameters:
    
    array - array to sort, left unchanged
    
    Returns:
    
    new sorted collection
  - sort
```
public Collection sort(Map map)
```
    Sort map values
    
    Parameters:
    
    map - map to sort
    
    Returns:
    
    new sorted collection of map values
  - sort
```
public Collection sort(Object object)
```
    Sort a collection, array or map
    
    Parameters:
    
    object - collection, array or map to sort
    
    Returns:
    
    new sorted collection, or null of object type is not supported
  - sort
```
public Collection sort(Object object,
                       String property)
```
    Sorts the collection on a single property.
    
    Parameters:
    
    object - the collection to be sorted, left unchanged.
    
    property - the property to sort on.
    
    Returns:
    
    new collection, sorted.
  - sort
```
public Collection sort(Collection collection,
                       List properties)
```
    Sorts the collection on several properties.
    
    Parameters:
    
    collection - the collection to be sorted, left unchanged.
    
    properties - the properties to sort on.
    
    Returns:
    
    new collection, sorted.
  - sort
```
public Collection sort(Map map,
                       List properties)
```
    Sorts map values on several properties.
    
    Parameters:
    
    map - the map to be sorted, left unchanged.
    
    properties - the properties to sort on.
    
    Returns:
    
    new collection, sorted.
  - sort
```
public Collection sort(Object[] array,
                       List properties)
```
    Sorts array on several properties.
    
    Parameters:
    
    array - array to be sorted, left unchanged.
    
    properties - the properties to sort on.
    
    Returns:
    
    new collection, sorted.
  - internalSort
```
protected Collection internalSort(List list,
                                  List properties)
```
    Internal sorting method.
    
    Parameters:
    
    list - values to sort.
    
    properties - the properties to sort on.
    
    Returns:
    
    new collection, sorted.
  - getComparable
```
protected static Comparable getComparable(Object object,
                                          String property)
```
    Safely retrieves the comparable value for the specified property from the specified object. Subclasses that wish to perform more advanced, efficient, or just different property retrieval methods should override this method to do so.
    
    Parameters:
    
    object - target object
    
    property - target property
    
    Returns:
    
    comparable

Class CollectionTool

Nested Class Summary

Field Summary

Fields inherited from class org.apache.velocity.tools.generic.SafeConfig

Constructor Summary

Method Summary

Methods inherited from class org.apache.velocity.tools.generic.SafeConfig

Methods inherited from class java.lang.Object

Field Detail

STRINGS_DELIMITER_FORMAT_KEY

STRINGS_TRIM_KEY

DEFAULT_STRINGS_DELIMITER

DEFAULT_STRINGS_TRIM

Constructor Detail

CollectionTool

Method Detail

setStringsDelimiter

getStringsDelimiter

setStringsTrim

getStringsTrim

configure

split

sort

sort

sort

sort

sort

sort

sort

sort

sort

sort

sort

sort

internalSort

getComparable