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:

DateTimeFormatterFactory

Method Summary

Modifier and Type	Method and Description
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).
String	format(Date date) Formats a Date as a human-readable string, using the date/time style returned by getStyle().
DateTimeFormatter	forUser(ApplicationUser user) Returns a new formatter that will use the given user's time zone and locale.
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	withStyle(String 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.

Method Detail

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:

JiraAuthenticationContext.getLoggedInUser(), withSystemZone()

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:

TimeZone.getDefault()

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