ZonedDateTime

Stay organized with collections Save and categorize content based on your preferences.
public final class ZonedDateTime extends Object
implements Temporal ChronoZonedDateTime<LocalDate> Serializable

A date-time with a time-zone in the ISO-8601 calendar system, such as 2007-12-03T10:15:30+01:00 Europe/Paris.

ZonedDateTime is an immutable representation of a date-time with a time-zone. This class stores all date and time fields, to a precision of nanoseconds, and a time-zone, with a zone offset used to handle ambiguous local date-times. For example, the value "2nd October 2007 at 13:45.30.123456789 +02:00 in the Europe/Paris time-zone" can be stored in a ZonedDateTime.

This class handles conversion from the local time-line of LocalDateTime to the instant time-line of Instant. The difference between the two time-lines is the offset from UTC/Greenwich, represented by a ZoneOffset.

Converting between the two time-lines involves calculating the offset using the rules accessed from the ZoneId. Obtaining the offset for an instant is simple, as there is exactly one valid offset for each instant. By contrast, obtaining the offset for a local date-time is not straightforward. There are three cases:

  • Normal, with one valid offset. For the vast majority of the year, the normal case applies, where there is a single valid offset for the local date-time.
  • Gap, with zero valid offsets. This is when clocks jump forward typically due to the spring daylight savings change from "winter" to "summer". In a gap there are local date-time values with no valid offset.
  • Overlap, with two valid offsets. This is when clocks are set back typically due to the autumn daylight savings change from "summer" to "winter". In an overlap there are local date-time values with two valid offsets.

Any method that converts directly or implicitly from a local date-time to an instant by obtaining the offset has the potential to be complicated.

For Gaps, the general strategy is that if the local date-time falls in the middle of a Gap, then the resulting zoned date-time will have a local date-time shifted forwards by the length of the Gap, resulting in a date-time in the later offset, typically "summer" time.

For Overlaps, the general strategy is that if the local date-time falls in the middle of an Overlap, then the previous offset will be retained. If there is no previous offset, or the previous offset is invalid, then the earlier offset is used, typically "summer" time.. Two additional methods, withEarlierOffsetAtOverlap() and withLaterOffsetAtOverlap(), help manage the case of an overlap.

In terms of design, this class should be viewed primarily as the combination of a LocalDateTime and a ZoneId. The ZoneOffset is a vital, but secondary, piece of information, used to ensure that the class represents an instant, especially during a daylight savings overlap.

Public Method Summary

boolean
equals(Object obj)
Checks if this date-time is equal to another date-time.
String
format(DateTimeFormatter formatter)
Formats this date-time using the specified formatter.
static ZonedDateTime
from(TemporalAccessor temporal)
Obtains an instance of ZonedDateTime from a temporal object.
int
get(TemporalField field)
Gets the value of the specified field from this date-time as an int.
int
getDayOfMonth()
Gets the day-of-month field.
DayOfWeek
getDayOfWeek()
Gets the day-of-week field, which is an enum DayOfWeek.
int
getDayOfYear()
Gets the day-of-year field.
int
getHour()
Gets the hour-of-day field.
long
getLong(TemporalField field)
Gets the value of the specified field from this date-time as a long.
int
getMinute()
Gets the minute-of-hour field.
Month
getMonth()
Gets the month-of-year field using the Month enum.
int
getMonthValue()
Gets the month-of-year field from 1 to 12.
int
getNano()
Gets the nano-of-second field.
ZoneOffset
getOffset()
Gets the zone offset, such as '+01:00'.
int
getSecond()
Gets the second-of-minute field.
int
getYear()
Gets the year field.
ZoneId
getZone()
Gets the time-zone, such as 'Europe/Paris'.
int
hashCode()
A hash code for this date-time.
boolean
isSupported(TemporalUnit unit)
Checks if the specified unit is supported.
boolean
isSupported(TemporalField field)
Checks if the specified field is supported.
ZonedDateTime
minus(TemporalAmount amountToSubtract)
Returns a copy of this date-time with the specified amount subtracted.
ZonedDateTime
minus(long amountToSubtract, TemporalUnit unit)
Returns a copy of this date-time with the specified amount subtracted.
ZonedDateTime
minusDays(long days)
Returns a copy of this ZonedDateTime with the specified number of days subtracted.
ZonedDateTime
minusHours(long hours)
Returns a copy of this ZonedDateTime with the specified number of hours subtracted.
ZonedDateTime
minusMinutes(long minutes)
Returns a copy of this ZonedDateTime with the specified number of minutes subtracted.
ZonedDateTime
minusMonths(long months)
Returns a copy of this ZonedDateTime with the specified number of months subtracted.
ZonedDateTime
minusNanos(long nanos)
Returns a copy of this ZonedDateTime with the specified number of nanoseconds subtracted.
ZonedDateTime
minusSeconds(long seconds)
Returns a copy of this ZonedDateTime with the specified number of seconds subtracted.
ZonedDateTime
minusWeeks(long weeks)
Returns a copy of this ZonedDateTime with the specified number of weeks subtracted.
ZonedDateTime
minusYears(long years)
Returns a copy of this ZonedDateTime with the specified number of years subtracted.
static ZonedDateTime
now(ZoneId zone)
Obtains the current date-time from the system clock in the specified time-zone.
static ZonedDateTime
now()
Obtains the current date-time from the system clock in the default time-zone.
static ZonedDateTime
now(Clock clock)
Obtains the current date-time from the specified clock.
static ZonedDateTime
of(LocalDateTime localDateTime, ZoneId zone)
Obtains an instance of ZonedDateTime from a local date-time.
static ZonedDateTime
of(int year, int month, int dayOfMonth, int hour, int minute, int second, int nanoOfSecond, ZoneId zone)
Obtains an instance of ZonedDateTime from a year, month, day, hour, minute, second, nanosecond and time-zone.
static ZonedDateTime
of(LocalDate date, LocalTime time, ZoneId zone)
Obtains an instance of ZonedDateTime from a local date and time.
static ZonedDateTime
ofInstant(Instant instant, ZoneId zone)
Obtains an instance of ZonedDateTime from an Instant.
static ZonedDateTime
ofInstant(LocalDateTime localDateTime, ZoneOffset offset, ZoneId zone)
Obtains an instance of ZonedDateTime from the instant formed by combining the local date-time and offset.
static ZonedDateTime
ofLocal(LocalDateTime localDateTime, ZoneId zone, ZoneOffset preferredOffset)
Obtains an instance of ZonedDateTime from a local date-time using the preferred offset if possible.
static ZonedDateTime
ofStrict(LocalDateTime localDateTime, ZoneOffset offset, ZoneId zone)
Obtains an instance of ZonedDateTime strictly validating the combination of local date-time, offset and zone ID.
static ZonedDateTime
parse(CharSequence text, DateTimeFormatter formatter)
Obtains an instance of ZonedDateTime from a text string using a specific formatter.
static ZonedDateTime
parse(CharSequence text)
Obtains an instance of ZonedDateTime from a text string such as 2007-12-03T10:15:30+01:00[Europe/Paris].
ZonedDateTime
plus(TemporalAmount amountToAdd)
Returns a copy of this date-time with the specified amount added.
ZonedDateTime
plus(long amountToAdd, TemporalUnit unit)
Returns a copy of this date-time with the specified amount added.
ZonedDateTime
plusDays(long days)
Returns a copy of this ZonedDateTime with the specified number of days added.
ZonedDateTime
plusHours(long hours)
Returns a copy of this ZonedDateTime with the specified number of hours added.
ZonedDateTime
plusMinutes(long minutes)
Returns a copy of this ZonedDateTime with the specified number of minutes added.
ZonedDateTime
plusMonths(long months)
Returns a copy of this ZonedDateTime with the specified number of months added.
ZonedDateTime
plusNanos(long nanos)
Returns a copy of this ZonedDateTime with the specified number of nanoseconds added.
ZonedDateTime
plusSeconds(long seconds)
Returns a copy of this ZonedDateTime with the specified number of seconds added.
ZonedDateTime
plusWeeks(long weeks)
Returns a copy of this ZonedDateTime with the specified number of weeks added.
ZonedDateTime
plusYears(long years)
Returns a copy of this ZonedDateTime with the specified number of years added.
<R> R
query(TemporalQuery<R> query)
Queries this date-time using the specified query.
ValueRange
range(TemporalField field)
Gets the range of valid values for the specified field.
LocalDate
toLocalDate()
Gets the LocalDate part of this date-time.
LocalDateTime
toLocalDateTime()
Gets the LocalDateTime part of this date-time.
LocalTime
toLocalTime()
Gets the LocalTime part of this date-time.
OffsetDateTime
toOffsetDateTime()
Converts this date-time to an OffsetDateTime.
String
toString()
Outputs this date-time as a String, such as 2007-12-03T10:15:30+01:00[Europe/Paris].
ZonedDateTime
truncatedTo(TemporalUnit unit)
Returns a copy of this ZonedDateTime with the time truncated.
long
until(Temporal endExclusive, TemporalUnit unit)
Calculates the amount of time until another date-time in terms of the specified unit.
ZonedDateTime
with(TemporalField field, long newValue)
Returns a copy of this date-time with the specified field set to a new value.
ZonedDateTime
with(TemporalAdjuster adjuster)
Returns an adjusted copy of this date-time.
ZonedDateTime
withDayOfMonth(int dayOfMonth)
Returns a copy of this ZonedDateTime with the day-of-month altered.
ZonedDateTime
withDayOfYear(int dayOfYear)
Returns a copy of this ZonedDateTime with the day-of-year altered.
ZonedDateTime
withEarlierOffsetAtOverlap()
Returns a copy of this date-time changing the zone offset to the earlier of the two valid offsets at a local time-line overlap.
ZonedDateTime
withFixedOffsetZone()
Returns a copy of this date-time with the zone ID set to the offset.
ZonedDateTime
withHour(int hour)
Returns a copy of this ZonedDateTime with the hour-of-day altered.
ZonedDateTime
withLaterOffsetAtOverlap()
Returns a copy of this date-time changing the zone offset to the later of the two valid offsets at a local time-line overlap.
ZonedDateTime
withMinute(int minute)
Returns a copy of this ZonedDateTime with the minute-of-hour altered.
ZonedDateTime
withMonth(int month)
Returns a copy of this ZonedDateTime with the month-of-year altered.
ZonedDateTime
withNano(int nanoOfSecond)
Returns a copy of this ZonedDateTime with the nano-of-second altered.
ZonedDateTime
withSecond(int second)
Returns a copy of this ZonedDateTime with the second-of-minute altered.
ZonedDateTime
withYear(int year)
Returns a copy of this ZonedDateTime with the year altered.
ZonedDateTime
withZoneSameInstant(ZoneId zone)
Returns a copy of this date-time with a different time-zone, retaining the instant.
ZonedDateTime
withZoneSameLocal(ZoneId zone)
Returns a copy of this date-time with a different time-zone, retaining the local date-time if possible.

Inherited Method Summary

Public Methods

public boolean equals (Object obj)

Checks if this date-time is equal to another date-time.

The comparison is based on the offset date-time and the zone. Only objects of type ZonedDateTime are compared, other types return false.

Parameters
obj the object to check, null returns false
Returns
  • true if this is equal to the other date-time

public String format (DateTimeFormatter formatter)

Formats this date-time using the specified formatter.

This date-time will be passed to the formatter to produce a string.

Parameters
formatter the formatter to use, not null
Returns
  • the formatted date-time string, not null
Throws
DateTimeException if an error occurs during printing

public static ZonedDateTime from (TemporalAccessor temporal)

Obtains an instance of ZonedDateTime from a temporal object.

This obtains a zoned date-time based on the specified temporal. A TemporalAccessor represents an arbitrary set of date and time information, which this factory converts to an instance of ZonedDateTime.

The conversion will first obtain a ZoneId from the temporal object, falling back to a ZoneOffset if necessary. It will then try to obtain an Instant, falling back to a LocalDateTime if necessary. The result will be either the combination of ZoneId or ZoneOffset with Instant or LocalDateTime. Implementations are permitted to perform optimizations such as accessing those fields that are equivalent to the relevant objects.

This method matches the signature of the functional interface TemporalQuery allowing it to be used as a query via method reference, ZonedDateTime::from.

Parameters
temporal the temporal object to convert, not null
Returns
  • the zoned date-time, not null
Throws
DateTimeException if unable to convert to an ZonedDateTime

public int get (TemporalField field)

Gets the value of the specified field from this date-time as an int.

This queries this date-time for the value of the specified field. The returned value will always be within the valid range of values for the field. If it is not possible to return the value, because the field is not supported or for some other reason, an exception is thrown.

If the field is a ChronoField then the query is implemented here. The supported fields will return valid values based on this date-time, except NANO_OF_DAY, MICRO_OF_DAY, EPOCH_DAY, PROLEPTIC_MONTH and INSTANT_SECONDS which are too large to fit in an int and throw a DateTimeException. All other ChronoField instances will throw an UnsupportedTemporalTypeException.

If the field is not a ChronoField, then the result of this method is obtained by invoking TemporalField.getFrom(TemporalAccessor) passing this as the argument. Whether the value can be obtained, and what the value represents, is determined by the field.

Parameters
field the field to get, not null
Returns
  • the value for the field
Throws
DateTimeException if a value for the field cannot be obtained or the value is outside the range of valid values for the field
UnsupportedTemporalTypeException if the field is not supported or the range of values exceeds an int
ArithmeticException if numeric overflow occurs

public int getDayOfMonth ()

Gets the day-of-month field.

This method returns the primitive int value for the day-of-month.

Returns
  • the day-of-month, from 1 to 31

public DayOfWeek getDayOfWeek ()

Gets the day-of-week field, which is an enum DayOfWeek.

This method returns the enum DayOfWeek for the day-of-week. This avoids confusion as to what int values mean. If you need access to the primitive int value then the enum provides the int value.

Additional information can be obtained from the DayOfWeek. This includes textual names of the values.

Returns
  • the day-of-week, not null

public int getDayOfYear ()

Gets the day-of-year field.

This method returns the primitive int value for the day-of-year.

Returns
  • the day-of-year, from 1 to 365, or 366 in a leap year

public int getHour ()

Gets the hour-of-day field.

Returns
  • the hour-of-day, from 0 to 23

public long getLong (TemporalField field)

Gets the value of the specified field from this date-time as a long.

This queries this date-time for the value of the specified field. If it is not possible to return the value, because the field is not supported or for some other reason, an exception is thrown.

If the field is a ChronoField then the query is implemented here. The supported fields will return valid values based on this date-time. All other ChronoField instances will throw an UnsupportedTemporalTypeException.

If the field is not a ChronoField, then the result of this method is obtained by invoking TemporalField.getFrom(TemporalAccessor) passing this as the argument. Whether the value can be obtained, and what the value represents, is determined by the field.

Parameters
field the field to get, not null
Returns
  • the value for the field
Throws
DateTimeException if a value for the field cannot be obtained
UnsupportedTemporalTypeException if the field is not supported
ArithmeticException if numeric overflow occurs

public int getMinute ()

Gets the minute-of-hour field.

Returns
  • the minute-of-hour, from 0 to 59

public Month getMonth ()

Gets the month-of-year field using the Month enum.

This method returns the enum Month for the month. This avoids confusion as to what int values mean. If you need access to the primitive int value then the enum provides the int value.

Returns
  • the month-of-year, not null
See Also

public int getMonthValue ()

Gets the month-of-year field from 1 to 12.

This method returns the month as an int from 1 to 12. Application code is frequently clearer if the enum Month is used by calling getMonth().

Returns
  • the month-of-year, from 1 to 12
See Also

public int getNano ()

Gets the nano-of-second field.

Returns
  • the nano-of-second, from 0 to 999,999,999

public ZoneOffset getOffset ()

Gets the zone offset, such as '+01:00'.

This is the offset of the local date-time from UTC/Greenwich.

Returns
  • the zone offset, not null

public int getSecond ()

Gets the second-of-minute field.

Returns
  • the second-of-minute, from 0 to 59

public int getYear ()

Gets the year field.

This method returns the primitive int value for the year.

The year returned by this method is proleptic as per get(YEAR). To obtain the year-of-era, use get(YEAR_OF_ERA).

Returns
  • the year, from MIN_YEAR to MAX_YEAR

public ZoneId getZone ()

Gets the time-zone, such as 'Europe/Paris'.

This returns the zone ID. This identifies the time-zone rules that determine when and how the offset from UTC/Greenwich changes.

The zone ID may be same as the {@linkplain #getOffset() offset}. If this is true, then any future calculations, such as addition or subtraction, have no complex edge cases due to time-zone rules. See also withFixedOffsetZone().

Returns
  • the time-zone, not null

public int hashCode ()

A hash code for this date-time.

Returns
  • a suitable hash code

public boolean isSupported (TemporalUnit unit)

Checks if the specified unit is supported.

This checks if the specified unit can be added to, or subtracted from, this date-time. If false, then calling the plus(long, TemporalUnit) and minus methods will throw an exception.

If the unit is a ChronoUnit then the query is implemented here. The supported units are:

  • NANOS
  • MICROS
  • MILLIS
  • SECONDS
  • MINUTES
  • HOURS
  • HALF_DAYS
  • DAYS
  • WEEKS
  • MONTHS
  • YEARS
  • DECADES
  • CENTURIES
  • MILLENNIA
  • ERAS
All other ChronoUnit instances will return false.

If the unit is not a ChronoUnit, then the result of this method is obtained by invoking TemporalUnit.isSupportedBy(Temporal) passing this as the argument. Whether the unit is supported is determined by the unit.

Parameters
unit the unit to check, null returns false
Returns
  • true if the unit can be added/subtracted, false if not

public boolean isSupported (TemporalField field)

Checks if the specified field is supported.

This checks if this date-time can be queried for the specified field. If false, then calling the range, get and with(TemporalField, long) methods will throw an exception.

If the field is a ChronoField then the query is implemented here. The supported fields are:

  • NANO_OF_SECOND
  • NANO_OF_DAY
  • MICRO_OF_SECOND
  • MICRO_OF_DAY
  • MILLI_OF_SECOND
  • MILLI_OF_DAY
  • SECOND_OF_MINUTE
  • SECOND_OF_DAY
  • MINUTE_OF_HOUR
  • MINUTE_OF_DAY
  • HOUR_OF_AMPM
  • CLOCK_HOUR_OF_AMPM
  • HOUR_OF_DAY
  • CLOCK_HOUR_OF_DAY
  • AMPM_OF_DAY
  • DAY_OF_WEEK
  • ALIGNED_DAY_OF_WEEK_IN_MONTH
  • ALIGNED_DAY_OF_WEEK_IN_YEAR
  • DAY_OF_MONTH
  • DAY_OF_YEAR
  • EPOCH_DAY
  • ALIGNED_WEEK_OF_MONTH
  • ALIGNED_WEEK_OF_YEAR
  • MONTH_OF_YEAR
  • PROLEPTIC_MONTH
  • YEAR_OF_ERA
  • YEAR
  • ERA
  • INSTANT_SECONDS
  • OFFSET_SECONDS
All other ChronoField instances will return false.

If the field is not a ChronoField, then the result of this method is obtained by invoking TemporalField.isSupportedBy(TemporalAccessor) passing this as the argument. Whether the field is supported is determined by the field.

Parameters
field the field to check, null returns false
Returns
  • true if the field is supported on this date-time, false if not

public ZonedDateTime minus (TemporalAmount amountToSubtract)

Returns a copy of this date-time with the specified amount subtracted.

This returns a ZonedDateTime, based on this one, with the specified amount subtracted. The amount is typically Period or Duration but may be any other type implementing the TemporalAmount interface.

The calculation is delegated to the amount object by calling TemporalAmount.subtractFrom(Temporal). The amount implementation is free to implement the subtraction in any way it wishes, however it typically calls back to minus(long, TemporalUnit). Consult the documentation of the amount implementation to determine if it can be successfully subtracted.

This instance is immutable and unaffected by this method call.

Parameters
amountToSubtract the amount to subtract, not null
Returns
  • a ZonedDateTime based on this date-time with the subtraction made, not null
Throws
DateTimeException if the subtraction cannot be made
ArithmeticException if numeric overflow occurs

public ZonedDateTime minus (long amountToSubtract, TemporalUnit unit)

Returns a copy of this date-time with the specified amount subtracted.

This returns a ZonedDateTime, based on this one, with the amount in terms of the unit subtracted. If it is not possible to subtract the amount, because the unit is not supported or for some other reason, an exception is thrown.

The calculation for date and time units differ.

Date units operate on the local time-line. The period is first subtracted from the local date-time, then converted back to a zoned date-time using the zone ID. The conversion uses ofLocal(LocalDateTime, ZoneId, ZoneOffset) with the offset before the subtraction.

Time units operate on the instant time-line. The period is first subtracted from the local date-time, then converted back to a zoned date-time using the zone ID. The conversion uses ofInstant(LocalDateTime, ZoneOffset, ZoneId) with the offset before the subtraction.

This method is equivalent to plus(long, TemporalUnit) with the amount negated. See that method for a full description of how addition, and thus subtraction, works.

This instance is immutable and unaffected by this method call.

Parameters
amountToSubtract the amount of the unit to subtract from the result, may be negative
unit the unit of the amount to subtract, not null
Returns
  • a ZonedDateTime based on this date-time with the specified amount subtracted, not null
Throws
DateTimeException if the subtraction cannot be made
UnsupportedTemporalTypeException if the unit is not supported
ArithmeticException if numeric overflow occurs

public ZonedDateTime minusDays (long days)

Returns a copy of this ZonedDateTime with the specified number of days subtracted.

This operates on the local time-line, subtracting days to the local date-time. This is then converted back to a ZonedDateTime, using the zone ID to obtain the offset.

When converting back to ZonedDateTime, if the local date-time is in an overlap, then the offset will be retained if possible, otherwise the earlier offset will be used. If in a gap, the local date-time will be adjusted forward by the length of the gap.

This instance is immutable and unaffected by this method call.

Parameters
days the days to subtract, may be negative
Returns
  • a ZonedDateTime based on this date-time with the days subtracted, not null
Throws
DateTimeException if the result exceeds the supported date range

public ZonedDateTime minusHours (long hours)

Returns a copy of this ZonedDateTime with the specified number of hours subtracted.

This operates on the instant time-line, such that subtracting one hour will always be a duration of one hour earlier. This may cause the local date-time to change by an amount other than one hour. Note that this is a different approach to that used by days, months and years, thus subtracting one day is not the same as adding 24 hours.

For example, consider a time-zone where the spring DST cutover means that the local times 01:00 to 01:59 occur twice changing from offset +02:00 to +01:00.

  • Subtracting one hour from 02:30+01:00 will result in 01:30+02:00
  • Subtracting one hour from 01:30+01:00 will result in 01:30+02:00
  • Subtracting one hour from 01:30+02:00 will result in 00:30+01:00
  • Subtracting three hours from 02:30+01:00 will result in 00:30+02:00

This instance is immutable and unaffected by this method call.

Parameters
hours the hours to subtract, may be negative
Returns
  • a ZonedDateTime based on this date-time with the hours subtracted, not null
Throws
DateTimeException if the result exceeds