Guide to Java ZonedDateTime

Learn about the ZonedDateTime class in Java, how to create its instances and other use cases such as parsing, formatting and adding duration and periods.

1. Overview

The java.time.ZonedDateTime class, introduced in Java 8 Date Time APIs, represents a date and time with zone id and zone offset information in the ISO-8601 calendar system. This class stores all date and time fields to a precision of nanoseconds.

A ZonedDateTime instance can be used to convert an instance in the universal timeline to LocalDateTime where the difference is the zone offset, and offset is calculated based on the timezone rules. Note that a timezone id can have different offsets during the year when the daylight saving time (DST) switches. In such cases, ZonedDateTime always has the current offset for that zone

We can use the ZonedDateTime instances where we need to represent the time to globally distributed users. For example, we can use it to communicate a conference date where joiners will connect online based on their local date and time.

A ZonedDateTime holds state equivalent to three separate objects, a LocalDateTime, a ZoneId and the resolved ZoneOffset.

ZonedDateTime instances are immutable and thread-safe. The class has been defined as below:

public final class ZonedDateTime
	extends Object
	implements Temporal, ChronoZonedDateTime<LocalDate>, Serializable
{
	//class body
}

2. Creating ZonedDateTime

Generally, we will be creating ZonedDateTime instances in two conditions i.e. get current timestamp or create a timestamp in a specific timezone id and offset.

2.1. Get Current Timestamp

Use the now() method to get the current timestamp with the current zone id and offset. To get the same instance in another timezone, pass the zone id to the now() method.

ZonedDateTime now = ZonedDateTime.now();

ZonedDateTime now = ZonedDateTime.now( ZoneId.of("GMT+05:30") ); 

2.2. Create ZonedDateTime with Values

To create a timestamp with given date, time and zone information – use the of() method which takes a variety of arguments to form an instance.

ZoneId zoneId = ZoneId.of("UTC+1");

ZonedDateTime zdt = ZonedDateTime.of(2015, 11, 30, 23, 45, 59, 1234, zoneId);

//Create from other local instances

LocalDate localDate = LocalDate.of(2019, 03, 12);
LocalTime localTime = LocalTime.of(12,  44);
ZoneId zoneId = ZoneId.of("GMT+05:30");

ZonedDateTime timeStamp = ZonedDateTime.of( localDate, localTime, zoneId );

3. Parse String to ZonedDateTime

The ZonedDateTime class has two overloaded parse() methods to convert the string to ZonedDateTime instance.

parse(CharSequence text)	//1

parse(CharSequence text, DateTimeFormatter formatter)	//2

• Use first method if the string contains time in ISO_ZONED_DATE_TIME pattern i.e. 2019-03-28T10:15:30+01:00[Europe/Paris]. This is default pattern.
• For any other date-time pattern, we need to use second method where we pass the date-time as string as well as a DateTimeFormatter which represents the pattern of that date-time string.

//1 - default pattern
String timeStamp = "2019-03-27T10:15:30";
ZonedDateTime localTimeObj = ZonedDateTime.parse(time);

//2 - specified pattern
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss a");
String timeStamp1 = "2019-03-27 10:15:30 AM";
ZonedDateTime localTimeObj1 = ZonedDateTime.parse(timeStamp1, formatter);

4. Format ZonedDateTime

Use ZonedDateTime.format(formatter) method to format an instance to the desired string pattern.

DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss a");

ZonedDateTime now = ZonedDateTime.now();

String dateTimeString = now.format(formatter);	//2019-03-28 14:47:33 PM

5. Add or Subtract Time from ZonedDateTime

ZonedDateTime provides below methods for modifications. All methods return a new instance of ZonedDateTime because the existing instance is always immutable.

• plusYears()
• plusMonths()
• plusDays()
• plusHours()
• plusMinutes()
• plusSeconds()
• plusNanos()
• minusYears()
• minusMonths()
• minusDays()
• minusHours()
• minusMinutes()
• minusSeconds()
• minusNanos()

ZonedDateTime now = ZonedDateTime.now();

//3 hours later
ZonedDateTime zonedDateTime1 = now.plusHours(3);	

//3 minutes earliar
ZonedDateTime zonedDateTime2 = now.minusMinutes(3);

//Next year same time
ZonedDateTime zonedDateTime2 = now.plusYears(1);

//Last year same time
ZonedDateTime zonedDateTime2 = now.minusYears(1);

6. More Examples

Format ZonedDateTime to String
Parse String to ZonedDateTime
Convert LocalDate to ZonedDateTime in Java
ZonedDateTime timezone conversion example
Compare ZonedDateTime instances
Java 8 – Parse String to date-time in UTC

Happy Learning !!

Sourcecode Download