org.apache.velocity.tools.generic
Class ComparisonDateTool

java.lang.Object
  extended by org.apache.velocity.tools.generic.SafeConfig
      extended by org.apache.velocity.tools.generic.LocaleConfig
          extended by org.apache.velocity.tools.generic.FormatConfig
              extended by org.apache.velocity.tools.generic.DateTool
                  extended by org.apache.velocity.tools.generic.ComparisonDateTool

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: 595822 $ $Date: 2006-04-04 12:35:17 -0700 (Tue, 04 Apr 2006) $
Author:
Nathan Bubna, Chris Townsen

Nested Class Summary
 class ComparisonDateTool.Comparison
           
 
Field Summary
protected static java.lang.String ABBR_SUFFIX
           
protected static java.lang.String AFTER_KEY
           
protected static java.lang.String BEFORE_KEY
           
static java.lang.String BUNDLE_NAME_KEY
          The key used for specifying a default locale via toolbox params.
private  java.lang.String bundleName
           
protected static java.lang.String CURRENT_PREFIX
           
protected static int CURRENT_TYPE
           
protected static java.lang.String DAY_KEY
           
static java.lang.String DEFAULT_BUNDLE_NAME
          The default path of the relative format resource bundles.
private  java.util.ResourceBundle defaultBundle
           
private  int depth
           
static java.lang.String DEPTH_KEY
          The key used for specifying a different default depth via toolbox params.
protected static int DIFF_TYPE
           
protected static java.lang.String EQUAL_KEY
           
protected static java.lang.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 java.lang.String MILLISECOND_KEY
           
protected static java.lang.String MINUTE_KEY
           
protected static java.lang.String MONTH_KEY
           
protected static java.lang.String ONE_DAY_SUFFIX
           
protected static java.lang.String PLURAL_SUFFIX
           
protected static int RELATIVE_TYPE
           
protected static java.lang.String SECOND_KEY
           
static java.lang.String SKIPPED_UNITS_KEY
          The key used for specifying time units to be skipped over.
protected static java.util.Map TIME_UNITS
          Array of all time unit message keys to their millisecond conversion factor.
private  java.util.Map timeUnits
           
protected static java.lang.String WEEK_KEY
           
protected static java.lang.String YEAR_KEY
           
protected static java.lang.String ZERO_KEY
           
 
Fields inherited from class org.apache.velocity.tools.generic.DateTool
DEFAULT_FORMAT_KEY, DEFAULT_LOCALE_KEY, 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, OLD_LOCK_CONFIG_KEY, SAFE_MODE_KEY
 
Constructor Summary
ComparisonDateTool()
           
 
Method Summary
protected  ComparisonDateTool.Comparison compare(java.lang.Object now, java.lang.Object then, int type)
           
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(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.
protected  java.lang.String getText(java.lang.String key, java.util.Locale locale)
          Retrieves the specified text resource.
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.
protected  java.lang.String toString(long diff, int maxUnitDepth, boolean abbreviate, java.util.Locale locale)
          Converts the specified positive duration of milliseconds into larger units up to the specified number of positive units, beginning with the largest positive unit.
protected  java.lang.String toString(long ms, int type, int depth, boolean abbr, java.util.Locale loc)
           
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(java.lang.Object then)
          Returns a ComparisonDateTool.Comparison between the result of DateTool.getCalendar() and the specified date.
 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.
 
Methods inherited from class org.apache.velocity.tools.generic.DateTool
format, format, format, format, format, format, format, get, get, getCalendar, getDate, getDateFormat, getDateFormat, getDateFormat, getDay, getDay, getMonth, getMonth, getStyleAsInt, getSystemCalendar, getSystemDate, getSystemTime, getTimeZone, getValue, getValue, getValue, getYear, getYear, setTimeZone, toCalendar, toCalendar, toDate, toDate, toDate, toDate, 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
 
Methods inherited from class org.apache.velocity.tools.generic.SafeConfig
configure, 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 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

SECOND_KEY

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

MINUTE_KEY

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

HOUR_KEY

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

DAY_KEY

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

WEEK_KEY

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

MONTH_KEY

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

YEAR_KEY

protected static final java.lang.String YEAR_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.


CURRENT_PREFIX

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

AFTER_KEY

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

BEFORE_KEY

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

EQUAL_KEY

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

ZERO_KEY

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

ABBR_SUFFIX

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

ONE_DAY_SUFFIX

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

PLURAL_SUFFIX

protected static final java.lang.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

bundleName

private java.lang.String bundleName

defaultBundle

private java.util.ResourceBundle defaultBundle

timeUnits

private java.util.Map timeUnits

depth

private int depth
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

getText

protected java.lang.String getText(java.lang.String key,
                                   java.util.Locale locale)
Retrieves the specified text resource.


toYears

public static long toYears(long ms)
Returns the number of whole Years in the specified number of milliseconds.


toMonths

public static long toMonths(long ms)
Returns the number of whole Months in the specified number of milliseconds.


toWeeks

public static long toWeeks(long ms)
Returns the number of whole Weeks in the specified number of milliseconds.


toDays

public static long toDays(long ms)
Returns the number of whole Days in the specified number of milliseconds.


toHours

public static long toHours(long ms)
Returns the number of whole Hours in the specified number of milliseconds.


toMinutes

public static long toMinutes(long ms)
Returns the number of whole Minutes in the specified number of milliseconds.


toSeconds

public static long toSeconds(long ms)
Returns the number of whole Seconds in the specified number of milliseconds.


whenIs

public ComparisonDateTool.Comparison whenIs(java.lang.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

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

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

compare

protected ComparisonDateTool.Comparison compare(java.lang.Object now,
                                                java.lang.Object then,
                                                int type)

toString

protected java.lang.String toString(long ms,
                                    int type,
                                    int depth,
                                    boolean abbr,
                                    java.util.Locale loc)
Parameters:
ms - The time in milliseconds
type - Whether the time should be represented as relative to "now", relative to some other time, or as a mere difference.
depth - The maximum number of units deep to show
abbr - Whether the units should be abbreviated or not
loc - The locale to be used when looking up resources

toString

protected java.lang.String toString(long diff,
                                    int maxUnitDepth,
                                    boolean abbreviate,
                                    java.util.Locale locale)
Converts the specified positive duration of milliseconds into larger units up to the specified number of positive units, beginning with the largest positive unit. e.g. toString(181453, 3, false, null) will return "3 minutes 1 second 453 milliseconds", toString(181453, 2, false, null) will return "3 minutes 1 second", and toString(180000, 2, true, null) will return "3 min".



Copyright (c) 2003-2007 Apache Software Foundation