Class DateTool
- Direct Known Subclasses:
ComparisonDateTool
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 tools.xml config (if you want to use this with VelocityView): <tools> <toolbox scope="application"> <tool class="org.apache.velocity.tools.generic.DateTool" format="yyyy-MM-dd"/> </toolbox> </tools>
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: 719489 $ $Date: 2008-11-20 22:05:11 -0800 (Thu, 20 Nov 2008) $
- Author:
- Nathan Bubna
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
Deprecated.static final String
Deprecated.private TimeZone
static final String
The key used for specifying a default timezone via tool configuration.Fields inherited from class org.apache.velocity.tools.generic.FormatConfig
DEFAULT_FORMAT, FORMAT_KEY
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
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprotected void
configure
(ValueParser values) Does the actual configuration.Converts the specified object to a date and formats it according to the pattern or style returned byFormatConfig.getFormat()
.Converts the specified object to a date and returns a formatted string representing that date in the locale returned byLocaleConfig.getLocale()
.Converts the specified object to a date and returns a formatted string representing that date in the specifiedLocale
.Returns the specified date as a string formatted according to the specified date and/or time styles.Returns the specified date as a string formatted according to the specifiedLocale
and date and/or time styles.Returns the specified date as a string formatted according to the specifiedLocale
and date and/or time styles.Returns a formatted string representing the date returned bygetDate()
.Returns a formatted string representing the date and/or time given bygetDate()
in standard, localized patterns.Returns aCalendar
instance created using the timezone and locale returned by getTimeZone() and getLocale().getDate()
Returns aDate
derived from the result ofgetCalendar()
protected DateFormat
getDateFormat
(int dateStyle, int timeStyle, Locale locale, TimeZone timezone) Deprecated.getDateFormat
(String dateStyle, String timeStyle, Locale locale, TimeZone timezone) getDateFormat
(String format, Locale locale, TimeZone timezone) getDay()
Returns the day (of the month) value of the date returned bygetCalendar()
.Returns the day (of the month) value for the specified date.getMonth()
Returns the month value of the date returned bygetCalendar()
.Returns the month value of the specified date.protected int
getStyleAsInt
(String style) Deprecated.static final Calendar
static final Date
static final long
Returns the configuredTimeZone
.Returns the specified value of the specified date, or null if the field or date is invalid.Return the specified value of the date returned bygetCalendar()
or null if the field is invalid.Returns the specified value of the specified date, or null if the field or date is invalid.getYear()
Returns the year value of the date returned bygetCalendar()
.Returns the year value of the specified date.protected void
setTimeZone
(TimeZone timezone) toCalendar
(Object obj) Converts an object to an instance ofCalendar
using the locale returned byLocaleConfig.getLocale()
if necessary.toCalendar
(Object obj, Locale locale) Converts an object to an instance ofCalendar
using the locale returned byLocaleConfig.getLocale()
if necessary.Converts an object to an instance ofDate
using the format returned byFormatConfig.getFormat()
,theLocale
returned byLocaleConfig.getLocale()
, and theTimeZone
returned bygetTimeZone()
if the object is not already an instance of Date, Calendar, or Long.Converts an object to an instance ofDate
using the specified format,theLocale
returned byLocaleConfig.getLocale()
, and theTimeZone
returned bygetTimeZone()
if the object is not already an instance of Date, Calendar, or Long.toString()
Methods inherited from class org.apache.velocity.tools.generic.FormatConfig
getFormat, setFormat
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
-
Field Details
-
DEFAULT_FORMAT_KEY
Deprecated.- See Also:
-
DEFAULT_LOCALE_KEY
Deprecated.- See Also:
-
TIMEZONE_KEY
The key used for specifying a default timezone via tool configuration.- See Also:
-
timezone
-
-
Constructor Details
-
DateTool
public DateTool()
-
-
Method Details
-
configure
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 classFormatConfig
-
setTimeZone
-
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
- Returns:
- the system's current time as a
Date
-
getSystemCalendar
- Returns:
- the system's current time as a
Calendar
-
getTimeZone
Returns the configuredTimeZone
. Default value is fromTimeZone.getDefault()
.- Returns:
- the configured
TimeZone
-
getDate
Returns aDate
derived from the result ofgetCalendar()
- Returns:
- a
Date
derived from the result ofgetCalendar()
-
getCalendar
Returns aCalendar
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 ofgetTimeZone()
andLocaleConfig.getLocale()
. - See Also:
-
getYear
Returns the year value of the date returned bygetCalendar()
.- Since:
- VelocityTools 1.2
-
getYear
Returns the year value of the specified date.- Since:
- VelocityTools 1.2
-
getMonth
Returns the month value of the date returned bygetCalendar()
.- Since:
- VelocityTools 1.2
-
getMonth
Returns the month value of the specified date.- Since:
- VelocityTools 1.2
-
getDay
Returns the day (of the month) value of the date returned bygetCalendar()
.
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
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
Return the specified value of the date returned bygetCalendar()
or null if the field is invalid.- Since:
- VelocityTools 1.2
-
getValue
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 valuedate
- the date/calendar from which the field value will be taken- Since:
- VelocityTools 1.2
-
getValue
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
Returns a formatted string representing the date returned bygetDate()
. 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:
-
get
Returns a formatted string representing the date and/or time given bygetDate()
in standard, localized patterns.- Parameters:
dateStyle
- the style pattern for the datetimeStyle
- the style pattern for the time- Returns:
- a formatted representation of the date returned by
getDate()
- Since:
- VelocityTools 1.1
- See Also:
-
format
Converts the specified object to a date and formats it according to the pattern or style returned byFormatConfig.getFormat()
.- Parameters:
obj
- the date object to be formatted- Returns:
- the specified date formatted as a string
- Since:
- VelocityTools 1.1
- See Also:
-
format
Converts the specified object to a date and returns a formatted string representing that date in the locale returned byLocaleConfig.getLocale()
.- Parameters:
format
- the formatting instructionsobj
- 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
Converts the specified object to a date and returns a formatted string representing that date in the specifiedLocale
.- Parameters:
format
- the formatting instructionsobj
- the date object to be formattedlocale
- the locale to be used when formatting- Returns:
- the given date as a formatted string
- See Also:
-
format
Returns a formatted string representing the specified date,Locale
, andTimeZone
.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 usedobj
- the date to formatlocale
- theLocale
to format the date fortimezone
- theTimeZone
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
Returns the specified date as a string formatted according to the specified date and/or time styles.- Parameters:
dateStyle
- the style pattern for the datetimeStyle
- the style pattern for the timeobj
- the date to be formatted- Returns:
- a formatted representation of the given date
- Since:
- VelocityTools 1.1
- See Also:
-
format
Returns the specified date as a string formatted according to the specifiedLocale
and date and/or time styles.- Parameters:
dateStyle
- the style pattern for the datetimeStyle
- the style pattern for the timeobj
- the date to be formattedlocale
- theLocale
to be used for formatting the date- Returns:
- a formatted representation of the given date
- Since:
- VelocityTools 1.1
- See Also:
-
format
public String format(String dateStyle, String timeStyle, Object obj, Locale locale, TimeZone timezone) Returns the specified date as a string formatted according to the specifiedLocale
and date and/or time styles.- Parameters:
dateStyle
- the style pattern for the datetimeStyle
- the style pattern for the timeobj
- the date to be formattedlocale
- theLocale
to be used for formatting the datetimezone
- theTimeZone
the date should be formatted for- Returns:
- a formatted representation of the given date
- Since:
- VelocityTools 1.1
- See Also:
-
getDateFormat
Returns aDateFormat
instance for the specified format,Locale
, andTimeZone
. 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 customizedSimpleDateFormat
will be returned.- Parameters:
format
- the custom or standard formatting pattern to be usedlocale
- theLocale
to be usedtimezone
- theTimeZone
to be used- Returns:
- an instance of
DateFormat
- Since:
- VelocityTools 1.1
- See Also:
-
getDateFormat
public DateFormat getDateFormat(String dateStyle, String timeStyle, Locale locale, TimeZone timezone) - Parameters:
dateStyle
- the date styletimeStyle
- the time stylelocale
- theLocale
to be usedtimezone
- theTimeZone
to be used- Returns:
- an instance of
DateFormat
- Since:
- VelocityTools 1.1
- See Also:
-
getDateFormat
@Deprecated protected DateFormat getDateFormat(int dateStyle, int timeStyle, Locale locale, TimeZone timezone) Deprecated.- 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
- theLocale
to be usedtimezone
- theTimeZone
to be used- Returns:
- an instance of
DateFormat
ornull
if an instance cannot be constructed with the given parameters - Since:
- VelocityTools 1.1
-
getStyleAsInt
Deprecated.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:
-
toDate
Converts an object to an instance ofDate
using the format returned byFormatConfig.getFormat()
,theLocale
returned byLocaleConfig.getLocale()
, and theTimeZone
returned bygetTimeZone()
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
ornull
if no conversion is possible
-
toDate
Converts an object to an instance ofDate
using the specified format,theLocale
returned byLocaleConfig.getLocale()
, and theTimeZone
returned bygetTimeZone()
if the object is not already an instance of Date, Calendar, or Long.- Parameters:
format
- - the format the date is inobj
- - the date to convert- Returns:
- the object as a
Date
ornull
if no conversion is possible - See Also:
-
toDate
Converts an object to an instance ofDate
using the specified format andLocale
if the object is not already an instance of Date, Calendar, or Long. -
toDate
Converts an object to an instance ofDate
using the specified format,Locale
, andTimeZone
if the object is not already an instance of Date, Calendar, or Long. -
toCalendar
Converts an object to an instance ofCalendar
using the locale returned byLocaleConfig.getLocale()
if necessary.- Parameters:
obj
- the date to convert- Returns:
- the converted date
- See Also:
-
toCalendar
Converts an object to an instance ofCalendar
using the locale returned byLocaleConfig.getLocale()
if necessary.- Parameters:
obj
- the date to convertlocale
- the locale used- Returns:
- the converted date
- See Also:
-
toString
- Overrides:
toString
in classObject
- Returns:
- the result of
getDate()
formatted according to the result ofFormatConfig.getFormat()
. - See Also:
-