org.apache.velocity.tools.generic

## 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(value="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

### Nested Class Summary

Nested Classes
`class` `ComparisonDateTool.Comparison`

### Field Summary

Fields
`protected static String` `ABBR_SUFFIX`
`protected static String` `AFTER_KEY`
`protected static String` `BEFORE_KEY`
`static String` `BUNDLE_NAME_KEY` The key used for specifying a default locale via toolbox params.
`protected static int[]` `CALENDAR_FIELDS`
`protected static String` `CURRENT_PREFIX`
`protected static int` `CURRENT_TYPE`
`protected static String` `DAY_KEY`
`static String` `DEFAULT_BUNDLE_NAME` The default path of the relative format resource bundles.
`static String` `DEPTH_KEY` The key used for specifying a different default depth via toolbox params.
`protected static int` `DIFF_TYPE`
`protected static String` `EQUAL_KEY`
`protected static int` `EXACT_TYPE`
`protected static int[]` `FIELD_MAXIMA`
`protected static String` `HOUR_KEY`
`static long` `MILLIS_PER_DAY` The number of milliseconds in a day.
`static long` `MILLIS_PER_HOUR` The number of milliseconds in an hour.
`static long` `MILLIS_PER_MINUTE` The number of millseconds in a minute.
`static long` `MILLIS_PER_MONTH` An approximation of the number of milliseconds in a month.
`static long` `MILLIS_PER_SECOND` The number of milliseconds in a second.
`static long` `MILLIS_PER_WEEK` The number of milliseconds in a week.
`static long` `MILLIS_PER_YEAR` An approximation of the number of milliseconds in a year.
`protected static String` `MILLISECOND_KEY`
`protected static String` `MINUTE_KEY`
`protected static String` `MONTH_KEY`
`protected static String` `ONE_DAY_SUFFIX`
`protected static String` `PLURAL_SUFFIX`
`protected static int` `RELATIVE_TYPE`
`protected static String` `SECOND_KEY`
`static String` `SKIPPED_UNITS_KEY` The key used for specifying time units to be skipped over.
`protected static Map` `TIME_UNITS` Array of all time unit message keys to their millisecond conversion factor.
`protected static String[]` `UNIT_KEYS`
`protected static String` `WEEK_KEY`
`protected static String` `YEAR_KEY`
`protected static String` `ZERO_KEY`

### Fields inherited from class org.apache.velocity.tools.generic.DateTool

`TIMEZONE_KEY`

### 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, log, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY`

### Constructor Summary

Constructors
Constructor and Description
`ComparisonDateTool()`

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`protected ComparisonDateTool.Comparison` `compare(Object now, Object then, int type)` Internal comparison method.
`protected void` `configure(ValueParser values)` Calls the superclass implementation, then looks for a bundle name and any time units to be skipped.
`ComparisonDateTool.Comparison` `difference(Object now, Object then)` Returns a `ComparisonDateTool.Comparison` between the result of the second specified date and the first specified date.
`protected String` `getText(String key, Locale locale)` Retrieves the specified text resource.
`ComparisonDateTool.Comparison` `timespan(Object now, Object then)` Returns a `ComparisonDateTool.Comparison` between the result of the second specified date and the first specified date.
`static long` `toDays(long ms)` Returns the number of whole Days in the specified number of milliseconds.
`static long` `toHours(long ms)` Returns the number of whole Hours in the specified number of milliseconds.
`static long` `toMinutes(long ms)` Returns the number of whole Minutes in the specified number of milliseconds.
`static long` `toMonths(long ms)` Returns the number of whole Months in the specified number of milliseconds.
`static long` `toSeconds(long ms)` Returns the number of whole Seconds in the specified number of milliseconds.
`static long` `toWeeks(long ms)` Returns the number of whole Weeks in the specified number of milliseconds.
`static long` `toYears(long ms)` Returns the number of whole Years in the specified number of milliseconds.
`ComparisonDateTool.Comparison` `whenIs(Object then)` Returns a `ComparisonDateTool.Comparison` between the result of `DateTool.getCalendar()` and the specified date.
`ComparisonDateTool.Comparison` `whenIs(Object now, Object then)` Returns a `ComparisonDateTool.Comparison` between the second specified date and the first specified date.

### Methods inherited from class org.apache.velocity.tools.generic.DateTool

`format, format, format, format, format, format, format, get, get, getCalendar, getDate, getDateFormat, getDateFormat, getDay, getDay, getMonth, getMonth, getSystemCalendar, getSystemDate, getSystemTime, getTimeZone, getValue, getValue, getValue, getYear, getYear, setTimeZone, toCalendar, toCalendar, toCalendar, toCalendar, toCalendar, toDate, toDate, toDate, toDate, toDate, toDate, toLocalizedPattern, 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, toLocale`

### Methods inherited from class org.apache.velocity.tools.generic.SafeConfig

`configure, getLog, initLogger, isConfigLocked, isSafeMode, setLockConfig, setSafeMode`

### Methods inherited from class java.lang.Object

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

### 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 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 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 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 String DEFAULT_BUNDLE_NAME

The default path of the relative format resource bundles.

See Also:
  Constant Field Values

#### MILLISECOND_KEY

    protected static final String MILLISECOND_KEY

See Also:
  Constant Field Values

#### SECOND_KEY

    protected static final String SECOND_KEY

See Also:
  Constant Field Values

#### MINUTE_KEY

    protected static final String MINUTE_KEY

See Also:
  Constant Field Values

#### HOUR_KEY

    protected static final String HOUR_KEY

See Also:
  Constant Field Values

#### DAY_KEY

    protected static final String DAY_KEY

See Also:
  Constant Field Values

#### WEEK_KEY

    protected static final String WEEK_KEY

See Also:
  Constant Field Values

#### MONTH_KEY

    protected static final String MONTH_KEY

See Also:
  Constant Field Values

#### YEAR_KEY

    protected static final String YEAR_KEY

See Also:
  Constant Field Values

#### TIME_UNITS

    protected static final Map TIME_UNITS

Array of all time unit message keys to their millisecond conversion factor.

#### CURRENT_PREFIX

    protected static final String CURRENT_PREFIX

See Also:
  Constant Field Values

#### AFTER_KEY

    protected static final String AFTER_KEY

See Also:
  Constant Field Values

#### BEFORE_KEY

    protected static final String BEFORE_KEY

See Also:
  Constant Field Values

#### EQUAL_KEY

    protected static final String EQUAL_KEY

See Also:
  Constant Field Values

#### ZERO_KEY

    protected static final String ZERO_KEY

See Also:
  Constant Field Values

#### ABBR_SUFFIX

    protected static final String ABBR_SUFFIX

See Also:
  Constant Field Values

#### ONE_DAY_SUFFIX

    protected static final String ONE_DAY_SUFFIX

See Also:
  Constant Field Values

#### PLURAL_SUFFIX

    protected static final String PLURAL_SUFFIX

See Also:
  Constant Field Values

#### CURRENT_TYPE

    protected static final int CURRENT_TYPE

See Also:
  Constant Field Values

#### RELATIVE_TYPE

    protected static final int RELATIVE_TYPE

See Also:
  Constant Field Values

#### DIFF_TYPE

    protected static final int DIFF_TYPE

See Also:
  Constant Field Values

#### EXACT_TYPE

    protected static final int EXACT_TYPE

See Also:
  Constant Field Values

#### CALENDAR_FIELDS

    protected static final int[] CALENDAR_FIELDS

#### FIELD_MAXIMA

    protected static final int[] FIELD_MAXIMA

#### UNIT_KEYS

    protected static final 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 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