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 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	Description
`RelativeTimeFormat(java.lang.String pattern)`	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.
`RelativeTimeFormat(java.lang.String pattern, java.util.ResourceBundle bundle)`	Constructs a new `RelativeTimeFormat` instance.

Method Summary

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

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`

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

Class RelativeTimeFormat

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SHORT

FULL

FACEBOOK

GMAIL

Constructor Detail

RelativeTimeFormat

RelativeTimeFormat

RelativeTimeFormat

Method Detail

format

format

format

format