org.afcs.warts.util
Class DateComparator

java.lang.Object
  org.afcs.warts.util.DateComparator

public final class DateComparator

extends java.lang.Object

The DateComparator class provides various utilities related to the comparison of dates.

The first utility is a comparator (in the DATE_COMPARATOR field, that can be used to compare dates, and hence sort them in a list.

The second utility is a method that can turn the difference between two dates into human-readable text (e.g., "less than 2 minutes ago").

Another method is a utility that allows users to quickly determine if the difference between two dates is less than some range.

LICENSE: This code is released to the public domain and may be used for any purpose whatsoever without permission or acknowledgment.

Version:

Last Modified 7 August 2003

Author:

Warren Hedley ( whedley at sdsc dot edu )

Field Summary

static java.util.Comparator	DATE_COMPARATOR This comparator can be used to compare dates.
static long	DAY The number of milliseconds in a day.
static long	HOUR The number of milliseconds in an hour.
static long	MINUTE The number of milliseconds in a minute.
static long	SECOND The number of milliseconds in a second.

Method Summary

static boolean	absoluteTimeDifferenceLessThan(java.util.Date baseDate, java.util.Date compareToDate, long unitInMilliseconds, int numUnits) Returns true if the difference between the specified "compare to" date and the source date that the instance was initialied with is less than the specified number of units of the specified units of time (which are specified in milliseconds).
static java.lang.String	getDateDifferenceText(java.util.Date baseDate, java.util.Date compareToDate) Returns text describing the difference between the two dates.

Methods inherited from class java.lang.Object

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

Field Detail

DATE_COMPARATOR

public static final java.util.Comparator DATE_COMPARATOR

This comparator can be used to compare dates. When applied to a list of dates, the comparator will put dates in ascending order with nulls first.

SECOND

public static final long SECOND

The number of milliseconds in a second.

See Also:

Constant Field Values

MINUTE

public static final long MINUTE

The number of milliseconds in a minute.

See Also:

Constant Field Values

HOUR

public static final long HOUR

The number of milliseconds in an hour.

See Also:

Constant Field Values

DAY

public static final long DAY

The number of milliseconds in a day.

See Also:

Constant Field Values

Method Detail

absoluteTimeDifferenceLessThan

public static boolean absoluteTimeDifferenceLessThan(java.util.Date baseDate,
                                                     java.util.Date compareToDate,
                                                     long unitInMilliseconds,
                                                     int numUnits)

Returns true if the difference between the specified "compare to" date and the source date that the instance was initialied with is less than the specified number of units of the specified units of time (which are specified in milliseconds). The unitInMilliseconds parameter can be conveniently specified using one of the constants defined in this class. A typical call might look like:

   boolean lessThanAnHourAgo =
       DateComparator.absoluteTimeDifferenceLessThan(
       someDate, someOtherDate, DateComparator.HOUR, 1);
 

Note that only the absolute difference between the two dates is considered.

Parameters:

baseDate - The base date in the comparison.

compareToDate - The date to compare the base date against.

unitInMilliseconds - A unit of time, specified in milliseconds. Users are encouraged to use the constants defined in this class to make code more readable.

numUnits - The number of units of time to consider.

Returns:

True if the difference between the base date and the "compare to" date is less than the specified number of units multiplied by the specified unit, which is specified in milliseconds.

Throws:

java.lang.NullPointerException - If baseDate or compareDate is null.

getDateDifferenceText

public static java.lang.String getDateDifferenceText(java.util.Date baseDate,
                                                     java.util.Date compareToDate)

Returns text describing the difference between the two dates. For instance, if the "compare to" date is two minutes before the base date, then the string "less than 2 minutes ago" will be returned.

Parameters:

baseDate - The base date in the comparison.

compareToDate - The date to compare the base date against.

Returns:

Text describing the difference between the two dates specified.

Throws:

java.lang.NullPointerException - If baseDate or compareDate is null.