Type Members

1.  abstract class Clock extends AnyRef

   A clock providing access to the current instant, date and time using a time-zone.

   A clock providing access to the current instant, date and time using a time-zone.

   Instances of this class are used to find the current instant, which can be interpreted using the stored time-zone to find the current date and time. As such, a clock can be used instead of System#currentTimeMillis() and TimeZone#getDefault().

   Use of a Clock is optional. All key date-time classes also have a now() factory method that uses the system clock in the default time zone. The primary purpose of this abstraction is to allow alternate clocks to be plugged in as and when required. Applications use an object to obtain the current time rather than a static method. This can simplify testing.

   Best practice for applications is to pass a Clock into any method that requires the current instant. A dependency injection framework is one way to achieve this:

    public class
   MyBean { private Clock clock; // dependency inject ... public void process(LocalDate eventDate) {
   if (eventDate.isBefore(LocalDate.now(clock)) { ... } } } 
   

   This approach allows an alternate clock, such as ZoneId) fixed or Duration) offset to be used during testing.

   The system factory methods provide clocks based on the best available system clock This may use System#currentTimeMillis(), or a higher resolution clock if one is available.

   Specification for implementors

   This abstract class must be implemented with care to ensure other operate correctly. All implementations that can be instantiated must be final, immutable and thread-safe.

   The principal methods are defined to allow the throwing of an exception. In normal use, no exceptions will be thrown, however one possible implementation would be to obtain the time from a central time server across the network. Obviously, in this case the lookup could fail, and so the method is permitted to throw an exception.

   The returned instants from Clock work on a time-scale that ignores leap seconds. If the implementation wraps a source that provides leap second information, then a mechanism should be used to "smooth" the leap second, such as UTC-SLS.

   Implementations should implement Serializable wherever possible and must document whether or not they do support serialization.

   if (eventDate.isBefore(LocalDate.now(clock)) { ... } } } clock, such as ZoneId) fixed or Duration) offset to be used during testing.

   The system factory methods provide clocks based on the best available system clock This may use System#currentTimeMillis(), or a higher resolution clock if one is available.

   Specification for implementors

   This abstract class must be implemented with care to ensure other operate correctly. All implementations that can be instantiated must be final, immutable and thread-safe.

   The principal methods are defined to allow the throwing of an exception. In normal use, no exceptions will be thrown, however one possible implementation would be to obtain the time from a central time server across the network. Obviously, in this case the lookup could fail, and so the method is permitted to throw an exception.

   The returned instants from Clock work on a time-scale that ignores leap seconds. If the implementation wraps a source that provides leap second information, then a mechanism should be used to "smooth" the leap second, such as UTC-SLS.

   Implementations should implement Serializable wherever possible and must document whether or not they do support serialization.

2.  class DateTimeException extends RuntimeException

   Exception used to indicate a problem while calculating a date-time.

   Exception used to indicate a problem while calculating a date-time.

   This exception is used to indicate problems with creating, querying and manipulating date-time objects.

   Specification for implementors

   This class is intended for use in a single thread.

   Constructs a new date-time exception with the specified message and cause.

   Annotations

   @SerialVersionUID()

3.  final class DayOfWeek extends Enum[DayOfWeek] with TemporalAccessor with TemporalAdjuster
4.  final class Duration extends TemporalAmount with Ordered[Duration] with Serializable

   A time-based amount of time, such as '34.5 seconds'.

   A time-based amount of time, such as '34.5 seconds'.

   This class models a quantity or amount of time in terms of seconds and nanoseconds. It can be accessed using other duration-based units, such as minutes and hours. In addition, the ChronoUnit#DAYS DAYS unit can be used and is treated as exactly equal to 24 hours, thus ignoring daylight savings effects. See Period for the date-based equivalent to this class.

   A physical duration could be of infinite length. For practicality, the duration is stored with constraints similar to Instant. The duration uses nanosecond resolution with a maximum value of the seconds that can be held in a long. This is greater than the current estimated age of the universe.

   The range of a duration requires the storage of a number larger than a long. To achieve this, the class stores a long representing seconds and an int representing nanosecond-of-second, which will always be between 0 and 999,999,999.

   The duration is measured in "seconds", but these are not necessarily identical to the scientific "SI second" definition based on atomic clocks. This difference only impacts durations measured near a leap-second and should not affect most applications. See Instant for a discussion as to the meaning of the second and time-scales.

   Specification for implementors

   This class is immutable and thread-safe.

   Constructs an instance of Duration using seconds and nanoseconds.

   Annotations

   @SerialVersionUID()

5.  final class Instant extends TemporalAccessor with Temporal with TemporalAdjuster with Ordered[Instant] with Serializable

   An instantaneous point on the time-line.

   An instantaneous point on the time-line.

   This class models a single instantaneous point on the time-line. This might be used to record event time-stamps in the application.

   For practicality, the instant is stored with some constraints. The measurable time-line is restricted to the number of seconds that can be held in a long. This is greater than the current estimated age of the universe. The instant is stored to nanosecond resolution.

   The range of an instant requires the storage of a number larger than a long. To achieve this, the class stores a long representing epoch-seconds and an int representing nanosecond-of-second, which will always be between 0 and 999,999,999. The epoch-seconds are measured from the standard Java epoch of 1970-01-01T00:00:00Z where instants after the epoch have positive values, and earlier instants have negative values. For both the epoch-second and nanosecond parts, a larger value is always later on the time-line than a smaller value.

   Time-scale

   The length of the solar day is the standard way that humans measure time. This has traditionally been subdivided into 24 hours of 60 minutes of 60 seconds, forming a 86400 second day.

   Modern timekeeping is based on atomic clocks which precisely define an SI second relative to the transitions of a Caesium atom. The length of an SI second was defined to be very close to the 86400th fraction of a day.

   Unfortunately, as the Earth rotates the length of the day varies. In addition, over time the average length of the day is getting longer as the Earth slows. As a result, the length of a solar day in 2012 is slightly longer than 86400 SI seconds. The actual length of any given day and the amount by which the Earth is slowing are not predictable and can only be determined by measurement. The UT1 time-scale captures the accurate length of day, but is only available some time after the day has completed.

   The UTC time-scale is a standard approach to bundle up all the additional fractions of a second from UT1 into whole seconds, known as leap-seconds. A leap-second may be added or removed depending on the Earth's rotational changes. As such, UTC permits a day to have 86399 SI seconds or 86401 SI seconds where necessary in order to keep the day aligned with the Sun.

   The modern UTC time-scale was introduced in 1972, introducing the concept of whole leap-seconds. Between 1958 and 1972, the definition of UTC was complex, with minor sub-second leaps and alterations to the length of the notional second. As of 2012, discussions are underway to change the definition of UTC again, with the potential to remove leap seconds or introduce other changes.

   Given the complexity of accurate timekeeping described above, this Java API defines its own time-scale with a simplification. The Java time-scale is defined as follows:

   • midday will always be exactly as defined by the agreed international civil time
   • other times during the day will be broadly in line with the agreed international civil time
   • the day will be divided into exactly 86400 subdivisions, referred to as "seconds"
   • the Java "second" may differ from an SI second

   Agreed international civil time is the base time-scale agreed by international convention, which in 2012 is UTC (with leap-seconds).

   In 2012, the definition of the Java time-scale is the same as UTC for all days except those where a leap-second occurs. On days where a leap-second does occur, the time-scale effectively eliminates the leap-second, maintaining the fiction of 86400 seconds in the day.

   The main benefit of always dividing the day into 86400 subdivisions is that it matches the expectations of most users of the API. The alternative is to force every user to understand what a leap second is and to force them to have special logic to handle them. Most applications do not have access to a clock that is accurate enough to record leap-seconds. Most applications also do not have a problem with a second being a very small amount longer or shorter than a real SI second during a leap-second.

   If an application does have access to an accurate clock that reports leap-seconds, then the recommended technique to implement the Java time-scale is to use the UTC-SLS convention. <a href="http://www.cl.cam.ac.uk/~mgk25/time/utc-sls/">UTC-SLS effectively smoothes the leap-second over the last 1000 seconds of the day, making each of the last 1000 "seconds" 1/1000th longer or shorter than a real SI second.

   One final problem is the definition of the agreed international civil time before the introduction of modern UTC in 1972. This includes the Java epoch of 1970-01-01. It is intended that instants before 1972 be interpreted based on the solar day divided into 86400 subdivisions.

   The Java time-scale is used by all date-time classes. This includes Instant, LocalDate, LocalTime, OffsetDateTime, ZonedDateTime and Duration.

   Specification for implementors

   This class is immutable and thread-safe.

   Constructs an instance of Instant using seconds from the epoch of 1970-01-01T00:00:00Z and nanosecond fraction of second.

   Annotations

   @SerialVersionUID()

6.  final class LocalDate extends ChronoLocalDate with Temporal with TemporalAdjuster with Serializable

   A date without a time-zone in the ISO-8601 calendar system, such as 2007-12-03.

   A date without a time-zone in the ISO-8601 calendar system, such as 2007-12-03.

   LocalDate is an immutable date-time object that represents a date, often viewed as year-month-day. Other date fields, such as day-of-year, day-of-week and week-of-year, can also be accessed. For example, the value "2nd October 2007" can be stored in a LocalDate.

   This class does not store or represent a time or time-zone. Instead, it is a description of the date, as used for birthdays. It cannot represent an instant on the time-line without additional information such as an offset or time-zone.

   The ISO-8601 calendar system is the modern civil calendar system used today in most of the world. It is equivalent to the proleptic Gregorian calendar system, in which today's rules for leap years are applied for all time. For most applications written today, the ISO-8601 rules are entirely suitable. However, any application that makes use of historical dates, and requires them to be accurate will find the ISO-8601 approach unsuitable.

   Specification for implementors

   This class is immutable and thread-safe.

   Annotations

   @SerialVersionUID()

7.  final class LocalDateTime extends ChronoLocalDateTime[LocalDate] with Temporal with TemporalAdjuster with Serializable

   A date-time without a time-zone in the ISO-8601 calendar system, such as 2007-12-03T10:15:30.

   A date-time without a time-zone in the ISO-8601 calendar system, such as 2007-12-03T10:15:30.

   LocalDateTime is an immutable date-time object that represents a date-time, often viewed as year-month-day-hour-minute-second. Other date and time fields, such as day-of-year, day-of-week and week-of-year, can also be accessed. Time is represented to nanosecond precision. For example, the value "2nd October 2007 at 13:45.30.123456789" can be stored in a LocalDateTime.

   This class does not store or represent a time-zone. Instead, it is a description of the date, as used for birthdays, combined with the local time as seen on a wall clock. It cannot represent an instant on the time-line without additional information such as an offset or time-zone.

   The ISO-8601 calendar system is the modern civil calendar system used today in most of the world. It is equivalent to the proleptic Gregorian calendar system, in which today's rules for leap years are applied for all time. For most applications written today, the ISO-8601 rules are entirely suitable. However, any application that makes use of historical dates, and requires them to be accurate will find the ISO-8601 approach unsuitable.

   Specification for implementors

   This class is immutable and thread-safe.

   Annotations

   @SerialVersionUID()

8.  final class LocalTime extends TemporalAccessor with Temporal with TemporalAdjuster with Ordered[LocalTime] with Serializable

   A time without time-zone in the ISO-8601 calendar system, such as 10:15:30.

   A time without time-zone in the ISO-8601 calendar system, such as 10:15:30.

   LocalTime is an immutable date-time object that represents a time, often viewed as hour-minute-second. Time is represented to nanosecond precision. For example, the value "13:45.30.123456789" can be stored in a LocalTime.

   It does not store or represent a date or time-zone. Instead, it is a description of the local time as seen on a wall clock. It cannot represent an instant on the time-line without additional information such as an offset or time-zone.

   The ISO-8601 calendar system is the modern civil calendar system used today in most of the world. This API assumes that all calendar systems use the same representation, this class, for time-of-day.

   Specification for implementors

   This class is immutable and thread-safe.

   Annotations

   @SerialVersionUID()

9.  final class Month extends Enum[Month] with TemporalAccessor with TemporalAdjuster
10.  final class MonthDay extends TemporalAccessor with TemporalAdjuster with Ordered[MonthDay] with Serializable

    A month-day in the ISO-8601 calendar system, such as --12-03.

    A month-day in the ISO-8601 calendar system, such as --12-03.

    MonthDay is an immutable date-time object that represents the combination of a year and month. Any field that can be derived from a month and day, such as quarter-of-year, can be obtained.

    This class does not store or represent a year, time or time-zone. For example, the value "December 3rd" can be stored in a MonthDay.

    Since a MonthDay does not possess a year, the leap day of February 29th is considered valid.

    This class implements TemporalAccessor rather than Temporal. This is because it is not possible to define whether February 29th is valid or not without external information, preventing the implementation of plus/minus. Related to this, MonthDay only provides access to query and set the fields MONTH_OF_YEAR and DAY_OF_MONTH.

    The ISO-8601 calendar system is the modern civil calendar system used today in most of the world. It is equivalent to the proleptic Gregorian calendar system, in which today's rules for leap years are applied for all time. For most applications written today, the ISO-8601 rules are entirely suitable. However, any application that makes use of historical dates, and requires them to be accurate will find the ISO-8601 approach unsuitable.

    Specification for implementors

    This class is immutable and thread-safe.

    Annotations

    @SerialVersionUID()

11.  final class OffsetDateTime extends Temporal with TemporalAdjuster with Ordered[OffsetDateTime] with Serializable

    A date-time with an offset from UTC/Greenwich in the ISO-8601 calendar system, such as 2007-12-03T10:15:30+01:00.

    A date-time with an offset from UTC/Greenwich in the ISO-8601 calendar system, such as 2007-12-03T10:15:30+01:00.

    OffsetDateTime is an immutable representation of a date-time with an offset. This class stores all date and time fields, to a precision of nanoseconds, as well as the offset from UTC/Greenwich. For example, the value "2nd October 2007 at 13:45.30.123456789 +02:00" can be stored in an OffsetDateTime.

    OffsetDateTime, ZonedDateTime and Instant all store an instant on the time-line to nanosecond precision. Instant is the simplest, simply representing the instant. OffsetDateTime adds to the instant the offset from UTC/Greenwich, which allows the local date-time to be obtained. ZonedDateTime adds full time-zone rules.

    It is intended that ZonedDateTime or Instant is used to model data in simpler applications. This class may be used when modeling date-time concepts in more detail, or when communicating to a database or in a network protocol.

    Specification for implementors

    This class is immutable and thread-safe.

12.  final class OffsetTime extends TemporalAccessor with Temporal with TemporalAdjuster with Ordered[OffsetTime] with Serializable

    A time with an offset from UTC/Greenwich in the ISO-8601 calendar system, such as 10:15:30+01:00.

    A time with an offset from UTC/Greenwich in the ISO-8601 calendar system, such as 10:15:30+01:00.

    OffsetTime is an immutable date-time object that represents a time, often viewed as hour-minute-second-offset. This class stores all time fields, to a precision of nanoseconds, as well as a zone offset. For example, the value "13:45.30.123456789+02:00" can be stored in an OffsetTime.

    Specification for implementors

    This class is immutable and thread-safe.

    Annotations

    @SerialVersionUID()

13.  final class Period extends ChronoPeriod with Serializable

    A date-based amount of time, such as '2 years, 3 months and 4 days'.

    A date-based amount of time, such as '2 years, 3 months and 4 days'.

    This class models a quantity or amount of time in terms of years, months and days. See Duration for the time-based equivalent to this class.

    Durations and period differ in their treatment of daylight savings time when added to ZonedDateTime. A Duration will add an exact number of seconds, thus a duration of one day is always exactly 24 hours. By contrast, a Period will add a conceptual day, trying to maintain the local time.

    For example, consider adding a period of one day and a duration of one day to 18:00 on the evening before a daylight savings gap. The Period will add the conceptual day and result in a ZonedDateTime at 18:00 the following day. By contrast, the Duration will add exactly 24 hours, resulting in a ZonedDateTime at 19:00 the following day (assuming a one hour DST gap).

    The supported units of a period are YEARS, MONTHS and DAYS. All three fields are always present, but may be set to zero.

    The period may be used with any calendar system. The meaning of a "year" or "month" is only applied when the object is added to a date.

    The period is modeled as a directed amount of time, meaning that individual parts of the period may be negative.

    The months and years fields may be normalized. The normalization assumes a 12 month year, so is not appropriate for all calendar systems.

    Specification for implementors

    This class is immutable and thread-safe.

    Annotations

    @SerialVersionUID()

14.  final class Year extends TemporalAccessor with Temporal with TemporalAdjuster with Ordered[Year] with Serializable

    A year in the ISO-8601 calendar system, such as 2007.

    A year in the ISO-8601 calendar system, such as 2007.

    Year is an immutable date-time object that represents a year. Any field that can be derived from a year can be obtained.

    Note that years in the ISO chronology only align with years in the Gregorian-Julian system for modern years. Parts of Russia did not switch to the modern Gregorian/ISO rules until 1920. As such, historical years must be treated with caution.

    This class does not store or represent a month, day, time or time-zone. For example, the value "2007" can be stored in a Year.

    Years represented by this class follow the ISO-8601 standard and use the proleptic numbering system. Year 1 is preceded by year 0, then by year -1.

    The ISO-8601 calendar system is the modern civil calendar system used today in most of the world. It is equivalent to the proleptic Gregorian calendar system, in which today's rules for leap years are applied for all time. For most applications written today, the ISO-8601 rules are entirely suitable. However, any application that makes use of historical dates, and requires them to be accurate will find the ISO-8601 approach unsuitable.

    Specification for implementors

    This class is immutable and thread-safe.

    Annotations

    @SerialVersionUID()

15.  final class YearMonth extends TemporalAccessor with Temporal with TemporalAdjuster with Ordered[YearMonth] with Serializable

16.  abstract class ZoneId extends Serializable

    A time-zone ID, such as Europe/Paris.

    A time-zone ID, such as Europe/Paris.

    A ZoneId is used to identify the rules used to convert between an Instant and a LocalDateTime. There are two distinct types of ID:

    • Fixed offsets - a fully resolved offset from UTC/Greenwich, that uses the same offset for all local date-times
    • Geographical regions - an area where a specific set of rules for finding the offset from UTC/Greenwich apply Most fixed offsets are represented by ZoneOffset. Calling #normalized() on any ZoneId will ensure that a fixed offset ID will be represented as a ZoneOffset.

    The actual rules, describing when and how the offset changes, are defined by ZoneRules. This class is simply an ID used to obtain the underlying rules. This approach is taken because rules are defined by governments and change frequently, whereas the ID is stable.

    The distinction has other effects. Serializing the ZoneId will only send the ID, whereas serializing the rules sends the entire data set. Similarly, a comparison of two IDs only examines the ID, whereas a comparison of two rules examines the entire data set.

    Time-zone IDs

    The ID is unique within the system. There are three types of ID.

    The simplest type of ID is that from ZoneOffset. This consists of 'Z' and IDs starting with '+' or '-'.

    The next type of ID are offset-style IDs with some form of prefix, such as 'GMT+2' or 'UTC+01:00'. The recognised prefixes are 'UTC', 'GMT' and 'UT'. The offset is the suffix and will be normalized during creation. These IDs can be normalized to a ZoneOffset using normalized().

    The third type of ID are region-based IDs. A region-based ID must be of two or more characters, and not start with 'UTC', 'GMT', 'UT' '+' or '-'. Region-based IDs are defined by configuration, see ZoneRulesProvider. The configuration focuses on providing the lookup from the ID to the underlying ZoneRules.

    Time-zone rules are defined by governments and change frequently. There are a number of organizations, known here as groups, that monitor time-zone changes and collate them. The default group is the IANA Time Zone Database (TZDB). Other organizations include IATA (the airline industry body) and Microsoft.

    Each group defines its own format for the region ID it provides. The TZDB group defines IDs such as 'Europe/London' or 'America/New_York'. TZDB IDs take precedence over other groups.

    It is strongly recommended that the group name is included in all IDs supplied by groups other than TZDB to avoid conflicts. For example, IATA airline time-zone region IDs are typically the same as the three letter airport code. However, the airport of Utrecht has the code 'UTC', which is obviously a conflict. The recommended format for region IDs from groups other than TZDB is 'group~region'. Thus if IATA data were defined, Utrecht airport would be 'IATA~UTC'.

    Serialization

    This class can be serialized and stores the string zone ID in the external form. The ZoneOffset subclass uses a dedicated format that only stores the offset from UTC/Greenwich.

    A ZoneId can be deserialized in a Java Runtime where the ID is unknown. For example, if a server-side Java Runtime has been updated with a new zone ID, but the client-side Java Runtime has not been updated. In this case, the ZoneId object will exist, and can be queried using getId, equals, hashCode, toString, getDisplayName and normalized. However, any call to getRules will fail with ZoneRulesException. This approach is designed to allow a ZonedDateTime to be loaded and queried, but not modified, on a Java Runtime with incomplete time-zone information.

    Specification for implementors

    This abstract class has two implementations, both of which are immutable and thread-safe. One implementation models region-based IDs, the other is ZoneOffset modelling offset-based IDs. This difference is visible in serialization.

    Annotations

    @SerialVersionUID()

17.  final class ZoneOffset extends ZoneId with TemporalAccessor with TemporalAdjuster with Ordered[ZoneOffset] with Serializable

    A time-zone offset from Greenwich/UTC, such as +02:00.

    A time-zone offset from Greenwich/UTC, such as +02:00.

    A time-zone offset is the period of time that a time-zone differs from Greenwich/UTC. This is usually a fixed number of hours and minutes.

    Different parts of the world have different time-zone offsets. The rules for how offsets vary by place and time of year are captured in the ZoneId class.

    For example, Paris is one hour ahead of Greenwich/UTC in winter and two hours ahead in summer. The ZoneId instance for Paris will reference two ZoneOffset instances - a +01:00 instance for winter, and a +02:00 instance for summer.

    In 2008, time-zone offsets around the world extended from -12:00 to +14:00. To prevent any problems with that range being extended, yet still provide validation, the range of offsets is restricted to -18:00 to 18:00 inclusive.

    This class is designed for use with the ISO calendar system. The fields of hours, minutes and seconds make assumptions that are valid for the standard ISO definitions of those fields. This class may be used with other calendar systems providing the definition of the time fields matches those of the ISO calendar system.

    Instances of ZoneOffset must be compared using #equals. Implementations may choose to cache certain common offsets, however applications must not rely on such caching.

    Specification for implementors

    This class is immutable and thread-safe.

    Annotations

    @SerialVersionUID()

18.  final class ZoneRegion extends ZoneId with Serializable

    A geographical region where the same time-zone rules apply.

    A geographical region where the same time-zone rules apply.

    Time-zone information is categorized as a set of rules defining when and how the offset from UTC/Greenwich changes. These rules are accessed using identifiers based on geographical regions, such as countries or states. The most common region classification is the Time Zone Database (TZDB), which defines regions such as 'Europe/Paris' and 'Asia/Tokyo'.

    The region identifier, modeled by this class, is distinct from the underlying rules, modeled by ZoneRules. The rules are defined by governments and change frequently. By contrast, the region identifier is well-defined and long-lived. This separation also allows rules to be shared between regions if appropriate.

    Specification for implementors

    This class is immutable and thread-safe.

19.  final class ZonedDateTime extends ChronoZonedDateTime[LocalDate] with Temporal with 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.

    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.

    Specification for implementors

    A ZonedDateTime holds state equivalent to three separate objects, a LocalDateTime, a ZoneId and the resolved ZoneOffset. The offset and local date-time are used to define an instant when necessary. The zone ID is used to obtain the rules for how and when the offset changes. The offset cannot be freely set, as the zone controls which offsets are valid.

    This class is immutable and thread-safe.

    Annotations

    @SerialVersionUID()