DateTime is a class used for parsing, storing, and manipulating Date and Time. It provides a number of advances over Java's Date object, including immutability, nanosecond precision, and calculation functions such as "add" and "truncate". It can parse dates and times without requiring a specific format, and has integrated formatting into its toString() output to make custom formatting simple and elegant.
DateTime has excellent support for business use cases involving multiple time zones, locales and formats. Default behaviors can be customized globally, for a set of dates sharing a common isolated configuration, or catered to individual instances.
DateTime will correctly parse precise date and time from the following strings without specifying any formats.
DateTimeConfig.globalEuropeanDateFormat(); DateTime dt1=new DateTime("01/02/2003"); DateTimeConfig.globalAmericanDateFormat(); DateTime dt2=new DateTime("02/01/2003"); assertEquals(dt1, dt2);
Working with DateTime is both easy and powerful. It's designed so that simple tasks are simple and difficult tasks are possible. While mostly intuitive, it helps to understand a few basic concepts.
A DateTime represents an instant in time in UTC (Universal Time, Coordinated), informally GMT or Zulu time. You can select the time zone, format, and locale (language) of displayed or printed output.
Every DateTime value is associated with a DateTimeConfig object. That object holds several variables affecting how DateTime will perform during input, processing, and output of values. When unspecified, the static DateTimeConfig.globalDefault is used. You can specify a time zone or locale in the constructor to override the default. In that case, a cloned copy of the DateTimeConfig is associated and those values are substituted in that config object.
The config.inputTimeZone determines the default time zone
assumed for an input string when no time zone is specified in the
string itself. The DateTime object will use that time zone to calculate
the internal UTC representation of that instant in time. For activities
after that initial parse the original time zone is ignored and all
outputs are based on config.outputTimeZone.
European and American formatting of dates can be a source of ambiguity, as one may interpret the date 01/02/2003 as February 1, and the other as January 2. You can choose whether the parser interprets such dates in Day/Month/Year order or Month/Day/Year order by setting the value config.dmyOrder to true or false. Two digit years are also ambiguous. By default, POJava treats such dates as 80 years in the past and 20 years into the future. When a date to parse is known to always be in the past, such as a date of birth, you can set the value config.unspecifiedCenturyAlwaysInPast to true to map 2-digit years to the past 100 years.
The config.outputTimeZone is used for DateTime calculations. For example, if a date was parsed from a string specifying "GMT" as the time zone, and the config.OutputTimeZone was set to the "PST" time zone, then the DateTime's truncate(CalendarUnit.Day) would round down to midnight as of the PST time zone. The original config is transferred to the newly calculated DateTime.
The config.outputTimeZone, config.locale, and config.format values determine the appearance of the toString() output. OutputTimeZone affects what date and hour is displayed for that instant in time. The locale affects the presentation of word values such as month names or days of the week.
String date="26-Feb-2020 9:43:17 pm"; DateTime dt=new DateTime(date); System.out.println(dt.toString());
String utc="2011/12/13T14:15:16Z"; DateTime dt=new DateTime(utc); System.out.println(dt.toString("yyyy-MM-dd HH:mm:ss z", TimeZone.getTimeZone("EST"));Another method is to predefine the expected time zones in the global configuration.
String utc="2011/12/13T14:15:16Z"; DateTimeConfig config=DateTimeConfig.getGlobalDefault(); config.setOutputTimeZone(TimeZone.getTimeZone("EST")); DateTime dt=new DateTime(utc); System.out.println(dt.toString());A third method is to use a custom configuration.
String utc="2011/12/13T14:15:16Z"; DateTimeConfig config=DateTimeConfig.getGlobalDefault().clone(); config.setOutputTimeZone(TimeZone.getTimeZone("EST")); DateTime dt=new DateTime(utc, config); System.out.println(dt.toString());