Package com.atlassian.jira.datetime

Interface DateTimeFormatter

@ThreadSafe @InjectableComponent public interface DateTimeFormatter
Interface for JIRA date time formatters. All formatters are time zone-aware (the actual time zone that they use when formatting dates will depend on how they were created). Formatters can be injected directly into other classes or alternatively created using DateTimeFormatterFactory. See com.atlassian.jira.datetime for examples of how to use DateTimeFormatter. Example:

All implementations of this interface are thread safe, and are therefore safe to cache and reuse across different requests.

Since:
4.4
See Also:

  • Method Details

    • format

      String format(Date date)
      Formats a Date as a human-readable string, using the date/time style returned by getStyle().

      Note that the formatted date is always in English, regardless of locale, if DateTimeStyle.RSS_RFC822_DATE_TIME is selected.

      Parameters:
      date - a Date instance
      Returns:
      a String containing a formatted date

    • parse

      Date parse(String text) throws IllegalArgumentException, UnsupportedOperationException
      Parses a date from the given text, returning a new Date. The text will be interpreted as being in the timezone of this formatter.

      Note that the given text must be in English, regardless of locale, if DateTimeStyle.RSS_RFC822_DATE_TIME is selected.

      Parameters:
      text - a String containing a date
      Returns:
      a new Date
      Throws:
      IllegalArgumentException - if the input text can not be parsed
      UnsupportedOperationException - if this strategy does not support parsing

    • forLoggedInUser

      DateTimeFormatter forLoggedInUser()
      Returns a new formatter that will use the time zone and locale of the user that is logged in when format and/or parse are called, if any (as specified by JiraAuthenticationContext). If there is no logged in user, or if the logged in user has not configured a time zone and/or locale, the JIRA default time zone and/or locale is used.

      It is intended that clients will reuse the formatter obtained from this method across requests: it will always use the time zone and locale of the currently logged in user.

      Important: You should use system time zone when you use this method together with DateTimeStyle.DATE style as it formats date without time information.

      Returns:
      a new DateTimeFormatter
      See Also:

    • forUser

      DateTimeFormatter forUser(@Nullable ApplicationUser user)
      Returns a new formatter that will use the given user's time zone and locale. If the user argument is null, this formatter will use the default JIRA time zone and locale at invocation time.
      Parameters:
      user - the User whose time zone and locale the new formatter will use
      Returns:
      a new DateTimeFormatter

    • withDefaultZone

      DateTimeFormatter withDefaultZone()
      Returns a new formatter that will use the JIRA default time zone to format and parse dates.
      Returns:
      a new DateTimeFormatter

    • withSystemZone

      DateTimeFormatter withSystemZone()
      Returns a new formatter that will use the system time zone to format and parse dates.
      Returns:
      a new DateTimeFormatter
      See Also:

    • withZone

      DateTimeFormatter withZone(@Nullable TimeZone timeZone)
      Returns a new formatter that will use the specified zone instead of the JIRA default time zone. If the time zone argument is null, this formatter will use the JIRA default time zone at invocation time.
      Parameters:
      timeZone - a TimeZone
      Returns:
      a new DateTimeFormatter

    • withDefaultLocale

      DateTimeFormatter withDefaultLocale()
      Returns a new formatter that will use the JIRA default locale to format and parse dates.
      Returns:
      a new DateTimeFormatter

    • withLocale

      DateTimeFormatter withLocale(@Nullable Locale locale)
      Specifies the Locale to use when formatting dates. If the locale argument is null, this formatter will use the JIRA default locale at invocation time.
      Parameters:
      locale - a Locale
      Returns:
      a new DateTimeFormatter

    • withStyle

      DateTimeFormatter withStyle(@Nullable DateTimeStyle style)
      Specifies the style to use when formatting dates. If the style argument is null, this formatter will use the JIRA default style at invocation time.
      Parameters:
      style - a DateTimeStyle
      Returns:
      a new DateTimeFormatter

    • withStyle

      DateTimeFormatter withStyle(@Nullable String style)
      Specifies the style to use when formatting dates. If the style argument is null, this formatter will use the JIRA default style at invocation time. This is a convenience method for use within velocity templates. Please use withStyle(DateTimeStyle) in java code.
      Parameters:
      style - a DateTimeStyle
      Returns:
      a new DateTimeFormatter

    • getZone

      TimeZone getZone()
      Returns this formatter's time zone. If null, this formatter will use the default JIRA time zone at invocation time.
      Returns:
      the TimeZone

    • getLocale

      Locale getLocale()

    • getStyle

      DateTimeStyle getStyle()
      Returns this formatter's style. If null, this formatter will use the JIRA default date time style at invocation time.
      Returns:
      the DateTimeStyle

    • getFormatHint

      String getFormatHint()
      Returns a hint for this formatter. This hint can be shown on screen to help the user understand the format that can be parsed by this formatter. Note that the hint should be understandable by a human, but not necessarily by a Java date formatter.
      Returns:
      a String containing a pattern