Class ConversionTool

  • Direct Known Subclasses:
    ValueParser

    @DefaultKey("convert")
    @SkipSetters
    public class ConversionTool
    extends LocaleConfig

    Utility class for easy conversion of String values to richer types.

     Template example(s):
       $convert.toNumber('12.6')   ->  12.6
       $convert.toInt('12.6')      ->  12
       $convert.toNumbers('12.6,42')  ->  [12.6, 42]
    
     Toolbox configuration:
     <tools>
       <toolbox scope="application">
         <tool class="org.apache.velocity.tools.generic.ConversionTool"
                  dateFormat="yyyy-MM-dd"/>
       </toolbox>
     </tools>
     

    This comes in very handy when parsing anything.

    Since:
    VelocityTools 2.0
    Version:
    $Revision: 932578 $ $Date: 2007-02-26 11:24:39 -0800 (Mon, 26 Feb 2007) $
    Author:
    Nathan Bubna
    • Constructor Summary

      Constructors 
      Constructor Description
      ConversionTool()  
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void configure​(ValueParser values)
      Does the actual configuration.
      java.lang.String getDateFormat()  
      java.lang.String getNumberFormat()  
      java.lang.String getStringsDelimiter()  
      boolean getStringsTrim()  
      protected java.lang.Boolean parseBoolean​(java.lang.String value)
      Converts a parameter value into a Boolean Sub-classes can override to allow for customized boolean parsing.
      java.util.Date parseDate​(java.lang.String value)
      Converts a string to an instance of Date, using the configured date parsing format, the configured default Locale, and the system's default TimeZone to parse it.
      java.util.Date parseDate​(java.lang.String value, java.lang.Object locale)
      Converts a string to an instance of Date using the configured date format and specified Locale to parse it.
      java.util.Date parseDate​(java.lang.String value, java.lang.String format)
      Converts a string to an instance of Date using the specified format,the configured default Locale, and the system's default TimeZone to parse it.
      java.util.Date parseDate​(java.lang.String value, java.lang.String format, java.lang.Object locale)
      Converts a string to an instance of Date using the specified format and Locale to parse it.
      java.util.Date parseDate​(java.lang.String value, java.lang.String format, java.lang.Object locale, java.util.TimeZone timezone)
      Converts a string to an instance of Date using the specified format, Locale, and TimeZone.
      protected java.util.Locale parseLocale​(java.lang.String value)
      Converts a String value into a Locale.
      java.lang.Number parseNumber​(java.lang.String value)
      Converts an object to an instance of Number using the format returned by getNumberFormat() and the default Locale if the object is not already an instance of Number.
      java.lang.Number parseNumber​(java.lang.String value, java.lang.Object locale)
      Converts an object to an instance of Number using the configured number format and the specified Locale.
      java.lang.Number parseNumber​(java.lang.String value, java.lang.String format)
      Converts an object to an instance of Number using the specified format and the Locale returned by LocaleConfig.getLocale().
      java.lang.Number parseNumber​(java.lang.String value, java.lang.String format, java.lang.Object locale)
      Converts an object to an instance of Number using the specified format and Locale.
      protected java.lang.String[] parseStringList​(java.lang.String value)
      Converts a single String value into an array of Strings by splitting it on the tool's set stringsDelimiter.
      protected void setDateFormat​(java.lang.String format)  
      protected void setNumberFormat​(java.lang.String format)  
      protected void setStringsDelimiter​(java.lang.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.
      java.lang.Boolean toBoolean​(java.lang.Object value)  
      java.lang.Boolean[] toBooleans​(java.lang.Object value)  
      java.lang.Boolean[] toBooleans​(java.util.Collection values)  
      java.util.Calendar toCalendar​(java.lang.Object value)  
      java.util.Calendar[] toCalendars​(java.lang.Object value)  
      java.util.Calendar[] toCalendars​(java.util.Collection values)  
      java.util.Date toDate​(java.lang.Object value)
      Converts an object to an instance of Date, when necessary using the configured date parsing format, the configured default Locale, and the system's default TimeZone to parse the string value of the specified object.
      java.util.Date[] toDates​(java.lang.Object value)  
      java.util.Date[] toDates​(java.util.Collection values)  
      java.lang.Double toDouble​(java.lang.Object value)  
      double[] toDoubles​(java.lang.Object value)  
      java.lang.Integer toInteger​(java.lang.Object value)  
      int[] toIntegers​(java.lang.Object value)  
      int[] toInts​(java.lang.Object value)  
      java.util.Locale toLocale​(java.lang.Object value)  
      java.util.Locale[] toLocales​(java.lang.Object value)  
      java.util.Locale[] toLocales​(java.util.Collection values)  
      java.lang.Number toNumber​(java.lang.Object value)  
      java.lang.Number[] toNumbers​(java.lang.Object value)  
      java.lang.Number[] toNumbers​(java.util.Collection values)  
      java.lang.String toString​(java.lang.Object value)
      Converts objects to String in a more Tools-ish way than String.valueOf(Object), especially with nulls, Arrays and Collections.
      java.lang.String[] toStrings​(java.lang.Object value)  
      • 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 java.lang.String STRINGS_DELIMITER_FORMAT_KEY
        See Also:
        Constant Field Values
      • STRINGS_TRIM_KEY

        public static final java.lang.String STRINGS_TRIM_KEY
        See Also:
        Constant Field Values
      • NUMBER_FORMAT_KEY

        public static final java.lang.String NUMBER_FORMAT_KEY
        See Also:
        Constant Field Values
      • DEFAULT_STRINGS_DELIMITER

        public static final java.lang.String DEFAULT_STRINGS_DELIMITER
        See Also:
        Constant Field Values
      • DEFAULT_NUMBER_FORMAT

        public static final java.lang.String DEFAULT_NUMBER_FORMAT
        See Also:
        Constant Field Values
      • DEFAULT_DATE_FORMAT

        public static final java.lang.String DEFAULT_DATE_FORMAT
        See Also:
        Constant Field Values
      • stringsDelimiter

        private java.lang.String stringsDelimiter
      • stringsTrim

        private boolean stringsTrim
      • numberFormat

        private java.lang.String numberFormat
      • dateFormat

        private java.lang.String dateFormat
    • Constructor Detail

      • ConversionTool

        public ConversionTool()
    • Method Detail

      • 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 LocaleConfig
      • setStringsDelimiter

        protected final void setStringsDelimiter​(java.lang.String stringsDelimiter)
        Sets the delimiter used for separating values in a single String value. The default string delimiter is a comma.
        See Also:
        parseStringList(java.lang.String)
      • getStringsDelimiter

        public final java.lang.String getStringsDelimiter()
      • setStringsTrim

        protected final void setStringsTrim​(boolean stringsTrim)
        Sets whether strings should be trimmed when separated from a delimited string value. The default is true.
        See Also:
        parseStringList(java.lang.String)
      • getStringsTrim

        public final boolean getStringsTrim()
      • setNumberFormat

        protected final void setNumberFormat​(java.lang.String format)
      • getNumberFormat

        public final java.lang.String getNumberFormat()
      • setDateFormat

        protected final void setDateFormat​(java.lang.String format)
      • getDateFormat

        public final java.lang.String getDateFormat()
      • toString

        public java.lang.String toString​(java.lang.Object value)
        Converts objects to String in a more Tools-ish way than String.valueOf(Object), especially with nulls, Arrays and Collections. Null returns null, Arrays and Collections return the toString(Object) of their first value, or null if they have no values.
        Parameters:
        value - the object to be turned into a String
        Returns:
        the string value of the object or null if the value is null or it is an array or collection whose first value is null
      • toBoolean

        public java.lang.Boolean toBoolean​(java.lang.Object value)
        Parameters:
        value - the object to be converted
        Returns:
        a Boolean object for the specified value or null if the value is null or the conversion failed
      • toInteger

        public java.lang.Integer toInteger​(java.lang.Object value)
        Parameters:
        value - the object to be converted
        Returns:
        a Integer for the specified value or null if the value is null or the conversion failed
      • toDouble

        public java.lang.Double toDouble​(java.lang.Object value)
        Parameters:
        value - the object to be converted
        Returns:
        a Double for the specified value or null if the value is null or the conversion failed
      • toNumber

        public java.lang.Number toNumber​(java.lang.Object value)
        Parameters:
        value - the object to be converted
        Returns:
        a Number for the specified value or null if the value is null or the conversion failed
      • toLocale

        public java.util.Locale toLocale​(java.lang.Object value)
        Parameters:
        value - the object to be converted
        Returns:
        a Locale for the specified value or null if the value is null or the conversion failed
      • toDate

        public java.util.Date toDate​(java.lang.Object value)
        Converts an object to an instance of Date, when necessary using the configured date parsing format, the configured default Locale, and the system's default TimeZone to parse the string value of the specified object.
        Parameters:
        value - the date to convert
        Returns:
        the object as a Date or null if no conversion is possible
      • toCalendar

        public java.util.Calendar toCalendar​(java.lang.Object value)
      • toStrings

        public java.lang.String[] toStrings​(java.lang.Object 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
      • toBooleans

        public java.lang.Boolean[] toBooleans​(java.lang.Object value)
        Parameters:
        value - the value to be converted
        Returns:
        an array of Boolean objects derived from the specified value, or null.
      • toBooleans

        public java.lang.Boolean[] toBooleans​(java.util.Collection values)
        Parameters:
        values - the collection of values to be converted
        Returns:
        an array of Boolean objects derived from the specified values, or null.
      • toNumbers

        public java.lang.Number[] toNumbers​(java.lang.Object value)
        Parameters:
        value - the value to be converted
        Returns:
        an array of Number objects derived from the specified value, or null.
      • toNumbers

        public java.lang.Number[] toNumbers​(java.util.Collection values)
        Parameters:
        values - the collection of values to be converted
        Returns:
        an array of Number objects derived from the specified values, or null.
      • toInts

        public int[] toInts​(java.lang.Object value)
        Parameters:
        value - the value to be converted
        Returns:
        an array of int values derived from the specified value, or null.
      • toIntegers

        public int[] toIntegers​(java.lang.Object value)
        Parameters:
        value - the value to be converted
        Returns:
        an array of int values derived from the specified value, or null.
      • toDoubles

        public double[] toDoubles​(java.lang.Object value)
        Parameters:
        value - the value to be converted
        Returns:
        an array of double values derived from the specified value, or null.
      • toLocales

        public java.util.Locale[] toLocales​(java.lang.Object value)
        Parameters:
        value - the value to be converted
        Returns:
        an array of Locale objects derived from the specified value, or null.
      • toLocales

        public java.util.Locale[] toLocales​(java.util.Collection values)
        Parameters:
        values - the collection of values to be converted
        Returns:
        an array of Locale objects derived from the specified values, or null.
      • toDates

        public java.util.Date[] toDates​(java.lang.Object value)
        Parameters:
        value - the value to be converted
        Returns:
        an array of Date objects derived from the specified value, or null.
      • toDates

        public java.util.Date[] toDates​(java.util.Collection values)
        Parameters:
        values - the collection of values to be converted
        Returns:
        an array of Date objects derived from the specified values, or null.
      • toCalendars

        public java.util.Calendar[] toCalendars​(java.lang.Object value)
        Parameters:
        value - the value to be converted
        Returns:
        an array of Calendar objects derived from the specified value, or null.
      • toCalendars

        public java.util.Calendar[] toCalendars​(java.util.Collection values)
        Parameters:
        values - the collection of values to be converted
        Returns:
        an array of Calendar objects derived from the specified values, or null.
      • parseBoolean

        protected java.lang.Boolean parseBoolean​(java.lang.String value)
        Converts a parameter value into a Boolean Sub-classes can override to allow for customized boolean parsing. (e.g. to handle "Yes/No" or "T/F")
        Parameters:
        value - the string to be parsed
        Returns:
        the value as a Boolean
      • parseStringList

        protected java.lang.String[] parseStringList​(java.lang.String value)
        Converts a single String value into an array of Strings by splitting it on the tool's set stringsDelimiter. The default stringsDelimiter is a comma, and by default, all strings parsed out are trimmed before returning.
      • parseLocale

        protected java.util.Locale parseLocale​(java.lang.String value)
        Converts a String value into a Locale.
      • parseNumber

        public java.lang.Number parseNumber​(java.lang.String value)
        Converts an object to an instance of Number using the format returned by getNumberFormat() and the default Locale if the object is not already an instance of Number.
        Parameters:
        value - the string to parse
        Returns:
        the string as a Number or null if no conversion is possible
      • parseNumber

        public java.lang.Number parseNumber​(java.lang.String value,
                                            java.lang.String format)
        Converts an object to an instance of Number using the specified format and the Locale returned by LocaleConfig.getLocale().
        Parameters:
        value - - the string to parse
        format - - the format the number is in
        Returns:
        the string as a Number or null if no conversion is possible
        See Also:
        parseNumber(String value, String format, Object locale)
      • parseNumber

        public java.lang.Number parseNumber​(java.lang.String value,
                                            java.lang.Object locale)
        Converts an object to an instance of Number using the configured number format and the specified Locale.
        Parameters:
        value - - the string to parse
        locale - - the Locale to use
        Returns:
        the string as a Number or null if no conversion is possible
        See Also:
        NumberFormat.parse(java.lang.String, java.text.ParsePosition)
      • parseNumber

        public java.lang.Number parseNumber​(java.lang.String value,
                                            java.lang.String format,
                                            java.lang.Object locale)
        Converts an object to an instance of Number using the specified format and Locale.
        Parameters:
        value - - the string to parse
        format - - the format the number is in
        locale - - the Locale to use
        Returns:
        the string as a Number or null if no conversion is possible
        See Also:
        NumberFormat.parse(java.lang.String, java.text.ParsePosition)
      • parseDate

        public java.util.Date parseDate​(java.lang.String value)
        Converts a string to an instance of Date, using the configured date parsing format, the configured default Locale, and the system's default TimeZone to parse it.
        Parameters:
        value - the date to convert
        Returns:
        the object as a Date or null if no conversion is possible
      • parseDate

        public java.util.Date parseDate​(java.lang.String value,
                                        java.lang.String format)
        Converts a string to an instance of Date using the specified format,the configured default Locale, and the system's default TimeZone to parse it.
        Parameters:
        value - - the date to convert
        format - - the format the date is in
        Returns:
        the string as a Date or null if no conversion is possible
        See Also:
        ConversionUtils.toDate(String str, String format, Locale locale, TimeZone timezone)
      • parseDate

        public java.util.Date parseDate​(java.lang.String value,
                                        java.lang.Object locale)
        Converts a string to an instance of Date using the configured date format and specified Locale to parse it.
        Parameters:
        value - - the date to convert
        locale - - the Locale to use
        Returns:
        the string as a Date or null if no conversion is possible
        See Also:
        SimpleDateFormat.parse(java.lang.String, java.text.ParsePosition)
      • parseDate

        public java.util.Date parseDate​(java.lang.String value,
                                        java.lang.String format,
                                        java.lang.Object locale)
        Converts a string to an instance of Date using the specified format and Locale to parse it.
        Parameters:
        value - - the date to convert
        format - - the format the date is in
        locale - - the Locale to use
        Returns:
        the string as a Date or null if no conversion is possible
        See Also:
        SimpleDateFormat.parse(java.lang.String, java.text.ParsePosition)
      • parseDate

        public java.util.Date parseDate​(java.lang.String value,
                                        java.lang.String format,
                                        java.lang.Object locale,
                                        java.util.TimeZone timezone)
        Converts a string to an instance of Date using the specified format, Locale, and TimeZone.
        Parameters:
        value - - the date to convert
        format - - the format the date is in
        locale - - the Locale to use
        timezone - - the TimeZone
        Returns:
        the string as a Date or null if no conversion is possible
        See Also:
        getDateFormat(), SimpleDateFormat.parse(java.lang.String, java.text.ParsePosition)