tl;dr
- No need to define the formatting pattern for standard inputs.
- Parse directly into java.time objects.
Examples…
// offset-from-UTC
OffsetDateTime.parse( "2016-01-23T12:34:56.123456789-07:00" )
…
// Z = Zulu = UTC
Instant.parse( "2016-01-23T12:34:56.123456789Z" )
…
// ISO 8601 format extended with time zone name appended in square brackets.
ZonedDateTime.parse( "2016-01-23T12:34:56.123456789-05:30[Asia/Kolkata]" )
Details
The Joda-Time project, now in maintenance mode, advises migration to java.time classes.
java.time
No need for ThreadLocal
as the java.time classes are inherently thread-safe because of they are immutable objects.
The standard ISO 8601 formats for date-time values are used by default in the java.time classes. So generally no need to specify a formatting pattern for such inputs.
Instant
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.parse
method can parse standard input strings ending in Z
, short for Zulu
, meaning UTC.
Instant instant = Instant.parse(
"2016-01-23T12:34:56.123456789Z" );
OffsetDateTime
For standard input strings that include a specific offset-from-UTC, use the OffsetDateTime
class and its parse
method.
OffsetDateTime odt = OffsetDateTime.parse(
"2016-01-23T12:34:56.123456789-07:00" );
ZonedDateTime
The ZonedDateTime
class with its toString
method generates a String in a format that extends beyond the ISO 8601 format by appending the name in square brackets. This is wise, as a time zone is much more than an offset-from-UTC. A time zone is an offset plus a set of rules for handling anomalies such as Daylight Saving Time (DST).
This class can parse as well as generate such strings.
ZonedDateTime zdt = ZonedDateTime.parse(
"2016-01-23T12:34:56.123456789-05:30[Asia/Kolkata]" ) ;
DateTimeFormatter
For non-standard string formats, search Stack Overflow for java.time.format.DateTimeFormatter
class.
Database
To send this value to a database through a JDBC driver supporting JDBC 4.2 or later, use the PreparedStatement::setObject
method and for fetching, the ResultSet::getObject
method.
myPreparedStatement.setObject( … , instant );
If your driver does not comply, fall back to converting to the old java.sql types. Look to the new conversion methods added to the old classes.
java.sql.Timestamp ts = java.sql.Timestamp.from( instant );
About java.time
The java.time framework is built into Java 8 and later. These classes supplant the troublesome old legacy date-time classes such as java.util.Date
, Calendar
, & 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.