{"id":22197,"date":"2014-03-03T19:00:24","date_gmt":"2014-03-03T17:00:24","guid":{"rendered":"http:\/\/www.javacodegeeks.com\/?p=22197"},"modified":"2014-03-03T11:28:28","modified_gmt":"2014-03-03T09:28:28","slug":"a-deeper-look-into-the-java-8-date-and-time-api","status":"publish","type":"post","link":"https:\/\/www.javacodegeeks.com\/2014\/03\/a-deeper-look-into-the-java-8-date-and-time-api.html","title":{"rendered":"A deeper look into the Java 8 Date and Time API"},"content":{"rendered":"

Within this post we will have a deeper look into the new Date\/Time API we get with Java 8 (
\nJSR 310<\/a>). Please note that this post is mainly driven by code examples that show the new API functionality. I think the examples are self-explanatory so I did not spent much time writing text around them :-)<\/p>\n

Let’s get started!<\/p>\n

Working with date and time objects<\/h2>\n

All classes of the Java 8 Date\/Time API are located within the java.time package. The first class we want to look at is java.time.LocalDate. A LocalDate<\/a> represents a year-month-day date without time. We start with creating new LocalDate instances:<\/p>\n

\/\/\u00a0the\u00a0current\u00a0date\r\nLocalDate\u00a0currentDate\u00a0=\u00a0LocalDate.now();\r\n\r\n\/\/\u00a02014-02-10\r\nLocalDate\u00a0tenthFeb2014\u00a0=\u00a0LocalDate.of(2014,\u00a0Month.FEBRUARY,\u00a010);\r\n\r\n\/\/\u00a0months\u00a0values\u00a0start\u00a0at\u00a01\u00a0(2014-08-01)\r\nLocalDate\u00a0firstAug2014\u00a0=\u00a0LocalDate.of(2014,\u00a08,\u00a01);\r\n\r\n\/\/\u00a0the\u00a065th\u00a0day\u00a0of\u00a02010\u00a0(2010-03-06)\r\nLocalDate\u00a0sixtyFifthDayOf2010\u00a0=\u00a0LocalDate.ofYearDay(2010,\u00a065);<\/pre>\n
LocalTime<\/a> and LocalDateTime<\/a> are the next classes we look at. Both work similar to LocalDate. A LocalTime works with time (without dates) while LocalDateTime combines date and time in one class:<\/p>\n
LocalTime\u00a0currentTime\u00a0=\u00a0LocalTime.now();\u00a0\/\/\u00a0current\u00a0time\r\nLocalTime\u00a0midday\u00a0=\u00a0LocalTime.of(12,\u00a00);\u00a0\/\/\u00a012:00\r\nLocalTime\u00a0afterMidday\u00a0=\u00a0LocalTime.of(13,\u00a030,\u00a015);\u00a0\/\/\u00a013:30:15\r\n\r\n\/\/\u00a012345th\u00a0second\u00a0of\u00a0day\u00a0(03:25:45)\r\nLocalTime\u00a0fromSecondsOfDay\u00a0=\u00a0LocalTime.ofSecondOfDay(12345);\r\n\r\n\/\/\u00a0dates\u00a0with\u00a0times,\u00a0e.g.\u00a02014-02-18 19:08:37.950\r\nLocalDateTime\u00a0currentDateTime\u00a0=\u00a0LocalDateTime.now();\r\n\r\n\/\/\u00a02014-10-02\u00a012:30\r\nLocalDateTime\u00a0secondAug2014\u00a0=\u00a0LocalDateTime.of(2014,\u00a010,\u00a02,\u00a012,\u00a030);\r\n\r\n\/\/\u00a02014-12-24\u00a012:00\r\nLocalDateTime\u00a0christmas2014\u00a0=\u00a0LocalDateTime.of(2014,\u00a0Month.DECEMBER,\u00a024,\u00a012,\u00a00);<\/pre>\n
By default LocalDate\/Time classes will use the system clock in the default time zone. We can change this by providing a time zone or an alternative Clock<\/a> implementation:<\/p>\n
\/\/\u00a0current\u00a0(local)\u00a0time\u00a0in\u00a0Los\u00a0Angeles\r\nLocalTime\u00a0currentTimeInLosAngeles\u00a0=\u00a0LocalTime.now(ZoneId.of(\"America\/Los_Angeles\"));\r\n\r\n\/\/\u00a0current\u00a0time\u00a0in\u00a0UTC\u00a0time\u00a0zone\r\nLocalTime\u00a0nowInUtc\u00a0=\u00a0LocalTime.now(Clock.systemUTC());<\/pre>\n
From LocalDate\/Time objects we can get all sorts of useful information we might need. Some examples:<\/p>\n
LocalDate\u00a0date\u00a0=\u00a0LocalDate.of(2014,\u00a02,\u00a015);\u00a0\/\/\u00a02014-02-15\r\n\r\nboolean\u00a0isBefore\u00a0=\u00a0LocalDate.now().isBefore(date);\u00a0\/\/\u00a0false\r\n\r\n\/\/\u00a0information\u00a0about\u00a0the\u00a0month\r\nMonth\u00a0february\u00a0=\u00a0date.getMonth();\u00a0\/\/\u00a0FEBRUARY\r\nint\u00a0februaryIntValue\u00a0=\u00a0february.getValue();\u00a0\/\/\u00a02\r\nint\u00a0minLength\u00a0=\u00a0february.minLength();\u00a0\/\/\u00a028\r\nint\u00a0maxLength\u00a0=\u00a0february.maxLength();\u00a0\/\/\u00a029\r\nMonth\u00a0firstMonthOfQuarter\u00a0=\u00a0february.firstMonthOfQuarter();\u00a0\/\/\u00a0JANUARY\r\n\r\n\/\/\u00a0information\u00a0about\u00a0the\u00a0year\r\nint\u00a0year\u00a0=\u00a0date.getYear();\u00a0\/\/\u00a02014\r\nint\u00a0dayOfYear\u00a0=\u00a0date.getDayOfYear();\u00a0\/\/\u00a046\r\nint\u00a0lengthOfYear\u00a0=\u00a0date.lengthOfYear();\u00a0\/\/\u00a0365\r\nboolean\u00a0isLeapYear\u00a0=\u00a0date.isLeapYear();\u00a0\/\/\u00a0false\r\n\r\nDayOfWeek\u00a0dayOfWeek\u00a0=\u00a0date.getDayOfWeek();\r\nint\u00a0dayOfWeekIntValue\u00a0=\u00a0dayOfWeek.getValue();\u00a0\/\/\u00a06\r\nString\u00a0dayOfWeekName\u00a0=\u00a0dayOfWeek.name();\u00a0\/\/\u00a0SATURDAY\r\n\r\nint\u00a0dayOfMonth\u00a0=\u00a0date.getDayOfMonth();\u00a0\/\/\u00a015\r\nLocalDateTime\u00a0startOfDay\u00a0=\u00a0date.atStartOfDay();\u00a0\/\/\u00a02014-02-15 00:00\r\n\r\n\/\/\u00a0time\u00a0information\r\nLocalTime\u00a0time\u00a0=\u00a0LocalTime.of(15,\u00a030);\u00a0\/\/\u00a015:30:00\r\nint\u00a0hour\u00a0=\u00a0time.getHour();\u00a0\/\/\u00a015\r\nint\u00a0second\u00a0=\u00a0time.getSecond();\u00a0\/\/\u00a00\r\nint\u00a0minute\u00a0=\u00a0time.getMinute();\u00a0\/\/\u00a030\r\nint\u00a0secondOfDay\u00a0=\u00a0time.toSecondOfDay();\u00a0\/\/\u00a055800<\/pre>\n
Some information can be obtained without providing a specific date. For example, we can use the Year<\/a> class if we need information about a specific year:<\/p>\n
Year\u00a0currentYear\u00a0=\u00a0Year.now();\r\nYear\u00a0twoThousand\u00a0=\u00a0Year.of(2000);\r\nboolean\u00a0isLeap\u00a0=\u00a0currentYear.isLeap();\u00a0\/\/\u00a0false\r\nint\u00a0length\u00a0=\u00a0currentYear.length();\u00a0\/\/\u00a0365\r\n\r\n\/\/\u00a0sixtyFourth\u00a0day\u00a0of\u00a02014\u00a0(2014-03-05)\r\nLocalDate\u00a0date\u00a0=\u00a0Year.of(2014).atDay(64);<\/pre>\n
We can use the plus and minus methods to add or subtract specific amounts of time. Note that these methods always return a new instance (Java 8 date\/time classes are immutable).
 
<\/div> <\/div><\/p>\n
LocalDate\u00a0tomorrow\u00a0=\u00a0LocalDate.now().plusDays(1);\r\n\r\n\/\/\u00a0before\u00a05\u00a0houres\u00a0and\u00a030\u00a0minutes\r\nLocalDateTime\u00a0dateTime\u00a0=\u00a0LocalDateTime.now().minusHours(5).minusMinutes(30);<\/pre>\n
TemporalAdjusters are another nice way for date manipulation. TemporalAdjuster<\/a> is a single method interface that is used to separate the process of adjustment from actual date\/time objects. A set of common TemporalAdjusters can be accessed using static methods of the TemporalAdjusters<\/a> class.<\/p>\n
LocalDate\u00a0date\u00a0=\u00a0LocalDate.of(2014,\u00a0Month.FEBRUARY,\u00a025);\u00a0\/\/\u00a02014-02-25\r\n\r\n\/\/\u00a0first\u00a0day\u00a0of\u00a0february\u00a02014\u00a0(2014-02-01)\r\nLocalDate\u00a0firstDayOfMonth\u00a0=\u00a0date.with(TemporalAdjusters.firstDayOfMonth());\r\n\r\n\/\/\u00a0last\u00a0day\u00a0of\u00a0february\u00a02014\u00a0(2014-02-28)\r\nLocalDate\u00a0lastDayOfMonth\u00a0=\u00a0date.with(TemporalAdjusters.lastDayOfMonth());<\/pre>\n
Static imports make this more fluent to read:<\/p>\n
import\u00a0static\u00a0java.time.temporal.TemporalAdjusters.*;\r\n\r\n...\r\n\r\n\/\/\u00a0last\u00a0day\u00a0of\u00a02014\u00a0(2014-12-31)\r\nLocalDate\u00a0lastDayOfYear\u00a0=\u00a0date.with(lastDayOfYear());\r\n\r\n\/\/\u00a0first\u00a0day\u00a0of\u00a0next\u00a0month\u00a0(2014-03-01)\r\nLocalDate\u00a0firstDayOfNextMonth\u00a0=\u00a0date.with(firstDayOfNextMonth());\r\n\r\n\/\/\u00a0next\u00a0sunday\u00a0(2014-03-02)\r\nLocalDate\u00a0nextSunday\u00a0=\u00a0date.with(next(DayOfWeek.SUNDAY));<\/pre>\n
Time zones<\/h2>\n
Working with time zones is another big topic that is simplified by the new API. The LocalDate\/Time classes we have seen so far do not contain information about a time zone. If we want to work with a date\/time in a certain time zone we can use ZonedDateTime<\/a> or OffsetDateTime<\/a>:<\/p>\n
ZoneId\u00a0losAngeles\u00a0=\u00a0ZoneId.of(\"America\/Los_Angeles\");\r\nZoneId\u00a0berlin\u00a0=\u00a0ZoneId.of(\"Europe\/Berlin\");\r\n\r\n\/\/\u00a02014-02-20\u00a012:00\r\nLocalDateTime\u00a0dateTime\u00a0=\u00a0LocalDateTime.of(2014,\u00a002,\u00a020,\u00a012,\u00a00);\r\n\r\n\/\/\u00a02014-02-20\u00a012:00,\u00a0Europe\/Berlin\u00a0(+01:00)\r\nZonedDateTime\u00a0berlinDateTime\u00a0=\u00a0ZonedDateTime.of(dateTime,\u00a0berlin);\r\n\r\n\/\/\u00a02014-02-20\u00a003:00,\u00a0America\/Los_Angeles\u00a0(-08:00)\r\nZonedDateTime\u00a0losAngelesDateTime\u00a0=\u00a0berlinDateTime.withZoneSameInstant(losAngeles);\r\n\r\nint\u00a0offsetInSeconds\u00a0=\u00a0losAngelesDateTime.getOffset().getTotalSeconds();\u00a0\/\/\u00a0-28800\r\n\r\n\/\/\u00a0a\u00a0collection\u00a0of\u00a0all\u00a0available\u00a0zones\r\nSet<String>\u00a0allZoneIds\u00a0=\u00a0ZoneId.getAvailableZoneIds();\r\n\r\n\/\/\u00a0using\u00a0offsets\r\nLocalDateTime\u00a0date\u00a0=\u00a0LocalDateTime.of(2013,\u00a0Month.JULY,\u00a020,\u00a03,\u00a030);\r\nZoneOffset\u00a0offset\u00a0=\u00a0ZoneOffset.of(\"+05:00\");\r\n\r\n\/\/\u00a02013-07-20 03:30\u00a0+05:00\r\nOffsetDateTime\u00a0plusFive\u00a0=\u00a0OffsetDateTime.of(date,\u00a0offset);\r\n\r\n\/\/\u00a02013-07-19\u00a020:30\u00a0-02:00\r\nOffsetDateTime\u00a0minusTwo\u00a0=\u00a0plusFive.withOffsetSameInstant(ZoneOffset.ofHours(-2));<\/pre>\n
Timestamps<\/h2>\n
Classes like LocalDate and ZonedDateTime provide a human view on time. However, often we need to work with time viewed from a machine perspective. For this we can use the Instant<\/a> class which represents timestamps. An Instant counts the time beginning from the first second of January 1, 1970 (1970-01-01 00:00:00) also called the EPOCH<\/a>. Instant values can be negative if they occured before the epoch. They follow ISO 8601<\/a> the standard for representing date and time.<\/p>\n
\/\/\u00a0current\u00a0time\r\nInstant\u00a0now\u00a0=\u00a0Instant.now();\r\n\r\n\/\/\u00a0from\u00a0unix\u00a0timestamp,\u00a02010-01-01\u00a012:00:00\r\nInstant\u00a0fromUnixTimestamp\u00a0=\u00a0Instant.ofEpochSecond(1262347200);\r\n\r\n\/\/\u00a0same\u00a0time\u00a0in\u00a0millis\r\nInstant\u00a0fromEpochMilli\u00a0=\u00a0Instant.ofEpochMilli(1262347200000l);\r\n\r\n\/\/\u00a0parsing\u00a0from\u00a0ISO\u00a08601\r\nInstant\u00a0fromIso8601\u00a0=\u00a0Instant.parse(\"2010-01-01T12:00:00Z\");\r\n\r\n\/\/\u00a0toString()\u00a0returns\u00a0ISO\u00a08601\u00a0format, e.g. 2014-02-15T01:02:03Z\r\nString\u00a0toIso8601\u00a0=\u00a0now.toString();\r\n\r\n\/\/\u00a0as\u00a0unix\u00a0timestamp\r\nlong\u00a0toUnixTimestamp\u00a0=\u00a0now.getEpochSecond();\r\n\r\n\/\/\u00a0in\u00a0millis\r\nlong\u00a0toEpochMillis\u00a0=\u00a0now.toEpochMilli();\r\n\r\n\/\/ plus\/minus methods are available too\r\nInstant\u00a0nowPlusTenSeconds\u00a0=\u00a0now.plusSeconds(10);<\/pre>\n
Periods and Durations<\/h2>\n
Period<\/a> and Duration<\/a> are two other important classes. Like the names suggest they represent a quantity or amount of time. A Period uses date based values (years, months, days) while a Duration uses seconds or nanoseconds to define an amount of time. Duration is most suitable when working with Instants and machine time. Periods and Durations can contain negative values if the end point occurs before the starting point.<\/p>\n
\/\/\u00a0periods\r\n\r\nLocalDate\u00a0firstDate\u00a0=\u00a0LocalDate.of(2010,\u00a05,\u00a017);\u00a0\/\/\u00a02010-05-17\r\nLocalDate\u00a0secondDate\u00a0=\u00a0LocalDate.of(2015,\u00a03,\u00a07);\u00a0\/\/\u00a02015-03-07\r\nPeriod\u00a0period\u00a0=\u00a0Period.between(firstDate,\u00a0secondDate);\r\n\r\nint\u00a0days\u00a0=\u00a0period.getDays();\u00a0\/\/\u00a018\r\nint\u00a0months\u00a0=\u00a0period.getMonths();\u00a0\/\/\u00a09\r\nint\u00a0years\u00a0=\u00a0period.getYears();\u00a0\/\/\u00a04\r\nboolean\u00a0isNegative\u00a0=\u00a0period.isNegative();\u00a0\/\/\u00a0false\r\n\r\nPeriod\u00a0twoMonthsAndFiveDays\u00a0=\u00a0Period.ofMonths(2).plusDays(5);\r\nLocalDate\u00a0sixthOfJanuary\u00a0=\u00a0LocalDate.of(2014,\u00a01,\u00a06);\r\n\r\n\/\/\u00a0add\u00a0two\u00a0months\u00a0and\u00a0five\u00a0days\u00a0to\u00a02014-01-06,\u00a0result\u00a0is\u00a02014-03-11\r\nLocalDate\u00a0eleventhOfMarch\u00a0=\u00a0sixthOfJanuary.plus(twoMonthsAndFiveDays);\r\n\r\n\/\/\u00a0durations\r\n\r\nInstant\u00a0firstInstant=\u00a0Instant.ofEpochSecond(\u00a01294881180\u00a0);\u00a0\/\/\u00a02011-01-13\u00a001:13\r\nInstant\u00a0secondInstant\u00a0=\u00a0Instant.ofEpochSecond(1294708260);\u00a0\/\/\u00a02011-01-11\u00a001:11\r\n\r\nDuration\u00a0between\u00a0=\u00a0Duration.between(firstInstant,\u00a0secondInstant);\r\n\r\n\/\/\u00a0negative\u00a0because\u00a0firstInstant\u00a0is\u00a0after\u00a0secondInstant\u00a0(-172920)\r\nlong\u00a0seconds\u00a0=\u00a0between.getSeconds();\r\n\r\n\/\/\u00a0get\u00a0absolute\u00a0result\u00a0in\u00a0minutes\u00a0(2882)\r\nlong\u00a0absoluteResult\u00a0=\u00a0between.abs().toMinutes();\r\n\r\n\/\/\u00a0two\u00a0hours\u00a0in\u00a0seconds\u00a0(7200)\r\nlong\u00a0twoHoursInSeconds\u00a0=\u00a0Duration.ofHours(2).getSeconds();<\/pre>\n
Formatting and parsing<\/h2>\n
Formatting and parsing is another big topic when working with dates and times. In Java 8 this can be accomplished by using the format() and parse() methods:<\/p>\n
\/\/\u00a02014-04-01\u00a010:45\r\nLocalDateTime\u00a0dateTime\u00a0=\u00a0LocalDateTime.of(2014,\u00a0Month.APRIL,\u00a01,\u00a010,\u00a045);\r\n\r\n\/\/\u00a0format\u00a0as\u00a0basic\u00a0ISO\u00a0date\u00a0format\u00a0(20140220)\r\nString\u00a0asBasicIsoDate\u00a0=\u00a0dateTime.format(DateTimeFormatter.BASIC_ISO_DATE);\r\n\r\n\/\/\u00a0format\u00a0as\u00a0ISO\u00a0week\u00a0date\u00a0(2014-W08-4)\r\nString\u00a0asIsoWeekDate\u00a0=\u00a0dateTime.format(DateTimeFormatter.ISO_WEEK_DATE);\r\n\r\n\/\/\u00a0format\u00a0ISO\u00a0date\u00a0time\u00a0(2014-02-20T20:04:05.867)\r\nString\u00a0asIsoDateTime\u00a0=\u00a0dateTime.format(DateTimeFormatter.ISO_DATE_TIME);\r\n\r\n\/\/\u00a0using\u00a0a\u00a0custom\u00a0pattern\u00a0(01\/04\/2014)\r\nString\u00a0asCustomPattern\u00a0=\u00a0dateTime.format(DateTimeFormatter.ofPattern(\"dd\/MM\/yyyy\"));\r\n\r\n\/\/\u00a0french\u00a0date\u00a0formatting\u00a0(1.\u00a0avril\u00a02014)\r\nString\u00a0frenchDate\u00a0=\u00a0dateTime.format(DateTimeFormatter.ofPattern(\"d.\u00a0MMMM\u00a0yyyy\",\u00a0new\u00a0Locale(\"fr\")));\r\n\r\n\/\/\u00a0using\u00a0short\u00a0german\u00a0date\/time\u00a0formatting\u00a0(01.04.14\u00a010:45)\r\nDateTimeFormatter\u00a0formatter\u00a0=\u00a0DateTimeFormatter.ofLocalizedDateTime(FormatStyle.SHORT)\r\n\u00a0\u00a0\u00a0\u00a0.withLocale(new\u00a0Locale(\"de\"));\r\nString\u00a0germanDateTime\u00a0=\u00a0dateTime.format(formatter);\r\n\r\n\/\/\u00a0parsing\u00a0date\u00a0strings\r\nLocalDate\u00a0fromIsoDate\u00a0=\u00a0LocalDate.parse(\"2014-01-20\");\r\nLocalDate\u00a0fromIsoWeekDate\u00a0=\u00a0LocalDate.parse(\"2014-W14-2\",\u00a0DateTimeFormatter.ISO_WEEK_DATE);\r\nLocalDate\u00a0fromCustomPattern\u00a0=\u00a0LocalDate.parse(\"20.01.2014\",\u00a0DateTimeFormatter.ofPattern(\"dd.MM.yyyy\"));<\/pre>\n
Conversion<\/h2>\n
Of course we do not always have objects of the type we need. Therefore, we need an option to convert different date\/time related objects between each other. The following examples show some of the possible conversion options:<\/p>\n
\/\/\u00a0LocalDate\/LocalTime\u00a0<->\u00a0LocalDateTime\r\nLocalDate\u00a0date\u00a0=\u00a0LocalDate.now();\r\nLocalTime\u00a0time\u00a0=\u00a0LocalTime.now();\r\nLocalDateTime\u00a0dateTimeFromDateAndTime\u00a0=\u00a0LocalDateTime.of(date,\u00a0time);\r\nLocalDate\u00a0dateFromDateTime\u00a0=\u00a0LocalDateTime.now().toLocalDate();\r\nLocalTime\u00a0timeFromDateTime\u00a0=\u00a0LocalDateTime.now().toLocalTime();\r\n\r\n\/\/\u00a0Instant\u00a0<->\u00a0LocalDateTime\r\nInstant\u00a0instant\u00a0=\u00a0Instant.now();\r\nLocalDateTime\u00a0dateTimeFromInstant\u00a0=\u00a0LocalDateTime.ofInstant(instant,\u00a0ZoneId.of(\"America\/Los_Angeles\"));\r\nInstant\u00a0instantFromDateTime\u00a0=\u00a0LocalDateTime.now().toInstant(ZoneOffset.ofHours(-2));\r\n\r\n\/\/\u00a0convert old\u00a0date\/calendar\/timezone\u00a0classes\r\nInstant\u00a0instantFromDate\u00a0=\u00a0new\u00a0Date().toInstant();\r\nInstant\u00a0instantFromCalendar\u00a0=\u00a0Calendar.getInstance().toInstant();\r\nZoneId\u00a0zoneId\u00a0=\u00a0TimeZone.getDefault().toZoneId();\r\nZonedDateTime\u00a0zonedDateTimeFromGregorianCalendar\u00a0=\u00a0new\u00a0GregorianCalendar().toZonedDateTime();\r\n\r\n\/\/ convert to old classes\r\nDate\u00a0dateFromInstant\u00a0=\u00a0Date.from(Instant.now());\r\nTimeZone\u00a0timeZone\u00a0=\u00a0TimeZone.getTimeZone(ZoneId.of(\"America\/Los_Angeles\"));\r\nGregorianCalendar\u00a0gregorianCalendar\u00a0=\u00a0GregorianCalendar.from(ZonedDateTime.now());<\/pre>\n
Conclusion <\/h2>\n
With Java 8 we get a very rich API for working with date and time located in the java.time package. The API can completely replace old classes like java.util.Date or java.util.Calendar with newer, more flexible classes. Due to mostly immutable classes the new API helps in building thread safe systems.<\/p>\n