Package org.apache.velocity.tools.generic

Class DateTool

  • All Implemented Interfaces:
    java.io.Serializable
    Direct Known Subclasses:
    ComparisonDateTool
    @DefaultKey("date")
public class DateTool
extends FormatConfig
implements java.io.Serializable

    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.

    Possible formats include:

    • 'short', 'medium', 'long', 'full' (from DateFormat, optionally suffixed by '_date' or '_time' to get a date-only or time-only format
    • 'iso' for extended ISO 8601 without time zone (ex: '2016-11-24T10:27:30'), optionally suffixed by '_date' or '_time' to get a date-only or time-only format
    • 'iso_tz', like 'iso' with time zone offset (ex: '2016-11-24T10:27:30+01:00'), optionally suffixed by '_time' to get a time-only format ('10:27:30+01:00')
    • 'intl', like 'iso' but with a space separator between date and time (ex: '2016-11-24 10:27:30'), optionally suffixed by '_date' or '_time' to get a date-only or time-only format
    • 'intl_tz', like 'intl' but with the time zone short id suffixed after another space (ex: '2016-11-24 10:27:30 CET'), optionally suffixed by '_time' to get a time-only format ('10:27:30+01:00')
    • a custom format, as specified in SimpleDateFormat

    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
  $date.iso                     -> 2003-10-19T21:54:50-07:00
  $date.iso_tz_time             -> 21:54:50-07:00
  $date.intl_tz                 -> 2003-10-19 21:54:50 CET

 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>

    Should you need to use several formats, you can either use explicit formats by means of the toDate(format, date) method, or you can declare several date tool instances with different formats.

    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
    See Also:
    Serialized Form

    • Constructor Summary

      Constructors 
      Constructor Description
      DateTool()  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete 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 by FormatConfig.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 LocaleConfig.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()
      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.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.lang.Integer getDay()  
      java.lang.Integer getDay​(java.lang.Object date)  
      java.lang.Integer getMonth()  
      java.lang.Integer getMonth​(java.lang.Object date)  
      static java.util.Calendar getSystemCalendar()  
      static java.util.Date getSystemDate()  
      static long getSystemTime()  
      java.util.TimeZone getTimeZone()
      Returns the configured TimeZone.
      java.lang.Integer getValue​(int field, java.lang.Object date)  
      java.lang.Integer getValue​(java.lang.Object field)  
      java.lang.Integer getValue​(java.lang.Object field, java.lang.Object date)  
      java.lang.Integer getYear()  
      java.lang.Integer getYear​(java.lang.Object date)  
      protected void setTimeZone​(java.util.TimeZone timezone)
      Sets time zone
      java.util.Calendar toCalendar​(java.lang.Object obj)
      Converts an object to an instance of Calendar using the format returned by FormatConfig.getFormat(), the locale returned by LocaleConfig.getLocale() and the time zone returned by getTimeZone().
      java.util.Calendar toCalendar​(java.lang.Object obj, java.util.Locale locale)
      Converts an object to an instance of Calendar using the provided locale, the format returned by FormatConfig.getFormat() and the time zone returned by getTimeZone().
      java.util.Calendar toCalendar​(java.lang.String format, java.lang.Object obj)
      Converts an object to an instance of Calendar using the provided format, the locale returned by LocaleConfig.getLocale() and the time zone returned by getTimeZone().
      java.util.Calendar toCalendar​(java.lang.String format, java.lang.Object obj, java.util.Locale locale)
      Converts an object to an instance of Calendar using the provided format and locale, and the time zone returned by getTimeZone().
      java.util.Calendar toCalendar​(java.lang.String format, java.lang.Object obj, java.util.Locale locale, java.util.TimeZone timezone)
      Converts an object to an instance of Calendar using the provided format, locale and time zone.
      java.util.Date toDate​(java.lang.Object obj)
      Converts an object to an instance of Date using the format returned by FormatConfig.getFormat(),the Locale returned by LocaleConfig.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.Object obj, java.util.Locale locale)
      Converts an object to an instance of Date using the format returned by FormatConfig.getFormat(),the provided Locale, 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.Object obj, java.util.Locale locale, java.util.TimeZone timezone)
      Converts an object to an instance of Date using the format returned by FormatConfig.getFormat(),the provided Locale, and TimeZone 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 LocaleConfig.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 toLocalizedPattern​(java.lang.String format, java.util.Locale locale)
      Returns a localized date format pattern for the given format.
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • 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

    • 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
        Parameters:
        values - configuration values

      • setTimeZone

        protected void setTimeZone​(java.util.TimeZone timezone)
        Sets time zone
        Parameters:
        timezone - time zone

      • 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 configured TimeZone. Default value is from TimeZone.getDefault().
        Returns:
        the configured 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 LocaleConfig.getLocale().
        See Also:
        Calendar.getInstance(TimeZone zone, Locale aLocale)

      • 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)
        Parameters:
        date - target 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)
        Parameters:
        date - target 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)
        Parameters:
        date - target 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)
        Parameters:
        field - target field
        Returns:
        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)
        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
        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.
        Since:
        VelocityTools 1.2

      • getValue

        public java.lang.Integer getValue​(int field,
                                  java.lang.Object date)
        Parameters:
        field - the int for the desired field (e.g. Calendar.MONTH)
        date - the date/calendar from which the field value will be taken
        Returns:
        the specified value of the specified date, or null if the field or date is invalid.
        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)

      • 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 LocaleConfig.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') or extended style pattern ('iso', 'iso_tz', 'intl', 'intl_tz').

        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', 'long_time', 'intl_date')

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

           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:
        ConversionUtils.getDateFormat(int,int,Locale,TimeZone)

      • toDate

        public java.util.Date toDate​(java.lang.Object obj)
        Converts an object to an instance of Date using the format returned by FormatConfig.getFormat(),the Locale returned by LocaleConfig.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.Object obj,
                             java.util.Locale locale)
        Converts an object to an instance of Date using the format returned by FormatConfig.getFormat(),the provided Locale, 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
        locale - the Locale
        Returns:
        the object as a Date or null if no conversion is possible

      • toDate

        public java.util.Date toDate​(java.lang.Object obj,
                             java.util.Locale locale,
                             java.util.TimeZone timezone)
        Converts an object to an instance of Date using the format returned by FormatConfig.getFormat(),the provided Locale, and TimeZone if the object is not already an instance of Date, Calendar, or Long.
        Parameters:
        obj - the date to convert
        locale - the Locale
        timezone - - the TimeZone
        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 LocaleConfig.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.String format,
                                     java.lang.Object obj,
                                     java.util.Locale locale)
        Converts an object to an instance of Calendar using the provided format and locale, and the time zone returned by getTimeZone().
        Parameters:
        format - the provided format
        obj - the date to convert
        locale - the locale used
        Returns:
        the converted date
        See Also:
        toDate(String format, Object obj, Locale locale), Calendar

      • toCalendar

        public java.util.Calendar toCalendar​(java.lang.String format,
                                     java.lang.Object obj,
                                     java.util.Locale locale,
                                     java.util.TimeZone timezone)
        Converts an object to an instance of Calendar using the provided format, locale and time zone.
        Parameters:
        format - the provided format
        obj - the date to convert
        locale - the locale used
        timezone - the time zone used
        Returns:
        the converted date
        See Also:
        toDate(String format, Object obj, Locale locale), Calendar

      • toLocalizedPattern

        public java.lang.String toLocalizedPattern​(java.lang.String format,
                                           java.util.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