org.apache.velocity.tools.generic
Class ConversionTool

java.lang.Object
  org.apache.velocity.tools.generic.SafeConfig
      org.apache.velocity.tools.generic.LocaleConfig
          org.apache.velocity.tools.generic.ConversionTool

Direct Known Subclasses:

ValueParser

@DefaultKey(value="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

Field Summary

static java.lang.String	DATE_FORMAT_KEY
private java.lang.String	dateFormat
static java.lang.String	DEFAULT_DATE_FORMAT
static java.lang.String	DEFAULT_NUMBER_FORMAT
static java.lang.String	DEFAULT_STRINGS_DELIMITER
static boolean	DEFAULT_STRINGS_TRIM
static java.lang.String	NUMBER_FORMAT_KEY
private java.lang.String	numberFormat
static java.lang.String	STRINGS_DELIMITER_FORMAT_KEY
static java.lang.String	STRINGS_TRIM_KEY
private java.lang.String	stringsDelimiter
private boolean	stringsTrim

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

DEFAULT_LOCALE

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

LOCK_CONFIG_KEY, OLD_LOCK_CONFIG_KEY, SAFE_MODE_KEY

Constructor Summary

ConversionTool()

Method Summary

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.util.Collection values)
java.lang.Boolean[]	toBooleans(java.lang.Object value)
java.util.Calendar	toCalendar(java.lang.Object value)
java.util.Calendar[]	toCalendars(java.util.Collection values)
java.util.Calendar[]	toCalendars(java.lang.Object value)
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.util.Collection values)
java.util.Date[]	toDates(java.lang.Object value)
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.util.Collection values)
java.util.Locale[]	toLocales(java.lang.Object value)
java.lang.Number	toNumber(java.lang.Object value)
java.lang.Number[]	toNumbers(java.util.Collection values)
java.lang.Number[]	toNumbers(java.lang.Object value)
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 org.apache.velocity.tools.generic.LocaleConfig

getLocale, setLocale

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

configure, 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 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

DATE_FORMAT_KEY

public static final java.lang.String DATE_FORMAT_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_STRINGS_TRIM

public static final boolean DEFAULT_STRINGS_TRIM

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)