Beyond dates and times, the API also allows the storage of periods and durations of time. Unless otherwise noted, passing a null argument to a constructor or method in any class or interface in this package will cause a .The API has been designed to reject null early and to be clear about this behavior.A key exception is any method that takes an object and returns a boolean, for the purpose of checking or validating, will generally return false for null.
Thus, there are separate classes for the distinct concepts of date, time and date-time, plus variants for offset and time-zone.
This can seem like a lot of classes, but most applications can begin with just five date/time types.
, are intended primarily for use with network protocols and database access.
The main API for dates, times, instants, and durations.
The classes defined here represent the principle 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. 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 .
This is intended for use by applications that need to use localized calendars.
It is recommended that applications use the ISO-8601 date 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. Where possible, it is recommended to use a simpler class without a time-zone.
The widespread use of time-zones tends to add considerable complexity to an application. This is sometimes found in XML messages and other forms of persistence, but contains less information than a full time-zone.