bp
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.
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.
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.
This class is intended for use in a single thread.
Constructs a new date-time exception with the specified message and cause.
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 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.
This class is immutable and thread-safe.
Constructs an instance of Duration using seconds and nanoseconds.
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.
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:
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. 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.
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.
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.
This class is immutable and thread-safe.
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.
This class is immutable and thread-safe.
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.
This class is immutable and thread-safe.
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.
This class is immutable and thread-safe.
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.
This class is immutable and thread-safe.
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.
This class is immutable and thread-safe.
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.
This class is immutable and thread-safe.
The shared serialization delegate for this package.
The shared serialization delegate for this package.
This class wraps the object being serialized, and takes a byte representing the type of the class to
be serialized. This byte can also be used for versioning the serialization format. In this case another
byte flag would be used in order to specify an alternative version of the type format.
For example LOCAL_DATE_TYPE_VERSION_2 = 21.
In order to serialise the object it writes its byte and then calls back to the appropriate class where the serialisation is performed. In order to deserialise the object it read in the type byte, switching in order to select which class to call back into.
The serialisation format is determined on a per class basis. In the case of field based classes each
of the fields is written out with an appropriate size format in descending order of the field's size. For
example in the case of LocalDate year is written before month. Composite classes, such as
LocalDateTime are serialised as one object.
This class is mutable and should be created once per serialization.
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.
This class is immutable and thread-safe.
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:
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.
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'.
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.
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.
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.
This class is immutable and thread-safe.
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.
This class is immutable and thread-safe.
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:
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.
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.
A set of utilities to assist in bridging the gap to Java 8.
A set of utilities to assist in bridging the gap to Java 8.
This class is not found in Java SE 8 but provides methods that are.
A day-of-week, such as 'Tuesday'.
A day-of-week, such as 'Tuesday'.
DayOfWeek is an enum representing the 7 days of the week -
Monday, Tuesday, Wednesday, Thursday, Friday, Saturday and Sunday.
In addition to the textual enum name, each day-of-week has an int value.
The int value follows the ISO-8601 standard, from 1 (Monday) to 7 (Sunday).
It is recommended that applications use the enum rather than the int value
to ensure code clarity.
This enum provides access to the localized textual form of the day-of-week.
Some locales also assign different numeric values to the days, declaring
Sunday to have the value 1, however this class provides no support for this.
See WeekFields for localized week-numbering.
Do not use ordinal() to obtain the numeric representation of DayOfWeek.
Use getValue() instead.
This enum represents a common concept that is found in many calendar systems. As such, this enum may be used by any calendar system that has the day-of-week concept defined exactly equivalent to the ISO calendar system.
This is an immutable and thread-safe enum.
A month-of-year, such as 'July'.
A month-of-year, such as 'July'.
Month is an enum representing the 12 months of the year -
January, February, March, April, May, June, July, August, September, October,
November and December.
In addition to the textual enum name, each month-of-year has an int value.
The int value follows normal usage and the ISO-8601 standard,
from 1 (January) to 12 (December). It is recommended that applications use the enum
rather than the int value to ensure code clarity.
Do not use ordinal() to obtain the numeric representation of Month.
Use getValue() instead.
This enum represents a common concept that is found in many calendar systems. As such, this enum may be used by any calendar system that has the month-of-year concept defined exactly equivalent to the ISO-8601 calendar system.
This is an immutable and thread-safe enum.
A year-month in the ISO-8601 calendar system, such as 2007-12.
A year-month in the ISO-8601 calendar system, such as 2007-12.
YearMonth is an immutable date-time object that represents the combination
of a year and month. Any field that can be derived from a year and month, such as
quarter-of-year, can be obtained.
This class does not store or represent a day, time or time-zone.
For example, the value "October 2007" can be stored in a YearMonth.
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.
This class is immutable and thread-safe.
Support for calendar systems other than the default ISO.
Support for calendar systems other than the default ISO.
The main API is based around the calendar system defined in ISO-8601. This package provides support for alternate systems.
The supported calendar systems includes:
-Hijrah calendar -Japanese calendar -Minguo calendar -Thai Buddhist calendar
It is intended that applications use the main API whenever possible, including code to read and write
from a persistent data store, such as a database, and to send dates and times across a network.
This package is then used at the user interface level to deal with localized input/output.
See ChronoLocalDate for a full discussion of the issues.
This example creates and uses a date in a non-ISO calendar system.
// Print the Thai Buddhist date
ChronoLocalDate now1 = ThaiBuddhistChronology.INSTANCE.now();
int day = now1.get(ChronoField.DAY_OF_MONTH);
int dow = now1.get(ChronoField.DAY_OF_WEEK);
int month = now1.get(ChronoField.MONTH_OF_YEAR);
int year = now1.get(ChronoField.YEAR);
System.out.printf(" Today is %s %s %d-%s-%d%n", now1.getChronology().getId(),
dow, day, month, year);
// Enumerate the list of available calendars and print today for each
Set<String> names = Chronology.getAvailableIds();
for (String name : names) {
Chronology<?> chrono = Chronology.of(name);
ChronoLocalDate<?> date = chrono.now();
System.out.printf(" %20s: %s%n", chrono.getId(), date.toString());
}
// Print today's date and the last day of the year for the Thai Buddhist Calendar.
ChronoLocalDate first = now1
.with(ChronoField.DAY_OF_MONTH, 1)
.with(ChronoField.MONTH_OF_YEAR, 1);
ChronoLocalDate last = first
.plus(1, ChronoUnit.YEARS)
.minus(1, ChronoUnit.DAYS);
System.out.printf(" %s: 1st of year: %s; end of year: %s%n", last.getChronology().getId(),
first, last);
Provides classes to print and parse dates and times.
Provides classes to print and parse dates and times.
Printing and parsing is based around the DateTimeFormatter class.
That class contains common formatters and factory methods.
The DateTimeFormatterBuilder class is available
for advanced and complex use cases.
Localization occurs by calling withLocale(Locale)
on the formatter. Further customization is possible using
DecimalStyle.
Access to date and time using fields and units.
Access to date and time using fields and units.
This package expands on the base package to provide additional functionality for more powerful use cases. Support is included for:
Dates and times are expressed in terms of fields and units.
A unit is used to measure an amount of time, such as years, days or minutes.
All units implement org.threeten.bp.temporal.TemporalUnit.
The set of well known units is defined in org.threeten.bp.temporal.ChronoUnit,
for example, org.threeten.bp.temporal.ChronoUnit#DAYS.
The unit interface is designed to allow applications to add their own units.
A field is used to express part of a larger date-time, such as year, month-of-year or second-of-minute.
All fields implement org.threeten.bp.temporal.TemporalField.
The set of well known fields are defined in org.threeten.bp.temporal.ChronoField,
for example, org.threeten.bp.temporal.ChronoField#HOUR_OF_DAY.
An additional fields are defined by org.threeten.bp.temporal.JulianFields.
The field interface is designed to allow applications to add their own fields.
This package provides tools that allow the units and fields of date and time to be accessed
in a general way most suited for frameworks.
org.threeten.bp.temporal.Temporal provides the abstraction for
date time types that support fields. Its methods support getting the value
of a field, creating a new date time with the value of a field modified,
and extracting another date time type, typically used to extract the offset or time-zone.
One use of fields in application code is to retrieve fields for which there is no convenience method.
For example, getting the day-of-month is common enough that there is a method on LocalDate
called getDayOfMonth(). However for more unusual fields it is necessary to use the field.
For example, date.get(ChronoField.ALIGNED_WEEK_OF_MONTH).
The fields also provide access to the range of valid values.
A key part of the date-time problem space is adjusting a date to a new, related value,
such as the "last day of the month", or "next Wednesday".
These are modeled as functions that adjust a base date-time.
The functions implement org.threeten.bp.temporal.TemporalAdjuster and operate
on org.threeten.bp.temporal.Temporal.
A set of common functions are provided in org.threeten.bp.temporal.TemporalAdjusters.
For example, to find the first occurrence of a day-of-week after a given date, use
org.threeten.bp.temporal.TemporalAdjusters#next(DayOfWeek), such as
date.with(next(MONDAY)).
Different locales have different definitions of the week.
For example, in Europe the week typically starts on a Monday, while in the US it starts on a Sunday.
The org.threeten.bp.temporal.WeekFields class models this distinction.
The ISO calendar system defines an additional week-based division of years.
This defines a year based on whole Monday to Monday weeks.
This is modeled in org.threeten.bp.temporal.IsoFields.
Support for time-zones and their rules.
Support for time-zones and their rules.
Daylight Saving Time and Time-Zones are concepts used by Governments to alter local time. This package provides support for time-zones, their rules and the resulting gaps and overlaps in the local time-line typically caused by Daylight Saving Time.
The main API for dates, times, instants, and durations.
The classes defined here represent the principal date-time concepts, including instants, durations, dates, times, time-zones and periods. They are based on the ISO calendar system, which is the de facto world calendar following the proleptic Gregorian rules. All the classes are immutable and thread-safe.
Each date time instance is composed of fields that are conveniently made available by the APIs. For lower level access to the fields refer to the
org.threeten.bp.temporalpackage. Each class includes support for printing and parsing all manner of dates and times. Refer to theorg.threeten.bp.formatpackage for customization options.The
org.threeten.bp.chronopackage contains the calendar neutral API. This is intended for use by applications that need to use localized calendars. It is recommended that applications use the ISO-8601 dates and time classes from this package across system boundaries, such as to the database or across the network. The calendar neutral API should be reserved for interactions with users.Dates and Times
org.threeten.bp.Instantis essentially a numeric timestamp. The current Instant can be retrieved from aorg.threeten.bp.Clock. This is useful for logging and persistence of a point in time and has in the past been associated with storing the result fromjava.lang.System#currentTimeMillis().org.threeten.bp.LocalDatestores a date without a time. This stores a date like '2010-12-03' and could be used to store a birthday.org.threeten.bp.LocalTimestores a time without a date. This stores a time like '11:30' and could be used to store an opening or closing time.org.threeten.bp.LocalDateTimestores a date and time. This stores a date-time like '2010-12-03T11:30'.org.threeten.bp.OffsetTimestores a time and offset from UTC without a date. This stores a date like '11:30+01:00'. TheZoneOffsetis of the form '+01:00'.org.threeten.bp.OffsetDateTimestores a date and time and offset from UTC. This stores a date-time like '2010-12-03T11:30+01:00'. This is sometimes found in XML messages and other forms of persistence, but contains less information than a full time-zone.org.threeten.bp.ZonedDateTimestores a date and time with a time-zone. This is useful if you want to perform accurate calculations of dates and times taking into account theorg.threeten.bp.ZoneId, such as 'Europe/Paris'. Where possible, it is recommended to use a simpler class. The widespread use of time-zones tends to add considerable complexity to an application.Duration and Period
Beyond dates and times, the API also allows the storage of period and durations of time. A
org.threeten.bp.Durationis a simple measure of time along the time-line in nanoseconds. Aorg.threeten.bp.Periodexpresses an amount of time in units meaningful to humans, such as years or hours.Additional value types
org.threeten.bp.Yearstores a year on its own. This stores a single year in isolation, such as '2010'.org.threeten.bp.YearMonthstores a year and month without a day or time. This stores a year and month, such as '2010-12' and could be used for a credit card expiry.org.threeten.bp.MonthDaystores a month and day without a year or time. This stores a month and day-of-month, such as '--12-03' and could be used to store an annual event like a birthday without storing the year.org.threeten.bp.Monthstores a month on its own. This stores a single month-of-year in isolation, such as 'DECEMBER'.org.threeten.bp.DayOfWeekstores a day-of-week on its own. This stores a single day-of-week in isolation, such as 'TUESDAY'.