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
 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(com.atlassian.crowd.embedded.api.User 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 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().

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.

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.

Returns:
a new DateTimeFormatter
See Also:
JiraAuthenticationContext.getLoggedInUser()

forUser

DateTimeFormatter forUser(@Nullable
                          com.atlassian.crowd.embedded.api.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

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

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


Copyright © 2002-2014 Atlassian. All Rights Reserved.