Class ComparisonDateTool

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
org.apache.velocity.tools.generic.ComparisonDateTool
All Implemented Interfaces:
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:

  • Field Details

  • Constructor Details

    • ComparisonDateTool

      public ComparisonDateTool()

  • Method Details

    • 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 String getText(String key, 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(Object then)
      Returns a ComparisonDateTool.Comparison between the result of DateTool.getCalendar() and the 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:
      then - The date in question
      Returns:
      ComparisonDateTool.Comparison object

    • whenIs

      public ComparisonDateTool.Comparison whenIs(Object now, 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(Object now, 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(Object now, 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(Object now, 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