org.apache.velocity.tools.generic
Class DateTool

java.lang.Object
  org.apache.velocity.tools.generic.DateTool

Direct Known Subclasses:

ComparisonDateTool

public class DateTool
extends java.lang.Object

Tool for working with Date and Calendar in Velocity templates. It is useful for accessing and formatting the "current" date as well as for formatting arbitrary Date and Calendar objects. Also the tool can be used to retrieve DateFormat instances or make conversions to and from various date types.

 Example of formatting the "current" date:
  $date                         -> Oct 19, 2003 9:54:50 PM
  $date.long                    -> October 19, 2003 9:54:50 PM PDT
  $date.medium_time             -> 9:54:50 PM
  $date.full_date               -> Sunday, October 19, 2003
  $date.get('default','short')  -> Oct 19, 2003 9:54 PM
  $date.get('yyyy-M-d H:m:s')   -> 2003-10-19 21:54:50

 Example of formatting an arbitrary date:
  $myDate                        -> Tue Oct 07 03:14:50 PDT 2003
  $date.format('medium',$myDate) -> Oct 7, 2003 3:14:50 AM

 Example toolbox.xml config (if you want to use this with VelocityView):
 <tool>
   <key>date</key>
   <scope>application</scope>
   <class>org.apache.velocity.tools.generic.DateTool</class>
   <parameter name="format" value="yyyy-M-d"/>
 </tool>
 

The methods of this tool are highly interconnected, and overriding key methods provides an easy way to create subclasses that use a non-default format, calendar, locale, or timezone.

Since:

VelocityTools 1.0

Version:

$Revision: 509840 $ $Date: 2007-02-20 16:59:26 -0800 (Tue, 20 Feb 2007) $

Author:

Nathan Bubna

Field Summary

private boolean	configLocked
static java.lang.String	DEFAULT_FORMAT The default format to be used when none is specified.
static java.lang.String	DEFAULT_FORMAT_KEY The key used for specifying a default format via toolbox params.
static java.lang.String	DEFAULT_LOCALE_KEY The key used for specifying a default locale via toolbox params.
private java.lang.String	format
private java.util.Locale	locale
static java.lang.String	LOCK_CONFIG_KEY The key used for specifying whether or not to prevent templates from reconfiguring this tool.

Constructor Summary

DateTool()

Method Summary

void	configure(java.util.Map params) Looks for configuration values in the given params.
protected void	configure(ValueParser values) Does the actual configuration.
java.lang.String	format(java.lang.Object obj) Converts the specified object to a date and formats it according to the pattern or style returned by getFormat().
java.lang.String	format(java.lang.String format, java.lang.Object obj) Converts the specified object to a date and returns a formatted string representing that date in the locale returned by getLocale().
java.lang.String	format(java.lang.String format, java.lang.Object obj, java.util.Locale locale) Converts the specified object to a date and returns a formatted string representing that date in the specified Locale.
java.lang.String	format(java.lang.String format, java.lang.Object obj, java.util.Locale locale, java.util.TimeZone timezone) Returns a formatted string representing the specified date, Locale, and TimeZone.
java.lang.String	format(java.lang.String dateStyle, java.lang.String timeStyle, java.lang.Object obj) Returns the specified date as a string formatted according to the specified date and/or time styles.
java.lang.String	format(java.lang.String dateStyle, java.lang.String timeStyle, java.lang.Object obj, java.util.Locale locale) Returns the specified date as a string formatted according to the specified Locale and date and/or time styles.
java.lang.String	format(java.lang.String dateStyle, java.lang.String timeStyle, java.lang.Object obj, java.util.Locale locale, java.util.TimeZone timezone) Returns the specified date as a string formatted according to the specified Locale and date and/or time styles.
java.lang.String	get(java.lang.String format) Returns a formatted string representing the date returned by getDate().
java.lang.String	get(java.lang.String dateStyle, java.lang.String timeStyle) Returns a formatted string representing the date and/or time given by getDate() in standard, localized patterns.
java.util.Calendar	getCalendar() Returns a Calendar instance created using the timezone and locale returned by getTimeZone() and getLocale().
java.util.Date	getDate() Returns a Date derived from the result of getCalendar()
protected java.text.DateFormat	getDateFormat(int dateStyle, int timeStyle, java.util.Locale locale, java.util.TimeZone timezone) Returns a DateFormat instance for the specified time style, date style, Locale, and TimeZone.
java.text.DateFormat	getDateFormat(java.lang.String format, java.util.Locale locale, java.util.TimeZone timezone) Returns a DateFormat instance for the specified format, Locale, and TimeZone.
java.text.DateFormat	getDateFormat(java.lang.String dateStyle, java.lang.String timeStyle, java.util.Locale locale, java.util.TimeZone timezone) Returns a DateFormat instance for the specified date style, time style, Locale, and TimeZone.
java.lang.Integer	getDay() Returns the day (of the month) value of the date returned by getCalendar().
java.lang.Integer	getDay(java.lang.Object date) Returns the day (of the month) value for the specified date.
java.lang.String	getFormat() Return the pattern or style to be used for formatting dates when none is specified.
java.util.Locale	getLocale() This implementation returns the configured default locale.
java.lang.Integer	getMonth() Returns the month value of the date returned by getCalendar().
java.lang.Integer	getMonth(java.lang.Object date) Returns the month value of the specified date.
protected int	getStyleAsInt(java.lang.String style) Checks a string to see if it matches one of the standard DateFormat style patterns: FULL, LONG, MEDIUM, SHORT, or DEFAULT.
static java.util.Calendar	getSystemCalendar()
static java.util.Date	getSystemDate()
static long	getSystemTime()
java.util.TimeZone	getTimeZone() This implementation returns the default TimeZone.
java.lang.Integer	getValue(int field, java.lang.Object date) Returns the specified value of the specified date, or null if the field or date is invalid.
java.lang.Integer	getValue(java.lang.Object field) Return the specified value of the date returned by getCalendar() or null if the field is invalid.
java.lang.Integer	getValue(java.lang.Object field, java.lang.Object date) Returns the specified value of the specified date, or null if the field or date is invalid.
java.lang.Integer	getYear() Returns the year value of the date returned by getCalendar().
java.lang.Integer	getYear(java.lang.Object date) Returns the year value of the specified date.
protected void	setFormat(java.lang.String format) Sets the default format for this instance.
protected void	setLocale(java.util.Locale locale) Sets the default locale for this instance.
java.util.Calendar	toCalendar(java.lang.Object obj) Converts an object to an instance of Calendar using the locale returned by getLocale() if necessary.
java.util.Calendar	toCalendar(java.lang.Object obj, java.util.Locale locale) Converts an object to an instance of Calendar using the locale returned by getLocale() if necessary.
java.util.Date	toDate(java.lang.Object obj) Converts an object to an instance of Date using the format returned by getFormat(),the Locale returned by getLocale(), and the TimeZone returned by getTimeZone() if the object is not already an instance of Date, Calendar, or Long.
java.util.Date	toDate(java.lang.String format, java.lang.Object obj) Converts an object to an instance of Date using the specified format,the Locale returned by getLocale(), and the TimeZone returned by getTimeZone() if the object is not already an instance of Date, Calendar, or Long.
java.util.Date	toDate(java.lang.String format, java.lang.Object obj, java.util.Locale locale) Converts an object to an instance of Date using the specified format and Locale if the object is not already an instance of Date, Calendar, or Long.
java.util.Date	toDate(java.lang.String format, java.lang.Object obj, java.util.Locale locale, java.util.TimeZone timezone) Converts an object to an instance of Date using the specified format, Locale, and TimeZone if the object is not already an instance of Date, Calendar, or Long.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_FORMAT

public static final java.lang.String DEFAULT_FORMAT

The default format to be used when none is specified.

Since:

VelocityTools 1.1

See Also:

Constant Field Values

DEFAULT_FORMAT_KEY

public static final java.lang.String DEFAULT_FORMAT_KEY

The key used for specifying a default format via toolbox params.

Since:

VelocityTools 1.3

See Also:

Constant Field Values

DEFAULT_LOCALE_KEY

public static final java.lang.String DEFAULT_LOCALE_KEY

The key used for specifying a default locale via toolbox params.

Since:

VelocityTools 1.4

See Also:

Constant Field Values

LOCK_CONFIG_KEY

public static final java.lang.String LOCK_CONFIG_KEY

The key used for specifying whether or not to prevent templates from reconfiguring this tool. The default is true.

Since:

VelocityTools 1.4

See Also:

Constant Field Values

format

private java.lang.String format

locale

private java.util.Locale locale

configLocked

private boolean configLocked

Constructor Detail

DateTool

public DateTool()

Method Detail

configure

public void configure(java.util.Map params)

Looks for configuration values in the given params.

Since:

VelocityTools 1.3

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.

Since:

VelocityTools 1.4

getSystemTime

public static final long getSystemTime()

Returns:

the system's current time as the number of milliseconds elapsed since January 1, 1970, 00:00:00 GMT.

getSystemDate

public static final java.util.Date getSystemDate()

Returns:

the system's current time as a Date

getSystemCalendar

public static final java.util.Calendar getSystemCalendar()

Returns:

the system's current time as a Calendar

getLocale

public java.util.Locale getLocale()

This implementation returns the configured default locale. Subclasses may override this to return alternate locales. Please note that doing so will affect all formatting methods where no locale is specified in the parameters.

Returns:

the default Locale

setLocale

protected void setLocale(java.util.Locale locale)

Sets the default locale for this instance. This is protected, because templates ought not to be using it; that would not be threadsafe so far as templates are concerned.

Since:

VelocityTools 1.4

getTimeZone

public java.util.TimeZone getTimeZone()

This implementation returns the default TimeZone. Subclasses may override this to return alternate timezones. Please note that doing so will affect all formatting methods where no timezone is specified in the parameters.

Returns:

the default TimeZone

getDate

public java.util.Date getDate()

Returns a Date derived from the result of getCalendar()

Returns:

a Date derived from the result of getCalendar()

getCalendar

public java.util.Calendar getCalendar()

Returns a Calendar instance created using the timezone and locale returned by getTimeZone() and getLocale(). This allows subclasses to easily override the default locale and timezone used by this tool.

Sub-classes may override this method to return a Calendar instance not based on the system date. Doing so will also cause the getDate(), get(String), get(String,String), and toString() methods to return dates equivalent to the Calendar returned by this method, because those methods return values derived from the result of this method.

Returns:

a Calendar instance created using the results of getTimeZone() and getLocale().

See Also:

Calendar.getInstance(TimeZone zone, Locale aLocale)

getFormat

public java.lang.String getFormat()

Return the pattern or style to be used for formatting dates when none is specified. This implementation gives a 'default' date-time format. Subclasses may override this to provide a different default format.

This can now be configured via the toolbox definition. Add a <parameter name="format" value="short"/> to your date tool configuration.

Since:

VelocityTools 1.1

setFormat

protected void setFormat(java.lang.String format)

Sets the default format for this instance. This is protected, because templates ought not to be using it; that would not be threadsafe so far as templates are concerned.

Since:

VelocityTools 1.3

getYear

public java.lang.Integer getYear()

Returns the year value of the date returned by getCalendar().

Since:

VelocityTools 1.2

getYear

public java.lang.Integer getYear(java.lang.Object date)

Returns the year value of the specified date.

Since:

VelocityTools 1.2

getMonth

public java.lang.Integer getMonth()

Returns the month value of the date returned by getCalendar().

Since:

VelocityTools 1.2

getMonth

public java.lang.Integer getMonth(java.lang.Object date)

Returns the month value of the specified date.

Since:

VelocityTools 1.2

getDay

public java.lang.Integer getDay()

Returns the day (of the month) value of the date returned by getCalendar().

NOTE: Unlike java.util.Date, this returns the day of the month. It is equivalent to Date.getDate() and Calendar.get(Calendar.DAY_OF_MONTH). We could not call this method getDate() because that already exists in this class with a different function.

Since:

VelocityTools 1.2

getDay

public java.lang.Integer getDay(java.lang.Object date)

Returns the day (of the month) value for the specified date.

NOTE: Unlike java.util.Date, this returns the day of the month. It is equivalent to Date.getDate() and Calendar.get(Calendar.DAY_OF_MONTH). We could not call this method getDate() because that already exists in this class with a different function.

Since:

VelocityTools 1.2

getValue

public java.lang.Integer getValue(java.lang.Object field)

Return the specified value of the date returned by getCalendar() or null if the field is invalid.

Since:

VelocityTools 1.2

getValue

public java.lang.Integer getValue(java.lang.Object field,
                                  java.lang.Object date)

Returns the specified value of the specified date, or null if the field or date is invalid. The field may be an Integer or it may be the name of the field as a String.

Parameters:

field - the corresponding Integer value or String name of the desired value

date - the date/calendar from which the field value will be taken

Since:

VelocityTools 1.2

getValue

public java.lang.Integer getValue(int field,
                                  java.lang.Object date)

Returns the specified value of the specified date, or null if the field or date is invalid.

Parameters:

field - the int for the desired field (e.g. Calendar.MONTH)

date - the date/calendar from which the field value will be taken

Since:

VelocityTools 1.2

get

public java.lang.String get(java.lang.String format)

Returns a formatted string representing the date returned by getDate(). In its default implementation, this method allows you to retrieve the current date in standard formats by simply doing things like $date.medium or $date.full. If you want only the date or time portion you can specify that along with the standard formats. (e.g. $date.medium_date or $date.short_time) More complex or custom formats can be retrieved by using the full method syntax. (e.g. $date.get('E, MMMM d'))

Parameters:

format - the formatting instructions

Returns:

a formatted representation of the date returned by getDate()

Since:

VelocityTools 1.1

See Also:

format(String format, Object obj, Locale locale, TimeZone timezone)

get

public java.lang.String get(java.lang.String dateStyle,
                            java.lang.String timeStyle)

Returns a formatted string representing the date and/or time given by getDate() in standard, localized patterns.

Parameters:

dateStyle - the style pattern for the date

timeStyle - the style pattern for the time

Returns:

a formatted representation of the date returned by getDate()

Since:

VelocityTools 1.1

See Also:

DateFormat, format(String dateStyle, String timeStyle, Object obj, Locale locale, TimeZone timezone)

format

public java.lang.String format(java.lang.Object obj)

Converts the specified object to a date and formats it according to the pattern or style returned by getFormat().

Parameters:

obj - the date object to be formatted

Returns:

the specified date formatted as a string

Since:

VelocityTools 1.1

See Also:

format(String format, Object obj, Locale locale, TimeZone timezone)

format

public java.lang.String format(java.lang.String format,
                               java.lang.Object obj)

Converts the specified object to a date and returns a formatted string representing that date in the locale returned by getLocale().

Parameters:

format - the formatting instructions

obj - the date object to be formatted

Returns:

a formatted string for this locale representing the specified date or null if the parameters are invalid

See Also:

format(String format, Object obj, Locale locale, TimeZone timezone)

format

public java.lang.String format(java.lang.String format,
                               java.lang.Object obj,
                               java.util.Locale locale)

Converts the specified object to a date and returns a formatted string representing that date in the specified Locale.

Parameters:

format - the formatting instructions

obj - the date object to be formatted

locale - the locale to be used when formatting

Returns:

the given date as a formatted string

See Also:

format(String format, Object obj, Locale locale, TimeZone timezone)

format

public java.lang.String format(java.lang.String format,
                               java.lang.Object obj,
                               java.util.Locale locale,
                               java.util.TimeZone timezone)

Returns a formatted string representing the specified date, Locale, and TimeZone.

The specified format may be a standard style pattern ('full', 'long', 'medium', 'short', or 'default').

You may also specify that you want only the date or time portion be appending '_date' or '_time' respectively to the standard style pattern. (e.g. 'full_date' or 'long_time')

If the format fits neither of these patterns, then the output will be formatted according to the symbols defined by SimpleDateFormat:

   Symbol   Meaning                 Presentation        Example
   ------   -------                 ------------        -------
   G        era designator          (Text)              AD
   y        year                    (Number)            1996
   M        month in year           (Text & Number)     July & 07
   d        day in month            (Number)            10
   h        hour in am/pm (1~12)    (Number)            12
   H        hour in day (0~23)      (Number)            0
   m        minute in hour          (Number)            30
   s        second in minute        (Number)            55
   S        millisecond             (Number)            978
   E        day in week             (Text)              Tuesday
   D        day in year             (Number)            189
   F        day of week in month    (Number)            2 (2nd Wed in July)
   w        week in year            (Number)            27
   W        week in month           (Number)            2
   a        am/pm marker            (Text)              PM
   k        hour in day (1~24)      (Number)            24
   K        hour in am/pm (0~11)    (Number)            0
   z        time zone               (Text)              Pacific Standard Time
   '        escape for text         (Delimiter)
   ''       single quote            (Literal)           '

   Examples: "E, MMMM d" will result in "Tue, July 24"
             "EEE, M-d (H:m)" will result in "Tuesday, 7-24 (14:12)"
 

Parameters:

format - the custom or standard pattern to be used

obj - the date to format

locale - the Locale to format the date for

timezone - the TimeZone to be used when formatting

Returns:

a formatted string representing the specified date or null if the parameters are invalid

Since:

VelocityTools 1.1

format

public java.lang.String format(java.lang.String dateStyle,
                               java.lang.String timeStyle,
                               java.lang.Object obj)

Returns the specified date as a string formatted according to the specified date and/or time styles.

Parameters:

dateStyle - the style pattern for the date

timeStyle - the style pattern for the time

obj - the date to be formatted

Returns:

a formatted representation of the given date

Since:

VelocityTools 1.1

See Also:

format(String dateStyle, String timeStyle, Object obj, Locale locale, TimeZone timezone)

format

public java.lang.String format(java.lang.String dateStyle,
                               java.lang.String timeStyle,
                               java.lang.Object obj,
                               java.util.Locale locale)

Returns the specified date as a string formatted according to the specified Locale and date and/or time styles.

Parameters:

dateStyle - the style pattern for the date

timeStyle - the style pattern for the time

obj - the date to be formatted

locale - the Locale to be used for formatting the date

Returns:

a formatted representation of the given date

Since:

VelocityTools 1.1

See Also:

format(String dateStyle, String timeStyle, Object obj, Locale locale, TimeZone timezone)

format

public java.lang.String format(java.lang.String dateStyle,
                               java.lang.String timeStyle,
                               java.lang.Object obj,
                               java.util.Locale locale,
                               java.util.TimeZone timezone)

Returns the specified date as a string formatted according to the specified Locale and date and/or time styles.

Parameters:

dateStyle - the style pattern for the date

timeStyle - the style pattern for the time

obj - the date to be formatted

locale - the Locale to be used for formatting the date

timezone - the TimeZone the date should be formatted for

Returns:

a formatted representation of the given date

Since:

VelocityTools 1.1

See Also:

DateFormat, format(String dateStyle, String timeStyle, Object obj, Locale locale, TimeZone timezone)

getDateFormat

public java.text.DateFormat getDateFormat(java.lang.String format,
                                          java.util.Locale locale,
                                          java.util.TimeZone timezone)

Returns a DateFormat instance for the specified format, Locale, and TimeZone. If the format specified is a standard style pattern, then a date-time instance will be returned with both the date and time styles set to the specified style. If it is a custom format, then a customized SimpleDateFormat will be returned.

Parameters:

format - the custom or standard formatting pattern to be used

locale - the Locale to be used

timezone - the TimeZone to be used

Returns:

an instance of DateFormat

Since:

VelocityTools 1.1

See Also:

SimpleDateFormat, DateFormat

getDateFormat

public java.text.DateFormat getDateFormat(java.lang.String dateStyle,
                                          java.lang.String timeStyle,
                                          java.util.Locale locale,
                                          java.util.TimeZone timezone)

Returns a DateFormat instance for the specified date style, time style, Locale, and TimeZone.

Parameters:

dateStyle - the date style

timeStyle - the time style

locale - the Locale to be used

timezone - the TimeZone to be used

Returns:

an instance of DateFormat

Since:

VelocityTools 1.1

See Also:

getDateFormat(int timeStyle, int dateStyle, Locale locale, TimeZone timezone)

getDateFormat

protected java.text.DateFormat getDateFormat(int dateStyle,
                                             int timeStyle,
                                             java.util.Locale locale,
                                             java.util.TimeZone timezone)

Returns a DateFormat instance for the specified time style, date style, Locale, and TimeZone.

Parameters:

dateStyle - the date style (date will be ignored if this is less than zero and the date style is not)

timeStyle - the time style (time will be ignored if this is less than zero and the date style is not)

locale - the Locale to be used

timezone - the TimeZone to be used

Returns:

an instance of DateFormat or null if an instance cannot be constructed with the given parameters

Since:

VelocityTools 1.1

getStyleAsInt

protected int getStyleAsInt(java.lang.String style)

Checks a string to see if it matches one of the standard DateFormat style patterns: FULL, LONG, MEDIUM, SHORT, or DEFAULT. If it does, it will return the integer constant for that pattern. If not, it will return -1.

Parameters:

style - the string to be checked

Returns:

the int identifying the style pattern

Since:

VelocityTools 1.1

See Also:

DateFormat

toDate

public java.util.Date toDate(java.lang.Object obj)

Converts an object to an instance of Date using the format returned by getFormat(),the Locale returned by getLocale(), and the TimeZone returned by getTimeZone() if the object is not already an instance of Date, Calendar, or Long.

Parameters:

obj - the date to convert

Returns:

the object as a Date or null if no conversion is possible

toDate

public java.util.Date toDate(java.lang.String format,
                             java.lang.Object obj)

Converts an object to an instance of Date using the specified format,the Locale returned by getLocale(), and the TimeZone returned by getTimeZone() if the object is not already an instance of Date, Calendar, or Long.

Parameters:

format - - the format the date is in

obj - - the date to convert

Returns:

the object as a Date or null if no conversion is possible

See Also:

toDate(String format, Object obj, Locale locale)

toDate

public java.util.Date toDate(java.lang.String format,
                             java.lang.Object obj,
                             java.util.Locale locale)

Converts an object to an instance of Date using the specified format and Locale if the object is not already an instance of Date, Calendar, or Long.

Parameters:

format - - the format the date is in

obj - - the date to convert

locale - - the Locale

Returns:

the object as a Date or null if no conversion is possible

See Also:

SimpleDateFormat.parse(java.lang.String, java.text.ParsePosition)

toDate

public java.util.Date toDate(java.lang.String format,
                             java.lang.Object obj,
                             java.util.Locale locale,
                             java.util.TimeZone timezone)

Converts an object to an instance of Date using the specified format, Locale, and TimeZone if the object is not already an instance of Date, Calendar, or Long.

Parameters:

format - - the format the date is in

obj - - the date to convert

locale - - the Locale

timezone - - the TimeZone

Returns:

the object as a Date or null if no conversion is possible

See Also:

getDateFormat(java.lang.String, java.util.Locale, java.util.TimeZone), SimpleDateFormat.parse(java.lang.String, java.text.ParsePosition)

toCalendar

public java.util.Calendar toCalendar(java.lang.Object obj)

Converts an object to an instance of Calendar using the locale returned by getLocale() if necessary.

Parameters:

obj - the date to convert

Returns:

the converted date

See Also:

toCalendar(Object obj, Locale locale)

toCalendar

public java.util.Calendar toCalendar(java.lang.Object obj,
                                     java.util.Locale locale)

Converts an object to an instance of Calendar using the locale returned by getLocale() if necessary.

Parameters:

obj - the date to convert

locale - the locale used

Returns:

the converted date

See Also:

toDate(String format, Object obj, Locale locale), Calendar

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

Returns:

the result of getDate() formatted according to the result of getFormat().

See Also:

format(String format, Object obj)