Class SortTool


  • @DefaultKey("sorter")
    public class SortTool
    extends java.lang.Object
    SortTool allows a user to sort a collection (or array, iterator, etc) on any arbitary set of properties exposed by the objects contained within the collection.

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

    The sort tool 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 1.2
    Version:
    $Id: SortTool.java 564672 2007-08-10 16:50:04Z nbubna $
    Author:
    S. Brett Sutton, Nathan Bubna
    • Constructor Summary

      Constructors 
      Constructor Description
      SortTool()  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected static java.lang.Comparable getComparable​(java.lang.Object object, java.lang.String property)
      Safely retrieves the comparable value for the specified property from the specified object.
      protected java.util.Collection internalSort​(java.util.List list, java.util.List properties)  
      java.util.Collection sort​(java.lang.Object[] array)  
      java.util.Collection sort​(java.lang.Object[] array, java.util.List properties)  
      java.util.Collection sort​(java.lang.Object object, java.lang.String property)
      Sorts the collection on a single property.
      java.util.Collection sort​(java.util.Collection collection)  
      java.util.Collection sort​(java.util.Collection collection, java.util.List properties)  
      java.util.Collection sort​(java.util.Map map)  
      java.util.Collection sort​(java.util.Map map, java.util.List properties)  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • SortTool

        public SortTool()
    • Method Detail

      • sort

        public java.util.Collection sort​(java.util.Collection collection)
      • sort

        public java.util.Collection sort​(java.lang.Object[] array)
      • sort

        public java.util.Collection sort​(java.util.Map map)
      • sort

        public java.util.Collection sort​(java.lang.Object object,
                                         java.lang.String property)
        Sorts the collection on a single property.
        Parameters:
        object - the collection to be sorted.
        property - the property to sort on.
      • sort

        public java.util.Collection sort​(java.util.Collection collection,
                                         java.util.List properties)
      • sort

        public java.util.Collection sort​(java.util.Map map,
                                         java.util.List properties)
      • sort

        public java.util.Collection sort​(java.lang.Object[] array,
                                         java.util.List properties)
      • internalSort

        protected java.util.Collection internalSort​(java.util.List list,
                                                    java.util.List properties)
      • getComparable

        protected static java.lang.Comparable getComparable​(java.lang.Object object,
                                                            java.lang.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.