Avoid legacy date-time classes
The old date-time classes bundled with the earliest versions of Java have proven to be poorly-designed, confusing, and troublesome. Avoid them. They are now legacy, supplanted by the java.time classes built into Java 8.
ThreeTen-Backport
Much of the java.time functionality was back-ported to Java 6 & 7 in the ThreeTen-Backport project. Add that library to your Java 6 apps.
Think of UTC as the One True Time. Forget about your own time zone. Use UTC for much of your business logic, logging, data storage, and data exchange. Generally only apply a time zone for presentation to the user.
The Instant
class represents a moment on the timeline in UTC with a resolution of nanoseconds (up to nine (9) digits of a decimal fraction). The Instant
is the basic building-block of java.time.
Instant instant = Instant.now(); // UTC
Apply a time zone. Daylight Saving Time (DST) is automatically handled for you. Be sure to read the doc to understand the behavior.
ZoneId z = ZoneId.of( "America/Montreal" );
ZonedDateTime zdt = instant.atZone( z );
To learn much more, search Stack Overflow for these class names as well as ZoneOffset
, OffsetDateTime
, and DateTimeFormatter
.
Updating tzdata
The definitions of time zones around the world change frequently, surprisingly often. And often happen with little forewarning. (Thank you, dear politicians.)
tzdata
in ThreeTen-Backport
The ThreeTen-Backport library contains its own copy of the tzdata
time zone database. The ThreeTen-Backport library is occasionally updated with a fresh copy of the tzdata
. But on occasion a time zone you may care about may be updated at the last minute. In such a situation, you need to update the data yourself inside ThreeTen-Backport. See this page: Update tzdb.
tzdata
in JVM
By the way, your JVM also has a copy of the tzdata. You may want to keep that up-to-date for old code not yet updated to ThreeTen-Backport. See the Oracle Timezone Updater Tool.
tzdata
in the OS
Your operating system also likely has its own copy of the tzdata. You may need to update that as well for all your other non-Java software.
About java.time
The java.time framework is built into Java 8 and later. These classes supplant the troublesome old date-time classes such as java.util.Date
, .Calendar
, & java.text.SimpleDateFormat
.
The Joda-Time project, now in maintenance mode, advises migration to java.time.
To learn more, see the Oracle Tutorial. And search Stack Overflow for many examples and explanations. Specification is JSR 310.
Where to obtain the java.time classes?
- Java SE 8 and SE 9 and later
- Built-in.
- Part of the standard Java API with a bundled implementation.
- Java 9 adds some minor features and fixes.
- Java SE 6 and SE 7
- Much of the java.time functionality is back-ported to Java 6 & 7 in ThreeTen-Backport.
- Android
The ThreeTen-Extra project extends java.time with additional classes. This project is a proving ground for possible future additions to java.time. You may find some useful classes here such as Interval
, YearWeek
, YearQuarter
, and more.