Why do you need to know about Java 8 date and time classes? In a lot of
\nJava applications it is necessary to calculate business days, or
\nmanipulate dates for display or export: eg. calendar events. There is
\nalso a lot of old Java code which uses the old date and calendar
\nclasses, that needs to be upgraded for when those classes are no longer
\nsupported. Furthermore, Java 8 makes working with date and time easier.<\/p>\n
Here are some commonly used terms:<\/p>\n
First is or by parsing an ISO datetime string as shown in the example below, If you don\\’t know the zone region for a datetime value, but you still or by parsing an ISO datetime string as shown in the example below, but be aware that the converted object will not contain the daylight If you don\\’t need to deal with offsets and regions then Java provides or by parsing an ISO datetime string as shown in the example below, If you only need to deal with whole days then the These two classes can be combined with a Zone Id to create a Be careful when doing calculations on Java represents Unix time with Note the use of the capital \\’Z\\’ at the end of the datetime string on An instant can be combined with a Zone Id to create a What happens if you omit the zone information when you try to create a An exception, The zone region (\\"[Australia\/Sydney]\\") is actually optional, but What happens if the offset is wrong for the region? eg the offset for A The time is then adjusted for the region rules, which say the offset +<\/sup>11 hours – –<\/sup>5 hours = +<\/sup>16 hours to adjust by.<\/p>\n So the resulting Suppose you want to watch the final stage of Le Tour de France. At the Line 1 starts with today\\’s date in a LocalDate object. Line 2 then uses Note here that the Java 8 date and time objects are immutable! Each of Now suppose that you have a friend in Paris and that you had planned to You can prove that two objects and secondly using the Both the between methods above accept objects that implement the Similarly, be careful when comparing If you swap the comparison order such that the Back to Le Tour de France. Suppose you want to generate an invitation The date and time classes have many methods for adding and subtracting Now suppose that you want to generate a reminder for the party the day When Oracle added the Java 8 date and time classes to the Java standard and java.time.ZonedDateTime<\/code>. This class lets you represent date and
\ntime for anywhere in the world, and it knows the daylight savings
\ntransitions for a great many regions. You can create one by reading the
\nsystem clock as shown:<\/p>\nZonedDateTime now = ZonedDateTime.now();<\/code><\/pre>\n
\nwhich includes zone offset and region. The format is:
\nyyyy-MM-dd\\’T\\’HH:mm:ss.nnnnnnnnnXXX\\'[\\’VV\\’]\\’<\/em> and is called
\nISO_ZONED_DATE_TIME<\/code> in Java. See the Java 8 Javadoc for
\njava.time.format.DateTimeFormatter<\/a>
\nfor more information. The three ZonedDateTime<\/code>s below are equivalent.<\/p>\nfinal String australiaDayStr = "2020-01-26T00:00:00.000000000+11:00[Australia\/Sydney]";\nfinal ZonedDateTime australiaDay1 = ZonedDateTime.parse(australiaDayStr);\nfinal ZonedDateTime australiaDay2 = ZonedDateTime.parse(australiaDayStr, DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss.nnnnnnnnnXXX'['VV']'"));\nfinal ZonedDateTime australiaDay3 = ZonedDateTime.parse(australiaDayStr, DateTimeFormatter.ISO_ZONED_DATE_TIME);<\/code><\/pre>\nOffsetDateTime<\/h3>\n
\nwant to handle zone offsets then Java provides java.time.OffsetDateTime<\/code>.
\nBecause it lacks a zone region, it doesn\\’t know the daylight savings
\ntransitions. You can create one by reading the system clock as shown:<\/p>\nOffsetDateTime now = OffsetDateTime.now();<\/code><\/pre>\n
\nwhich includes zone offset but not the region. The format is:
\nyyyy-MM-dd\\’T\\’HH:mm:ss.nnnnnnnnnXXX<\/em> and is called
\nISO_OFFSET_DATE_TIME<\/code> in Java. See the Java 8 Javadoc for
\njava.time.format.DateTimeFormatter<\/a>
\nfor more information. The three OffsetDateTimes below are equivalent.<\/p>\nfinal String australiaDayStr = "2020-01-26T00:00:00.000000000+11:00";\nfinal OffsetDateTime australiaDay1 = OffsetDateTime.parse(australiaDayStr);\nfinal OffsetDateTime australiaDay2 = OffsetDateTime.parse(australiaDayStr, DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss.nnnnnnnnnXXX"));\nfinal OffsetDateTime australiaDay3 = OffsetDateTime.parse(australiaDayStr, DateTimeFormatter.ISO_OFFSET_DATE_TIME;<\/code><\/pre>\nOffsetDateTime<\/code> is convertable to ZonedDateTime<\/code> via the method:<\/p>\nfinal ZonedDateTime nowZdt = OffsetDateTime.now().toZonedDateTime();<\/code><\/pre>\n
\nsavings transitions because you didn\\’t supply a zone id! If you want to
\ninclude the zone id, then use this technique:<\/p>\nfinal ZonedDateTime nowZdt = OffsetDateTime.now().atZoneSameInstant(ZoneId.of("Australia\/Sydney"));<\/code><\/pre>\nLocalDateTime<\/h3>\n
\njava.time.LocalDateTime<\/code>. This class stores dates and times that are not
\nconnected to a particular place. You can create one by reading the
\nsystem clock as shown:<\/p>\nLocalDateTime now = LocalDateTime.now();<\/code><\/pre>\n
\nwhich includes neither the zone offset nor the region. The format is:
\nyyyy-MM-dd\\’T\\’HH:mm:ss.nnnnnnnnn<\/em> and is called ISO_LOCAL_DATE_TIME<\/code> in
\nJava. See the Java 8 Javadoc for
\njava.time.format.DateTimeFormatter<\/a>
\nfor more information. The three LocalDateTimes below are equivalent.<\/p>\nfinal String australiaDayStr = "2020-01-26T00:00:00.000000000";\nfinal LocalDateTime australiaDay1 = LocalDateTime.parse(australiaDayStr);\nfinal LocalDateTime australiaDay2 = LocalDateTime.parse(australiaDayStr, DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss.nnnnnnnnn"));\nfinal LocalDateTime australiaDay3 = LocalDateTime.parse(australiaDayStr, DateTimeFormatter.ISO_LOCAL_DATE_TIME);<\/code><\/pre>\nLocalDateTime<\/code> can be combined with a Zone Id to create a ZonedDateTime<\/code>
\nvia:<\/p>\nfinal LocalDateTime australiaDayLdt = LocalDateTime.parse("2020-01-26T00:00:00.000000000");\nfinal ZonedDateTime australiaDayZdt = ZonedDateTime.of(australiaDayLdt, ZoneId.of("Australia\/Sydney"));<\/code><\/pre>\nLocalDate and LocalTime<\/h3>\n
java.time.LocalDate<\/code>
\nclass is very handy. Similarly if you only need to deal with times, then
\nJava provides the java.time.LocalTime<\/code> class. Both can be created by
\nreading the system clock, or by parsing a string in the correct format.<\/p>\nLocalDate today = LocalDate.now();\nLocalTime now = LocalTime.now();<\/code><\/pre>\n
\nZonedDateTime<\/code>:<\/p>\nLocalDate australiaDay = LocalDate.parse("2020-01-26");\nLocalTime midnight = LocalTime.parse("00:00:00");\nZonedDateTime australiaDayZdt = ZonedDateTime.of(australiaDay, midnight, ZoneId.of("Australia\/Sydney"));<\/code><\/pre>\nLocalDate<\/code> and LocalTime<\/code>! If you
\ntry, for example, to calculate the number of hours difference between
\ntwo LocalDate<\/code>s, the code might compile but then fail at runtime, because
\nLocalDate<\/code> has no hours component and doesn\\’t know how to work with
\nthem.<\/p>\nInstant<\/h3>\n
java.time.Instant<\/code>. Objects of this class
\nstore the number of seconds since midnight, 1st<\/sup> Jan 1970 UTC, to
\nnanosecond (10-9<\/sup> s) precision. Instants are always in UTC and are not
\nregion-aware. An instant can be created by reading from the system
\nclock, parsing a datetime string, or reading in a whole number of
\nseconds, for example:<\/p>\nInstant now = Instant.now();\nInstant australiaDayUnix = Instant.parse("2020-01-25T13:00:00Z");\nInstant australiaDayUnix2 = Instant.ofEpochSecond(1579957200);<\/code><\/pre>\n
\nline 2, which denotes UTC.<\/p>\nZonedDateTime<\/code> as
\nshown below:<\/p>\nZonedDateTime australiaDayZdt = ZonedDateTime.ofInstant(australiaDayUnix, ZoneId.of("Australia\/Sydney"));<\/code><\/pre>\nTest Your Knowledge<\/h3>\n
Question 1<\/h4>\n
\nZonedDateTime<\/code>, as shown in the example below?<\/p>\nZonedDateTime australiaDay = ZonedDateTime.parse("2020-01-26T00:00:00");<\/code><\/pre>\njava.time.format.DateTimeParseException<\/code>, is thrown at
\nruntime. The three components necessary to create a ZonedDateTime<\/code> are:<\/p>\n\n
\nwithout it the ZonedDateTime<\/code> will not contain the daylight savings
\ntransitions.<\/p>\nQuestion 2<\/h4>\n
\nSydney during summer is UTC+11:00 but the offset given in the example
\nbelow is UTC-05:00.<\/p>\nZonedDateTime weird = ZonedDateTime.parse("2020-01-26T00:00:00-05:00[Australia\/Sydney]");<\/code><\/pre>\nZonedDateTime<\/code> is created! Java uses the region to decide what the
\noffset should be and adjusts the time accordingly. So in the above
\nexample:<\/p>\n\n
\nshould be UTC+11:00:<\/p>\nZonedDateTime<\/code> is equivalent to:<\/p>\n<\/li>\n<\/ol>\nZonedDateTime.parse("2020-01-26T16:00:00+11:00[Australia\/Sydney]");<\/code><\/pre>\nManipulating Dates and Times<\/h2>\n
\ntime of writing (Tuesday 15th<\/sup> Sep 2020), the race starts at 11:30 pm
\nthis Sunday, Sydney time. You could do that many ways, but here is one
\nway that illustrates a few of the classes that we\\’ve already discussed:<\/p>\nimport java.time.DayOfWeek;\nimport java.time.LocalDate;\nimport java.time.ZonedDateTime;\nimport java.time.ZoneId;\n...\nZonedDateTime tdfFinalSydney = LocalDate.now()\n .with(TemporalAdjusters.next(DayOfWeek.SUNDAY))\n .atTime(23,30,0)\n .atZone(ZoneId.of("Australia\/Sydney"));<\/code><\/pre>\n
\nJava\\’s very handy
\nTemporalAdjusters<\/a>
\nclass with the DayOfWeek.SUNDAY<\/code> enum to advance the date to this Sunday.
\nTemporalAdjusters<\/code> provides methods to calculate the next and previous
\ndays of the week, the first and last days of the month and the year, and
\nthe first date of next year, amongst others. Do check it out. Line 3
\nthen adds a time component in 24 h time, which is 11:30 pm. This method
\nreturns a LocalDateTime object. Finally, line 4 adds a zone component to
\ninternationalise the date and time in a ZonedDateTime<\/code> object. The
\nclasses LocalDate<\/code>, LocalTime<\/code>, LocalDateTime<\/code>, OffsetDateTime<\/code>, and
\nZonedDateTime<\/code> share a lot of methods in common and can be transformed
\nfrom one to the other, so it is very easy work with them once you learn
\nthe patterns.<\/p>\n
\nthe methods which operates on a Java 8 date or time object (in the
\njava.time<\/code> package), such as is shown in the example above, creates a new
\nobject and returns it. In the four lines of code above, we performed
\nfour operations and created four new objects, although we only retained
\nthe last one created. This design seems strange compared to the old Java
\nDate<\/code> and Calendar<\/code> classes, but it actually simplifies the programming
\nmodel greatly, and lends itself towards a functional programming style
\nof working, which is the direction that Java has been going recently.<\/p>\nWhen is the Final of Le Tour De France, Paris Time?<\/h3>\n
\nwatch the race together. You would calculate the correct time in Paris
\nfor the start of the race as follows:<\/p>\nimport java.time.ZonedDateTime;\nimport java.time.ZoneId;\n...\nZonedDateTime tdfFinalParis = tdfFinalSydney.withZoneSameInstant(ZoneId.of("Europe\/Paris"));<\/code><\/pre>\ntdfFinalSydney<\/code> and tdfFinalParis<\/code>, which
\nrepresent the start of the race in Sydney and Paris respectively,
\nrepresent the same moment in time and have no time difference between
\nthem. Java provides at least two ways to do this, first using the
\nChronoUnit.HOURS<\/a>
\nenum:<\/p>\nimport org.junit.jupiter.api.Assertions; \/\/only import this in a JUnit test, not in your main code!\nimport java.time.temporal.ChronoUnit;\nimport java.time.ZonedDateTime;\n...\nfinal long difference = ChronoUnit.HOURS.between(tdfFinalParis, tdfFinalSydney);\nAssertions.assertEquals(0, difference);<\/code><\/pre>\n
\nDuration<\/a>
\nclass as follows:<\/p>\nimport org.junit.jupiter.api.Assertions; \/\/only import this in a JUnit test, not in your main code!\nimport java.time.Duration;\nimport java.time.ZonedDateTime;\n...\nDuration difference = Duration.between(tdfFinalParis, tdfFinalSydney);\nAssertions.assertEquals(0, difference.getSeconds());<\/code><\/pre>\nBe Careful!<\/h3>\n
\nTemporal<\/a>
\ninterface, which includes instances of the date and time classes we have
\nalready introduced. Be careful, however, because not all of those
\nclasses will work here, even if the code compiles! For example, if you
\ntry to calculate the difference between two LocalDate<\/code> objects as a
\nDuration<\/code>, you will get an UnsupportedTemporalTypeException<\/code> at runtime,
\nwith a message \\"Unsupported unit: Seconds\\", because LocalDate<\/code> is does
\nnot have a time component and does not know what seconds are. eg:<\/p>\nimport org.junit.jupiter.api.Assertions; \/\/only import this in a JUnit test, not in your main code!\nimport java.time.Duration;\nimport java.time.LocalDate;\nimport java.time.temporal.UnsupportedTemporalTypeException;\n...\nAssertions.assertThrows(UnsupportedTemporalTypeException.class, () -> {\n LocalDate today = LocalDate.now();\n LocalDate tomorrow = today.plusDays(1);\n Duration.between(today, tomorrow); \/\/throws here!\n});<\/code><\/pre>\nTemporal<\/code>s of different implementing
\nclasses. For example, comparing a ZonedDateTime<\/code> with a LocalDateTime<\/code>
\ndoesn\\’t work with the ZonedDateTime<\/code> on the left hand side of the
\ncomparison, because the LocalDateTime<\/code> doesn\\’t know about zone regions.
\neg the following example compiles but fails with a DateTimeException<\/code>,
\n\\"Unable to obtain ZonedDateTime from TemporalAccessor…\\":<\/p>\nimport org.junit.jupiter.api.Assertions; \/\/only import this in a JUnit test, not in your main code!\nimport java.time.DateTimeException;\nimport java.time.Duration;\nimport java.time.LocalDateTime;\nimport java.time.ZonedDateTime;\n...\nAssertions.assertThrows(DateTimeException.class, () -> {\n ZonedDateTime todayZdt = ZonedDateTime.now();\n LocalDateTime laterLdt = todayZdt.toLocalDateTime().plusMinutes(1);\n Duration.between(todayZdt, laterLdt); \/\/ throws here!\n});<\/code><\/pre>\nLocalDateTime<\/code> is on the
\nleft hand side, however, the comparison works:<\/p>\nimport org.junit.jupiter.api.Assertions; \/\/only import this in a JUnit test, not in your main code!\nimport java.time.Duration;\nimport java.time.LocalDateTime;\nimport java.time.ZonedDateTime;\n...\nLocalDateTime todayLdt = LocalDateTime.now();\nZonedDateTime laterZdt = todayLdt.plusMinutes(1).atZone(ZoneId.of("Australia\/Sydney"));\nAssertions.assertEquals("PT1M", Duration.between(todayLdt, laterZdt).toString())<\/code><\/pre>\nThrow a Party, not an Exception!<\/h3>\n
\nfor a party via your favourite video conferencing application, and send
\nit to your friend in Paris. The party starts one hour before the race
\nstarts. Java provides at least three ways for you to do this:<\/p>\nimport java.time.temporal.ChronoUnit;\nimport java.time.Duration;\nimport java.time.ZonedDateTime;\n...\nZonedDateTime zoomPartyParis1 = tdfFinalParis.minusHours(1);\nZonedDateTime zoomPartyParis2 = tdfFinalParis.minus(Duration.ofHours(1));\nZonedDateTime zoomPartyParis3 = tdfFinalParis.minus(1, ChronoUnit.HOURS);<\/code><\/pre>\n
\ntime, a few of which are shown above. They range from minusNanos(long)<\/code>
\nto plusYears(long)<\/code>, as well as general purpose methods which accept a
\nPeriod<\/a>
\n(days, months, years or longer) or a Duration<\/code> (hours, minutes, seconds,
\nor shorter), or an arbitrary ChronoUnit<\/code> (from nanoseconds to millenia).<\/p>\n
\nbefore, so that you have sufficient time to go shopping for drinks and
\nsnacks. Java provides at least three ways for you to do this:<\/p>\nimport java.time.temporal.ChronoUnit;\nimport java.time.Period;\nimport java.time.ZonedDateTime;\n...\nZonedDateTime zoomPartyReminderParis1 = zoomPartyParis1.minusDays(1);\nZonedDateTime zoomPartyReminderParis2 = zoomPartyParis1.minus(Period.ofDays(1));\nZonedDateTime zoomPartyReminderParis3 = zoomPartyParis1.minus(1, ChronoUnit.DAYS);<\/code><\/pre>\nOld to New<\/h2>\n
\nlibrary, it deprecated many of the methods in the old Date<\/code> and Calendar<\/code>
\nclasses, and also made the old classes aware of some of the new classes,
\nto enable easy conversion between them. So if you need to support APIs
\nwhich rely on the old classes, you can still expose the old classes in
\nyour API while using the new classes underneath. Note, however, that the
\nnew classes have an entirely different set of methods, so your old code
\nwill need to be reengineered heavily. Java lets you convert between old
\nand new classes as shown in the example below, with Date<\/code> being replaced
\nby Instant<\/code>:<\/p>\nimport java.util.Date;\nimport java.time.Instant;\n...\nDate now = Date.from(Instant.now());\nInstant now2 = new Date().toInstant();<\/code><\/pre>\nGregorianCalendar<\/code> being replaced by ZonedDateTime<\/code>:<\/p>\nimport java.util.GregorianCalendar;\nimport java.time.ZonedDateTime;\n...\nGregorianCalendar tdfFinalSydneyGregorian = GregorianCalendar.from(tdfFinalSydney);\nZonedDateTime tdfFinalSydney2 = tdfFinalSydneyGregorian.toZonedDateTime();<\/code><\/pre>\nFurther Reading<\/h2>\n