Java 8 Date-Time API – Better logical way to represent date, time & zone (java.time package)

New package java.time that was introduced in Java 8 has surely made representation of date & time more closer to real world. Also the representation is more exact & without unwanted information. Lets explore in depth.

How do we really refer date, time & timezone in real world?

Lets take few examples to understand what do we mean when we talk about different dates, times & timezones.

• Birthday
  • Generally when we tell someone our birth date, we tell them – day, month & year. We generally never mention time or timezone etc.
  • So logically the object representation for birthday should ideally only have day, month & year.
• Store opening & closing times
  • Generally when we talk about store opening & closing hours, we only refer to hour, minutes (may be seconds!). We do not mention date, month, year here as it doesn’t make sense here. Its a particular time on all working days.
  • So logically the object representation should only have hour, minutes (optionally seconds)
• Question – Which is the next leap year?
  • Answer to this question only requires year & nothing else.
  • So logical representation of this answer must only have year & nothing else.
• Happy New Year Fireworks
  • Happy new year mid night moment (or fireworks start time) happens at different moments around the world.
  • Some countries have it early like Australia & other countries have it little later like USA. But everyone have new year event at 1st January 2019, 00:00:00 in their local date & time.
  • So logically here we can either just mention new year as 1st January 2019 00 hours, 00 minutes 00 seconds. Or some might prefer to add timezone to be more accurate. So representation have day, month, year, hour, minute, seconds (and timezone if need to be specific).
• ECG/EKG graph of heart
  • If we are creating software to record ECG/EKG of heart against “time“, then none of the human understandable information like date or time or timezone makes sense.
  • Even though we are going to record heart activity against time, it won’t make sense to record it like 3mV at 28 December 2018 09:00:00 PM. Here time is more graphical than human readable date/time.
  • So for such cases we need something completely different than human readable time like machine time etc.

Looking at above several examples, its pretty clear that representation of all such info with single class that holds all information i.e. year, month, day, hour, minute, and second might not be logically justifying.

How Java 8 helps represent date/time like real world?

Below table gives details of how Java 8 classes from java.time package helps represent real world data. In each example you can see that the classes used only represent expected information & no unwanted information.

What to represent?	Example	Class to represent
Only Year	Next leap year	java.time.Year Year nextLeapYear = Year.of(2020); System.out.println(nextLeapYear + " is leap year? " + nextLeapYear.isLeap()); 1 2 3 Year nextLeapYear = Year.of(2020); System.out.println(nextLeapYear + " is leap year? " + nextLeapYear.isLeap()); 2020 is leap year? true
Only Month	Start of fall season i.e. September	java.time.Month (Enum) Month startOfFall = Month.SEPTEMBER; System.out.println("Start of fall is " + startOfFall); 1 2 3 Month startOfFall = Month.SEPTEMBER; System.out.println("Start of fall is " + startOfFall); Start of fall is SEPTEMBER
Only Day of month	Valentine’s Day i.e 14’th Feb	java.time.MonthDay MonthDay valentinesDay = MonthDay.of(Month.FEBRUARY, 14); System.out.println("Valentine's Day is on " + valentinesDay); 1 2 3 4 MonthDay valentinesDay = MonthDay.of(Month.FEBRUARY, 14); System.out.println("Valentine's Day is on " + valentinesDay); Valentine's Day is on --02-14
Only Day of week	Non working day i.e. Sunday	java.time.DayOfWeek (Enum) DayOfWeek nonWorkingDay = DayOfWeek.SUNDAY; System.out.println(nonWorkingDay + " is non working day"); 1 2 3 DayOfWeek nonWorkingDay = DayOfWeek.SUNDAY; System.out.println(nonWorkingDay + " is non working day"); SUNDAY is non working day
Only Year, Month & Day	Birthday ex: 10 January 1981	java.time.LocalDate LocalDate birthDay = LocalDate.of(1981, Month.JANUARY, 10); System.out.println("Tom's birthday is on " + birthDay); 1 2 3 LocalDate birthDay      = LocalDate.of(1981, Month.JANUARY, 10); System.out.println("Tom's birthday is on " + birthDay); Tom's birthday is on 1981-01-10
Only Hour, Minute & Seconds	Store opening time like 09:00:00 AM	java.time.LocalTime LocalTime storeOpeningTime = LocalTime.of(9, 0, 0); System.out.println("Store opening time is " + storeOpeningTime); 1 2 3 4 LocalTime storeOpeningTime = LocalTime.of(9, 0, 0); System.out.println("Store opening time is " + storeOpeningTime); Store opening time is 09:00
Only Year, Month, Day, Hour, Minute & Seconds	Happy New Year ex: 1 January 2019, 00:00:00 AM	java.time.LocalDateTime LocalDateTime happyNewYear = LocalDateTime.of(2019, Month.JANUARY, 1, 0, 0, 0); System.out.println("Fireworks start at " + happyNewYear); 1 2 3 LocalDateTime happyNewYear = LocalDateTime.of(2019, Month.JANUARY, 1, 0, 0, 0); System.out.println("Fireworks start at " + happyNewYear); Fireworks start at 2019-01-01T00:00
Machine time or particular instance in time	ECG/EKG graph of heart	java.time.Instant Java Map<Instant, Integer> ecgOfHeart = new HashMap<>(); while (!stopECG()) { ecgOfHeart.put(Instant.now(), getHeartActivity()); } 1 2 3 4 Map<Instant, Integer> ecgOfHeart = new HashMap<>(); while (!stopECG()) { ecgOfHeart.put(Instant.now(), getHeartActivity()); }

But wait, where’s time zone?

In general, we represent timezone in two ways

1. By the name of time zone like “America/Los_Angeles”, “Asia/Kolkata” etc.
2. By the offset from UTC/Greenwich like “GMT-8”, “UTC+05:30” etc.

Java now provides same analogy using classes

1. By the name – java.time.ZonedDateTime & java.time.ZoneId
2. By the offset from UTC – java.time.OffsetDateTime & java.time.ZoneOffset

Here are examples for the same.

Output:

Why is this better than pre Java 8 classes from java.util?

Till Java 8, to represent date, time & timezone  java.util.Date, java.util.Calendar, and java.util.TimeZone classes were used.

• java.util.Date
  • Date is a representation of instant in time in milliseconds.
  • It also allows interpretation in terms of year, month, day, hour, minute, and second values.
• java.util.Calendar,
  • Calendar provides a way to manipulate date & time in human readable notation.
  • GregorianCalendar is a concrete implementation of Calendar providing standard calendar implementation.
• java.util.TimeZone
  • As name suggests, this represents time zone.

Now lets try to represent few from above example using these pre Java 8 classes.

What to represent?	Example	Pre Java 8 Representation.
Only Year	Next leap year	/* * Represent a leap year */ Calendar calendar = Calendar.getInstance(); calendar.set(Calendar.YEAR, 2020); /* * I can still convert it to Date object in milliseconds. * But we only expected year & not a precise instant. * So not an accurate representation of year. */ System.out.println(calendar.getTime()); 1 2 3 4 5 6 7 8 9 10 11 /* * Represent a leap year */ Calendar calendar = Calendar.getInstance(); calendar.set(Calendar.YEAR, 2020); /* * I can still convert it to Date object in milliseconds. * But we only expected year & not a precise instant. * So not an accurate representation of year. */ System.out.println(calendar.getTime()); Thu Dec 31 15:12:37 PST 2020 1 Thu Dec 31 15:12:37 PST 2020
Only Year, Month & Day	Birthday ex: 10 January 1981	/* * Represent birthday using GregorianCalendar */ GregorianCalendar tomBirthDay = new GregorianCalendar(1981, GregorianCalendar.JANUARY, 10); /* * We didn't mean to have birthday as just one moment * on that day, but as per output, tomBirthDay object * represents one moment on that day not that entire * day. */ System.out.println("Tom's birthday is on " + tomBirthDay.getTime()); 1 2 3 4 5 6 7 8 9 10 11 12 13 /* * Represent birthday using GregorianCalendar */ GregorianCalendar tomBirthDay = new GregorianCalendar(1981, GregorianCalendar.JANUARY, 10); /* * We didn't mean to have birthday as just one moment * on that day, but as per output, tomBirthDay object * represents one moment on that day not that entire * day. */ System.out.println("Tom's birthday is on " + tomBirthDay.getTime()); Tom's birthday is on Sat Jan 10 00:00:00 PST 1981
Only Hour, Minute & Seconds	Store opening time like 09:00:00 AM	Didn’t have anything to specifically represent only time.
Machine time or particular instance in time	ECG/EKG graph of heart	We can use “new Date()” which stores milliseconds. But still date is a representation of Human time. But closer to what we want here. Java Map<Date, Integer> ecgOfHeart = new HashMap<>(); while (!stopECG()) { ecgOfHeart.put(new Date(), getHeartActivity()); } 1 2 3 4 Map<Date, Integer> ecgOfHeart = new HashMap<>(); while (!stopECG()) { ecgOfHeart.put(new Date(), getHeartActivity()); }

As you can see, with pre Java 8 classes, we could represent our examples but not as logical & appropriate as java 8 date-time classes. All of these still had unwanted information which was not necessary in the context of examples.

So legacy date-time API classes did the job but not as well as new java.time package API

Migrating to Java 8 date-time API (java.time package)

Even though Date, Calendar & GregorianCalendar classes are not deprecated, they are officially called legacy by Oracle documentation. Also the new date-time API is better representation as explained above, so you might consider migrating to new Java 8 date-time API.

Migrating to java.time from java.util is not going to be one-to-one. We can’t just replace java.util.Date with java.time.LocalDate or java.time.LocalDateTime as it might not be logically accurate.

First step while migrating to new java.time will be to identify what your Date, Calendar or GregorianCalendar represent functionally? It might represent just “day, month, year” or it might represent “day, month, year with time” or “day, month, year with time & timezone” etc. Once you figure out what exactly you want to represent, then refer to table in earlier section of representation like real-world examples & timezone examples. Choose appropriate classes to represent & use it.

More Examples

Refer Lots of Examples with javadoc here.

To get further more details refer below articles

Java 8 Date-Time API – Period & Duration