@ThreadSafe @InjectableComponent public interface

DateTimeFormatter

com.atlassian.jira.datetime.DateTimeFormatter

Class Overview

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.

See Also

Summary

Public Methods
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).
DateTimeFormatter forUser(User user)
Returns a new formatter that will use the given user's time zone and locale.
String format(Date date)
Formats a Date as a human-readable string, using the date/time style returned by getStyle().
String getFormatHint()
Returns a hint for this formatter.
Locale getLocale()
DateTimeStyle getStyle()
Returns this formatter's style.
TimeZone getZone()
Returns this formatter's time zone.
Date parse(String text)
Parses a date from the given text, returning a new Date.
DateTimeFormatter withDefaultLocale()
Returns a new formatter that will use the JIRA default locale to format and parse dates.
DateTimeFormatter withDefaultZone()
Returns a new formatter that will use the JIRA default time zone to format and parse dates.
DateTimeFormatter withLocale(Locale locale)
Specifies the Locale to use when formatting dates.
DateTimeFormatter withStyle(DateTimeStyle style)
Specifies the style to use when formatting dates.
DateTimeFormatter withSystemZone()
Returns a new formatter that will use the system time zone to format and parse dates.
DateTimeFormatter withZone(TimeZone timeZone)
Returns a new formatter that will use the specified zone instead of the JIRA default time zone.

Public Methods

public 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 DATE style as it formats date without time information.

Returns
  • a new DateTimeFormatter
See Also

public DateTimeFormatter forUser (User 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

public String format (Date date)

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

Parameters
date a Date instance
Returns
  • a String containing a formatted date

public 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

public Locale getLocale ()

public 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

public 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

public Date parse (String text)

Parses a date from the given text, returning a new Date. The text will be interpreted as being in the timezone of this formatter.

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

public DateTimeFormatter withDefaultLocale ()

Returns a new formatter that will use the JIRA default locale to format and parse dates.

Returns
  • a new DateTimeFormatter

public DateTimeFormatter withDefaultZone ()

Returns a new formatter that will use the JIRA default time zone to format and parse dates.

Returns
  • a new DateTimeFormatter

public DateTimeFormatter withLocale (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

public DateTimeFormatter withStyle (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

public DateTimeFormatter withSystemZone ()

Returns a new formatter that will use the system time zone to format and parse dates.

Returns
  • a new DateTimeFormatter
See Also

public DateTimeFormatter withZone (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