Notes on Java DateTime

Java Data Time

In modern Java (after Java 8), we use the pacakage java.time.* to represent DataTime. This is much better than the java.util classes. For interoperability, we have methods in the java.util.* package, that can convert from the older java.util.Date to the newer types.

Instant

An instantaneous point on the time-line (with a precision of nano seconds). It models a single instantaneous point on the time-line. This might be used to record event time-stamps in the application. The epoch-seconds are measured from the standard Java epoch of 1970-01-01T00:00:00Z where instants after the epoch have positive values, and earlier instants have negative values.

Duration

This models a quantity or amount of time in terms of seconds and nanoseconds. It can be accessed using other duration-based units, such as minutes and hours. In addition, the DAYS unit can be used and is treated as exactly equal to 24 hours, thus ignoring daylight savings effects. Durations can also be negative.

UTC

Internationally accepted way of reprecenting Data and Time as defined by ISO 8601. The Epoch time can be represented as:

1970-01-01T00:00:00Z -> Time with UTC Time-Zone
1969-12-31T19:00:00-05:00 -> Time in New York at UTC Epoch (which is 5 hrs behind UTC)

LocalDate

A date without a time-zone in the ISO-8601 calendar system, such as 1969-12-31. Does not contain time or time-zone information. This is just the fist part of the UTC dataTime reprecentation (without time and time-zone information). e.g. Birthday. Independant of time-zone.

LocalTime

A time without a time-zone in the ISO-8601 calendar system, such as 10:15:30. This is just the time part of the UTC dataTime reprecentation (without date and time-zone information).

LocalDateTime

A date-time without a time-zone in the ISO-8601 calendar system, such as 1970-01-01T00:00. This class does not store or represent a time-zone. Instead, it is a description of the date, as used for birthdays, combined with the local time as seen on a wall clock.

ZoneOffset

A time-zone offset is the amount of time that a time-zone differs from Greenwich/UTC.

ZoneOffset.of("+7");
==> +07:00

ZonedDateTime

A date-time with a time-zone in the ISO-8601 calendar system, such as 2007-12-03T10:15:30+01:00 Europe/Paris. e.g. Start of a conference call.

Period

A date-based amount of time in the ISO-8601 calendar system, such as '2 years, 3 months and 4 days'. This is based on the human time based on calendar. This is not based on Duration.

DateTimeFormatter

Helps conver string to java Date-Time and back.

Temporal

Interface for exposing read-write access to temporal objects:

├──OffsetTime
├──ChronoLocalDate
├──ChronoLocalDateImpl
├──ChronoLocalDateTime
│  └──LocalDateTime
├──ZonedDateTime
├──LocalDateTime
├──Instant
├──ChronoZonedDateTime
│  └──ZonedDateTime
├──OffsetDateTime
├──Year
├──ChronoLocalDateTimeImpl
├──LocalDate
├──LocalTime
└──YearMonth

This interface exposes methods like

plus(long amountToAdd, TemporalUnit unit);
minus(long amountToSubtract, TemporalUnit unit)
get()
query()
range()

Emample code

// Tomorrow with Zone information
ZonedDateTime.now().plusDays(1).truncatedTo(ChronoUnit.DAYS)

// Yesterday without TimeZone information
LocalDateTime.now().minusDays(1).truncatedTo(ChronoUnit.DAYS)

// Use the plus/minus methods which take a Duration (absolute time or Period (days, months etc.) 
// as adjustment operators

LocalDateTime.now().plus(Duration.of(5, ChronoUnit.DAYS)); // Add 5 days to today

LocalDateTime.now().plus(Period.ofMonths(2)); // Add two months to today

Converting between types

java.util.Date <-> java.time.LocalDate

Date input = new Date();
LocalDate date = input.toInstant().atZone(ZoneId.systemDefault()).toLocalDate();

https://stackoverflow.com/questions/21242110/convert-java-util-date-to-java-time-localdate http://time4j.net/tutorial/appendix.html

georgeck/DateTime.md