Package org.apache.velocity.tools.generic

Class DateTool

  • Direct Known Subclasses:
    ComparisonDateTool
    @DefaultKey("date")
public class DateTool
extends FormatConfig
    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 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$ $Date$
    Author:
    Nathan Bubna

    • Constructor Detail

      • DateTool

        public DateTool()

    • 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 FormatConfig

      • setTimeZone

        protected void setTimeZone​(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 Date getSystemDate()
        Returns:
        the system's current time as a Date

      • getSystemCalendar

        public static final Calendar getSystemCalendar()
        Returns:
        the system's current time as a Calendar

      • getCalendar

        public 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 LocaleConfig.getLocale().
        See Also:
        Calendar.getInstance(TimeZone zone, Locale aLocale)

      • getYear

        public Integer getYear()
        Returns the year value of the date returned by getCalendar().
        Since:
        VelocityTools 1.2

      • getYear

        public Integer getYear​(Object date)
        Returns the year value of the specified date.
        Since:
        VelocityTools 1.2

      • getMonth

        public Integer getMonth()
        Returns the month value of the date returned by getCalendar().
        Since:
        VelocityTools 1.2

      • getMonth

        public Integer getMonth​(Object date)
        Returns the month value of the specified date.
        Since:
        VelocityTools 1.2

      • getDay

        public 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 Integer getDay​(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 Integer getValue​(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 Integer getValue​(Object field,
                        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 Integer getValue​(int field,
                        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 String get​(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)

      • format

        public String format​(String format,
                     Object obj,
                     Locale locale,
                     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

      • getDateFormat

        public DateFormat getDateFormat​(String format,
                                Locale locale,
                                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

        @Deprecated
protected DateFormat getDateFormat​(int dateStyle,
                                   int timeStyle,
                                   Locale locale,
                                   TimeZone timezone)
        Deprecated.
        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

        @Deprecated
protected int getStyleAsInt​(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

      • toLocalizedPattern

        public String toLocalizedPattern​(String format,
                                 Locale locale)
        Returns a localized date format pattern for the given format. SimpleDateFormat uses patterns that are based upon English words (such as Month = M, Day = d, and Year = y). When displaying a format pattern to readers of other languages, it is appropriate to display these patterns using their localized expectations. For instance, the date pattern yyyy-MM-dd should, for French speakers appear as "aaaa-MM-jj". SimpleDateFormat.toLocalizedPattern() provides this functionality, and this method merely calls that on an appropriately-constructed SimpleDateFormat object.
        Parameters:
        format - the custom or standard pattern to convert
        locale - the Locale to format for pattern for
        Returns:
        a format string appropriate for the specified Locale
        Since:
        VelocityTools 2.0