com.day.cq.commons.date

Class RelativeTimeFormat

java.lang.Object

com.day.cq.commons.date.RelativeTimeFormat

public class RelativeTimeFormat
extends java.lang.Object

The RelativeTimeFormat provides formatting of relative time periods. Relative time periods in this context indicate a duration from a given start date/time to the current system time or the given end date/time.

These periods can be formatted to provide human readable strings describing the duration of that period. For example the duration with start date 2010-06-30 3:25:00 PM and end date 2010-06-30 3:25:16 would be 16 seconds. This can for example be formatted as "16 seconds ago". With an end date of e.g. 2010-07-02 5:23:00 AM, the resulting formatted string could be "Jul 2 (2 days ago)".

The desired formatting can be defined using a formatting pattern, similar to many date formatting tools in existence. Relative time format patterns also result in outputting standard date/time information, e.g. the date or hour included in a relative time format string, e.g. "Jun 30 (16 seconds ago)". The format of the standard date/time information is delegated to SimpleDateFormat. Thus, in addition to the main relative time format pattern, sub-patterns for the standard date/time blocks can be specified in the constructor (RelativeTimeFormat(String, String, String, String, java.util.ResourceBundle). Patterns for time, medium date and long date information can be specified.

The relative time formatting also uses localized words for output, such as e.g. the month names (e.g. "Jul" or "July") or the words "ago" and "minutes" to e.g. output "2 minutes ago". For localization the default system locale is used, unless a custom resource bundle is provided in the constructor. The custom resource bundle must provide a locale, otherwise again the default system locale is used, which mit result in mixed language outputs, such as "30. June (vor 2 Minuten)" (english/german mixture).

Within date and time pattern strings, unquoted letters from 'A' to 'Z' and from 'a' to 'z' are interpreted as pattern letters representing the components of a date or time string. All other characters are not interpreted; they're simply copied into the output string during formatting or matched against the input string during parsing.

The format function gives the ability to specify the insertion of the word ago in the resulting string. For example, it can be used to get a string like "15 seconds ago". If "ago" is false "15 seconds will be returned.

The following pattern letters are defined (all other characters from 'A' to 'Z' and from 'a' to 'z' are reserved):

Letter	Date or Time Component	Presentation	Examples
d	Number of days of the period (localized)	Text	2 days
D	Dynamic date. This formats the start date of the period according to the amount of time it is in the past with respect to period's end date: start is last year: date is formated according to the longPattern, default: MM/dd/yyyy (see SimpleDateFormat). start is 1 day (24h) or more in the past: date is formated according to the shortPattern, default: MMM dd (see SimpleDateFormat). start is less than 24h in the past: date is formated according to the timePattern, default: HH:mm (see SimpleDateFormat).	Text	21/12/2010, Jun 30, 21:34
h	Number of hours in the period (localized)	Text	4 hours
m	Number of minutes in the period (localized)	Text	40 minutes
M	Number of months in the period (localized)	Text	3 months
r	Amount of time since the start of the period (localized). The amount is structured into the following units: seconds, minutes, hours, days, months and years. Always the largest non-zero unit is output. E.g. if the amount is 2 days, 4 minutes and 54 seconds, the output would be "2 days".	Text	4 months
s	Number of seconds in the period (localized)	Text	16 seconds
y	Number of years in the period (localized)	Text	1 year
Y	Fully dynamic auto-mode. The auto-mode reflects Gmail-style adaptation of the relative time output string, and is subject to the following rules: start is last year: only the full date is output, according to longPattern, default: MM/dd/yyyy. start is 2 weeks or more in the past: the month and day in month are output, according to shortPattern, default: MMM dd. start is 24 hours or more in the past: the month and day in month are output, additionally the number of days are put in brackets. The month and day in month are formatted according to the shortPattern. start is less than 24 hours in the past: the time is output according to timePattern and additionally in brackets the relative amount of time passed according to the r pattern character. Do not need to put the boolean to true when format is called with the pattern 'Y'. "ago" will be included automatically in the resulting string.	Text	21/12/2009 Jun 30 Sep 4 (12 days ago) 15:25 (2 minutes ago

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	FACEBOOK
static java.lang.String	FULL
static java.lang.String	GMAIL
static java.lang.String	SHORT

Constructor Summary

Constructors

Constructor and Description
RelativeTimeFormat(java.lang.String pattern) Constructs a new RelativeTimeFormat instance.
RelativeTimeFormat(java.lang.String pattern, java.util.ResourceBundle bundle) Constructs a new RelativeTimeFormat instance.
RelativeTimeFormat(java.lang.String pattern, java.lang.String timePattern, java.lang.String shortPattern, java.lang.String longPattern, java.util.ResourceBundle bundle) Constructs a new RelativeTimeFormat instance.

Method Summary

Modifier and Type	Method and Description
java.lang.String	format(long start) Formats the time period from the given start date/time according to the pattern selected in the constructor.
java.lang.String	format(long start, boolean ago) Formats the time period from the given start date/time according to the pattern selected in the constructor.
java.lang.String	format(long start, long end) Formats the time period as defined via the given start date/time and the given end date/time, according to the pattern selected in the constructor.
java.lang.String	format(long start, long end, boolean ago) Formats the time period as defined via the given start date/time and the given end date/time, according to the pattern selected in the constructor.

Methods inherited from class java.lang.Object

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

Field Detail

SHORT

public static final java.lang.String SHORT

See Also:

Constant Field Values

FULL

public static final java.lang.String FULL

See Also:

Constant Field Values

FACEBOOK

public static final java.lang.String FACEBOOK

See Also:

Constant Field Values

GMAIL

public static final java.lang.String GMAIL

See Also:

Constant Field Values

Constructor Detail

RelativeTimeFormat

public RelativeTimeFormat(java.lang.String pattern)

Constructs a new RelativeTimeFormat instance.

Parameters:

pattern - The pattern for the relative time.

RelativeTimeFormat

public RelativeTimeFormat(java.lang.String pattern,
                          java.util.ResourceBundle bundle)

Constructs a new RelativeTimeFormat instance.

Parameters:

pattern - The pattern for the relative time.

bundle - The ResourceBundle for i18n of the time labels (e.g. "days", "seconds", ...), may be null.

RelativeTimeFormat

public RelativeTimeFormat(java.lang.String pattern,
                          java.lang.String timePattern,
                          java.lang.String shortPattern,
                          java.lang.String longPattern,
                          java.util.ResourceBundle bundle)

Constructs a new RelativeTimeFormat instance.

Parameters:

pattern - The formatting pattern for the relative time.

timePattern - The SimpleDateFormat pattern for time (default: HH:mm), may be null.

shortPattern - The SimpleDateFormat pattern for month and day (default: MMM d), may be null.

longPattern - The SimpleDateFormat pattern for full date (default: MM/dd/yyyy), may be null.

bundle - The ResourceBundle for i18n of the time labels (e.g. "days", "seconds", ...), may be null.

Method Detail

format

public java.lang.String format(long start)

Formats the time period from the given start date/time according to the pattern selected in the constructor. The end date/time of the period is the current system time. To specify your own end date/time of the period, use format(long, long).

Parameters:

start - The start date/time of the period to be formatted in milliseconds.

Returns:

A String representing the formatted period.

format

public java.lang.String format(long start,
                               boolean ago)

Formats the time period from the given start date/time according to the pattern selected in the constructor. The end date/time of the period is the current system time. To specify your own end date/time of the period, use format(long, long).

Parameters:

start - The start date/time of the period to be formatted in milliseconds.

ago - The resulting string should contain "ago" (or localized variant)

Returns:

A String representing the formatted period.

format

public java.lang.String format(long start,
                               long end)

Formats the time period as defined via the given start date/time and the given end date/time, according to the pattern selected in the constructor.

Parameters:

start - The start date/time of the period to be formatted in milliseconds.

end - The end date/time of the period to be formatted in milliseconds.

Returns:

A String representing the formatted period.

format

public java.lang.String format(long start,
                               long end,
                               boolean ago)

Formats the time period as defined via the given start date/time and the given end date/time, according to the pattern selected in the constructor.

Parameters:

start - The start date/time of the period to be formatted in milliseconds.

end - The end date/time of the period to be formatted in milliseconds.

ago - The resulting string should contain "ago" (or localized variant)

Returns:

A String representing the formatted period.