org.apache.velocity.tools.generic
Class ComparisonDateTool

java.lang.Object
  org.apache.velocity.tools.generic.DateTool
      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 toolbox.xml config (if you want to use this with VelocityView):
 <tool>
   <key>date</key>
   <scope>application</scope>
   <class>org.apache.velocity.tools.generic.ComparisonDateTool</class>
   <parameter name="format" value="yyyy-MM-dd"/>
   <parameter name="bundle" value="org.apache.velocity.tools.generic.times"/>
   <parameter name="depth" value="1"/>
   <parameter name="skip" value="month,week,millisecond"/>
 </tool>
 

Since:

VelocityTools 1.4

Version:

$Revision: 527192 $ $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, DEFAULT_FORMAT_KEY, DEFAULT_LOCALE_KEY, LOCK_CONFIG_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

configure, format, format, format, format, format, format, format, get, get, getCalendar, getDate, getDateFormat, getDateFormat, getDateFormat, getDay, getDay, getFormat, getLocale, getMonth, getMonth, getStyleAsInt, getSystemCalendar, getSystemDate, getSystemTime, getTimeZone, getValue, getValue, getValue, getYear, getYear, setFormat, setLocale, toCalendar, toCalendar, toDate, toDate, toDate, toDate, toString

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".