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 !!