Class DateTool
- java.lang.Object
-
- org.apache.velocity.tools.generic.SafeConfig
-
- org.apache.velocity.tools.generic.LocaleConfig
-
- org.apache.velocity.tools.generic.FormatConfig
-
- org.apache.velocity.tools.generic.DateTool
-
- Direct Known Subclasses:
ComparisonDateTool
@DefaultKey("date") public class DateTool extends FormatConfig
Tool for working withDate
andCalendar
in Velocity templates. It is useful for accessing and formatting the "current" date as well as for formatting arbitraryDate
andCalendar
objects. Also the tool can be used to retrieveDateFormat
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
Fields Modifier and Type Field Description static java.lang.String
DEFAULT_FORMAT_KEY
Deprecated.static java.lang.String
DEFAULT_LOCALE_KEY
Deprecated.private java.util.TimeZone
timezone
static java.lang.String
TIMEZONE_KEY
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 Constructor Description DateTool()
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description 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 byFormatConfig.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 byLocaleConfig.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 specifiedLocale
.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
, andTimeZone
.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 specifiedLocale
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 specifiedLocale
and date and/or time styles.java.lang.String
get(java.lang.String format)
Returns a formatted string representing the date returned bygetDate()
.java.lang.String
get(java.lang.String dateStyle, java.lang.String timeStyle)
Returns a formatted string representing the date and/or time given bygetDate()
in standard, localized patterns.java.util.Calendar
getCalendar()
Returns aCalendar
instance created using the timezone and locale returned by getTimeZone() and getLocale().java.util.Date
getDate()
Returns aDate
derived from the result ofgetCalendar()
protected java.text.DateFormat
getDateFormat(int dateStyle, int timeStyle, java.util.Locale locale, java.util.TimeZone timezone)
Deprecated.java.text.DateFormat
getDateFormat(java.lang.String dateStyle, java.lang.String timeStyle, java.util.Locale locale, java.util.TimeZone timezone)
Returns aDateFormat
instance for the specified date style, time style,Locale
, andTimeZone
.java.text.DateFormat
getDateFormat(java.lang.String format, java.util.Locale locale, java.util.TimeZone timezone)
Returns aDateFormat
instance for the specified format,Locale
, andTimeZone
.java.lang.Integer
getDay()
Returns the day (of the month) value of the date returned bygetCalendar()
.java.lang.Integer
getDay(java.lang.Object date)
Returns the day (of the month) value for the specified date.java.lang.Integer
getMonth()
Returns the month value of the date returned bygetCalendar()
.java.lang.Integer
getMonth(java.lang.Object date)
Returns the month value of the specified date.protected int
getStyleAsInt(java.lang.String style)
Deprecated.static java.util.Calendar
getSystemCalendar()
static java.util.Date
getSystemDate()
static long
getSystemTime()
java.util.TimeZone
getTimeZone()
Returns the configuredTimeZone
.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 bygetCalendar()
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 bygetCalendar()
.java.lang.Integer
getYear(java.lang.Object date)
Returns the year value of the specified date.protected void
setTimeZone(java.util.TimeZone timezone)
java.util.Calendar
toCalendar(java.lang.Object obj)
Converts an object to an instance ofCalendar
using the locale returned byLocaleConfig.getLocale()
if necessary.java.util.Calendar
toCalendar(java.lang.Object obj, java.util.Locale locale)
Converts an object to an instance ofCalendar
using the locale returned byLocaleConfig.getLocale()
if necessary.java.util.Date
toDate(java.lang.Object obj)
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.java.util.Date
toDate(java.lang.String format, java.lang.Object obj)
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.java.util.Date
toDate(java.lang.String format, java.lang.Object obj, java.util.Locale locale)
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.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 ofDate
using the specified format,Locale
, andTimeZone
if the object is not already an instance of Date, Calendar, or Long.java.lang.String
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 Detail
-
DEFAULT_FORMAT_KEY
@Deprecated public static final java.lang.String DEFAULT_FORMAT_KEY
Deprecated.- See Also:
- Constant Field Values
-
DEFAULT_LOCALE_KEY
@Deprecated public static final java.lang.String DEFAULT_LOCALE_KEY
Deprecated.- See Also:
- Constant Field Values
-
TIMEZONE_KEY
public static final java.lang.String TIMEZONE_KEY
The key used for specifying a default timezone via tool configuration.- See Also:
- Constant Field Values
-
timezone
private java.util.TimeZone timezone
-
-
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 classFormatConfig
-
setTimeZone
protected void setTimeZone(java.util.TimeZone timezone)
-
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
-
getTimeZone
public java.util.TimeZone getTimeZone()
Returns the configuredTimeZone
. Default value is fromTimeZone.getDefault()
.- Returns:
- the configured
TimeZone
-
getDate
public java.util.Date getDate()
Returns aDate
derived from the result ofgetCalendar()
- Returns:
- a
Date
derived from the result ofgetCalendar()
-
getCalendar
public java.util.Calendar 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:
Calendar.getInstance(TimeZone zone, Locale aLocale)
-
getYear
public java.lang.Integer getYear()
Returns the year value of the date returned bygetCalendar()
.- 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 bygetCalendar()
.- 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 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
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 bygetCalendar()
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 valuedate
- 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 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:
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 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:
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 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(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 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(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 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(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
, 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
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 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(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 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(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 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:
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 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:
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 aDateFormat
instance for the specified date style, time style,Locale
, andTimeZone
.- 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(int timeStyle, int dateStyle, Locale locale, TimeZone timezone)
-
getDateFormat
@Deprecated protected java.text.DateFormat getDateFormat(int dateStyle, int timeStyle, java.util.Locale locale, java.util.TimeZone timezone)
Deprecated.Returns aDateFormat
instance for the specified time style, date style,Locale
, andTimeZone
.- 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 protected int getStyleAsInt(java.lang.String style)
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:
DateFormat
-
toDate
public java.util.Date toDate(java.lang.Object obj)
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
public java.util.Date toDate(java.lang.String format, java.lang.Object obj)
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(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 ofDate
using the specified format andLocale
if the object is not already an instance of Date, Calendar, or Long.- Parameters:
format
- - the format the date is inobj
- - the date to convertlocale
- - theLocale
- Returns:
- the object as a
Date
ornull
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 ofDate
using the specified format,Locale
, andTimeZone
if the object is not already an instance of Date, Calendar, or Long.- Parameters:
format
- - the format the date is inobj
- - the date to convertlocale
- - theLocale
timezone
- - theTimeZone
- Returns:
- the object as a
Date
ornull
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 ofCalendar
using the locale returned byLocaleConfig.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 ofCalendar
using the locale returned byLocaleConfig.getLocale()
if necessary.- Parameters:
obj
- the date to convertlocale
- 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 classjava.lang.Object
- Returns:
- the result of
getDate()
formatted according to the result ofFormatConfig.getFormat()
. - See Also:
format(String format, Object obj)
-
-