Package com.atlassian.jira.datetime

A small set of classes that allow clients to format and parse dates in JIRA, in a way that is time zone and locale aware.

See:
Description

Interface Summary

DateTimeFormatter	Interface for JIRA date time formatters.
DateTimeFormatterFactory	This factory is used to create DateTimeFormatter instances within JIRA.

Class Summary

DateTimeFormatterFactoryImpl	This class is responsible for providing DateTimeFormatter instances to JIRA and plugin code.
DateTimeFormatterFactoryStub	Stub for DateTimeFormatterFactory, useful for unit tests.
JodaFormatterSupplierStub	JodaFormatterSupplier for use in tests.
LocalDate	Represents a "Local Date" or "Calendar Date" - that is a date (no time) without any associated timezone.
LocalDateFactory	Used for creating LocalDate objects.

Enum Summary

DateTimeStyle

The date styles that JIRA is capable of formatting to.

Package com.atlassian.jira.datetime Description

A small set of classes that allow clients to format and parse dates in JIRA, in a way that is time zone and locale aware.

Time zones

When working with dates and times inside JIRA, it is important to understand the following time zone concepts.

• System time zone: the time zone of the JVM, as defined by TimeZone.getDefault(),
• Default user time zone: the JIRA default time zone, as configured by an administrator, and
• User time zone: the user-specific time zone, as configured by each user.

By default, formatters in this package will operate using the time zone of the user that is currently logged in. If the default user time zone has not configured, it defaults to the system time zone. Similarly, if a user has not configured a user time zone, JIRA will use the default user time zone when displaying date and times to that user.

Locales

JIRA is capable of displaying dates in the default JIRA locale, and also in the user's locale, when a user has explicitly configured a different locale. By default, formatters in this package will operate using the locale of the user that is currently logged in.

Usage

Most of the work is done by implementations of the DateTimeFormatter interface. If you intent to use date, and especially date/time values in your plugin, you should have a DateTimeFormatterFactory injected into your plugin classes, which you can use to build DateTimeFormatter instances, as in the following example.

     public class MyPluginClass
     {
         private final DateTimeFormatter dateTimeFormatter;
         private final DateTimeFormatter utcDateTimeFormatter;
         private final DateTimeFormatter dutchDateTimeFormatter;

         public MyPluginClass(DateTimeFormatterFactory dateTimeFormatterFactory)
         {
             dateTimeFormatter = dateTimeFormatterFactory.formatter().withStyle(COMPLETE);
             utcDateTimeFormatter = dateTimeFormatter.withZone(TimeZone.UTC);
             dutchDateTimeFormatter= = dateTimeFormatter.withLocale(new Locale("nl"));
         }

         // formats dates in the user's time zone and with the user's locale
         public String currentDate()
         {
             return dateTimeFormatter.format(new Date());
         }

         // formats dates in UTC and with the user's locale
         public String currentDateInUTC()
         {
             return utcDateTimeFormatter.format(new Date());
         }

         // formats dates in the user's time zone and in Dutch
         public String currentDateInDutch()
         {
             return dutchDateTimeFormatter.format(new Date());
         }
     }
 

Since:

4.4