Package org.apache.velocity.tools.generic

Class ComparisonDateTool

  • All Implemented Interfaces:
    java.io.Serializable
    @ValidScope("application")
public class ComparisonDateTool
extends DateTool

    Tool for comparing Date and Calendar values in Velocity templates. This is a subclass of DateTool and thus provides all the functionality of that tool and augments it with the ability to find the relationship between any date and the current date, or between any two dates. This comparison can result in either a textual representation of the relationship (e.g. "3 weeks, 2 days ago", "tomorrow", or "3 hrs away") or the value of a specific time unit may be requested. When using the textual representations, you can configure the tool to use alternate resource bundles and to skip over units you do not want to be included.

     Example of formatting the "current" date:
  $date.whenIs('2005-07-04')                -> 1 year ago
  $date.whenIs('2007-02-15').full           -> 1 year 32 weeks 2 days 17 hours 38 minutes 44 seconds 178 milliseconds ago
  $date.whenIs('2007-02-15').days           -> -730
  $date.whenIs($date.calendar)              -> now
  $date.whenIs('2005-07-04', '2005-07-04')  -> same time
  $date.difference('2005-07-04','2005-07-04')      -> 0 milliseconds
  $date.difference('2005-07-04','2007-02-15').abbr -> 1 yr

 Example tools.xml config (if you want to use this with VelocityView):
 <tools>
   <toolbox scope="application">
     <tool class="org.apache.velocity.tools.generic.ComparisonDateTool"
              format="yyyy-MM-dd" depth="1" skip="month,week,millisecond"
              bundle="org.apache.velocity.tools.generic.times"/>
   </toolbox>
 </tools>
    Since:
    VelocityTools 1.4
    Version:
    $Revision$ $Date: 2006-04-04 12:35:17 -0700 (Tue, 04 Apr 2006) $
    Author:
    Nathan Bubna, Chris Townsen
    See Also:
    Serialized Form

    • Field Detail

      • MILLIS_PER_SECOND

        public static final long MILLIS_PER_SECOND
        The number of milliseconds in a second.
        See Also:
        Constant Field Values

      • MILLIS_PER_MINUTE

        public static final long MILLIS_PER_MINUTE
        The number of millseconds in a minute.
        See Also:
        Constant Field Values

      • MILLIS_PER_HOUR

        public static final long MILLIS_PER_HOUR
        The number of milliseconds in an hour.
        See Also:
        Constant Field Values

      • MILLIS_PER_DAY

        public static final long MILLIS_PER_DAY
        The number of milliseconds in a day.
        See Also:
        Constant Field Values

      • MILLIS_PER_WEEK

        public static final long MILLIS_PER_WEEK
        The number of milliseconds in a week.
        See Also:
        Constant Field Values

      • MILLIS_PER_MONTH

        public static final long MILLIS_PER_MONTH
        An approximation of the number of milliseconds in a month.
        See Also:
        Constant Field Values

      • MILLIS_PER_YEAR

        public static final long MILLIS_PER_YEAR
        An approximation of the number of milliseconds in a year.
        See Also:
        Constant Field Values

      • BUNDLE_NAME_KEY

        public static final java.lang.String BUNDLE_NAME_KEY
        The key used for specifying a default locale via toolbox params.
        See Also:
        Constant Field Values

      • DEPTH_KEY

        public static final java.lang.String DEPTH_KEY
        The key used for specifying a different default depth via toolbox params.
        See Also:
        Constant Field Values

      • SKIPPED_UNITS_KEY

        public static final java.lang.String SKIPPED_UNITS_KEY
        The key used for specifying time units to be skipped over.
        See Also:
        Constant Field Values

      • DEFAULT_BUNDLE_NAME

        public static final java.lang.String DEFAULT_BUNDLE_NAME
        The default path of the relative format resource bundles.
        See Also:
        Constant Field Values

      • MILLISECOND_KEY

        protected static final java.lang.String MILLISECOND_KEY
        See Also:
        Constant Field Values

      • TIME_UNITS

        protected static final java.util.Map TIME_UNITS
        Array of all time unit message keys to their millisecond conversion factor.

      • CALENDAR_FIELDS

        protected static final int[] CALENDAR_FIELDS

      • FIELD_MAXIMA

        protected static final int[] FIELD_MAXIMA

      • UNIT_KEYS

        protected static final java.lang.String[] UNIT_KEYS

    • Constructor Detail

      • ComparisonDateTool

        public ComparisonDateTool()

    • Method Detail

      • configure

        protected void configure​(ValueParser values)
        Calls the superclass implementation, then looks for a bundle name and any time units to be skipped.
        Overrides:
        configure in class DateTool
        Parameters:
        values - configuration values

      • getText

        protected java.lang.String getText​(java.lang.String key,
                                   java.util.Locale locale)
        Retrieves the specified text resource.
        Parameters:
        key - key
        locale - locale
        Returns:
        text resource

      • toYears

        public static long toYears​(long ms)
        Returns the number of whole Years in the specified number of milliseconds.
        Parameters:
        ms - milliseconds
        Returns:
        years

      • toMonths

        public static long toMonths​(long ms)
        Returns the number of whole Months in the specified number of milliseconds.
        Parameters:
        ms - milliseconds
        Returns:
        months

      • toWeeks

        public static long toWeeks​(long ms)
        Returns the number of whole Weeks in the specified number of milliseconds.
        Parameters:
        ms - milliseconds
        Returns:
        weeks

      • toDays

        public static long toDays​(long ms)
        Returns the number of whole Days in the specified number of milliseconds.
        Parameters:
        ms - milliseconds
        Returns:
        days

      • toHours

        public static long toHours​(long ms)
        Returns the number of whole Hours in the specified number of milliseconds.
        Parameters:
        ms - milliseconds
        Returns:
        hours

      • toMinutes

        public static long toMinutes​(long ms)
        Returns the number of whole Minutes in the specified number of milliseconds.
        Parameters:
        ms - milliseconds
        Returns:
        minutes

      • toSeconds

        public static long toSeconds​(long ms)
        Returns the number of whole Seconds in the specified number of milliseconds.
        Parameters:
        ms - milliseconds
        Returns:
        seconds

      • whenIs

        public ComparisonDateTool.Comparison whenIs​(java.lang.Object now,
                                            java.lang.Object then)
        Returns a ComparisonDateTool.Comparison between the second specified date and the first specified date. The default rendering of that Comparison will be the largest unit difference between the dates followed by a description of their relative position.
        Parameters:
        now - The date to use as representative of "now"
        then - The date in question
        Returns:
        ComparisonDateTool.Comparison object

      • difference

        public ComparisonDateTool.Comparison difference​(java.lang.Object now,
                                                java.lang.Object then)
        Returns a ComparisonDateTool.Comparison between the result of the second specified date and the first specified date. The default rendering of that Comparison will be the largest unit difference between the dates.
        Parameters:
        now - The date to use as representative of "now"
        then - The secondary date
        Returns:
        ComparisonDateTool.Comparison object

      • timespan

        public ComparisonDateTool.Comparison timespan​(java.lang.Object now,
                                              java.lang.Object then)
        Returns a ComparisonDateTool.Comparison between the result of the second specified date and the first specified date. The default rendering of that Comparison will be the decreasing sequence of bygone time units between the dates.
        Parameters:
        now - The date to use as representative of "now"
        then - The secondary date
        Returns:
        ComparisonDateTool.Comparison object

      • compare

        protected ComparisonDateTool.Comparison compare​(java.lang.Object now,
                                                java.lang.Object then,
                                                int type)
        Internal comparison method.
        Parameters:
        now - The date to use as representative of "now"
        then - The secondary date
        type - Difference type
        Returns:
        ComparisonDateTool.Comparison object