ComparisonDateTool (VelocityTools 3.2-SNAPSHOT API)

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
Modifier and Type Class and Description

class ComparisonDateTool.Comparison

Nested Classes
Modifier and Type	Class and Description
`class`	`ComparisonDateTool.Comparison`

Field Summary

Fields
Modifier and Type	Field and Description
`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()

Constructors
Constructor and Description
`ComparisonDateTool()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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

Class ComparisonDateTool

Nested Class Summary

Field Summary

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

Fields inherited from class org.apache.velocity.tools.generic.FormatConfig

Fields inherited from class org.apache.velocity.tools.generic.LocaleConfig

Fields inherited from class org.apache.velocity.tools.generic.SafeConfig

Constructor Summary

Method Summary

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

Methods inherited from class org.apache.velocity.tools.generic.FormatConfig

Methods inherited from class org.apache.velocity.tools.generic.LocaleConfig

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

Methods inherited from class java.lang.Object

Field Detail

MILLIS_PER_SECOND

MILLIS_PER_MINUTE

MILLIS_PER_HOUR

MILLIS_PER_DAY

MILLIS_PER_WEEK

MILLIS_PER_MONTH

MILLIS_PER_YEAR

BUNDLE_NAME_KEY

DEPTH_KEY

SKIPPED_UNITS_KEY

DEFAULT_BUNDLE_NAME

MILLISECOND_KEY

SECOND_KEY

MINUTE_KEY

HOUR_KEY

DAY_KEY

WEEK_KEY

MONTH_KEY

YEAR_KEY

TIME_UNITS

CURRENT_PREFIX

AFTER_KEY

BEFORE_KEY

EQUAL_KEY

ZERO_KEY

ABBR_SUFFIX

ONE_DAY_SUFFIX

PLURAL_SUFFIX

CURRENT_TYPE

RELATIVE_TYPE

DIFF_TYPE

EXACT_TYPE

CALENDAR_FIELDS

FIELD_MAXIMA

UNIT_KEYS

Constructor Detail

ComparisonDateTool

Method Detail

configure

getText

toYears

toMonths

toWeeks

toDays

toHours

toMinutes

toSeconds

whenIs

whenIs

difference

timespan

compare