Class 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
    • 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.