Package time

This package provide a proposition of classes to replace the Date and Calendar from java.util.

See:
Description

Interface Summary

Chronology

This class represents a system used by humans to describe time.

Class Summary

DayOfWeek	Definition a day of the week.
GregorianChronology	This class provides a concrete gregorian chronology.
Instant	Instant is the implementation of a fully immutable instant in time.
Interval	Interval is the implementation of an immutable time interval.
Time	Time is a representation of a piece of time.
TimeField<V>	Implements a field used in time representation.
TimeMask	A TimeMask is a sorted set of TimeField which is used to defined Time.

Enum Summary

Month

The 12 months of the year.

Package time Description

This package provide a proposition of classes to replace the Date and Calendar from java.util. It is also available in PDF format.

Indeed, thoses classes are not very well designed in Java. Their main drawbacks are:

• They should be immutable, so that they can be used as keys in Map
• They should be thread-safe
• A java.util.date does not represent a date in the common meaning of the word.
• A java.util.calendar does not represent neither a calendar, but rather a date in a particular calendar.

Several discutions have already point out thoses problems: here here and here for example.

Proposal

The goal of this document is NOT to propose yet another datetime library for Java.

It is rather to explain some concepts that, maybe, should be present in a future release that Sun would one day hopefully provide. Because we need standardization about dates in Java.

The main ideas are:

• To separate concepts like:
  • Instant
  • Date
  • Calendar system
• Good integration with Java Collections Framework
  • As any Java programmer knows this framework, it should help to use a new date/time package like this one.
• Take advantage of new capabilities of Java 1.5 :
  • Generics
  • Varargs
  • Autoboxing/Unboxing
  • Typesafe Enums
• To provide only few key classes.

Open discussions

As said, the goal of this package is to provide a basis for discussions between Java programmers, and what they would like to have in a decent date/time API. The current proposal defines that:

• A Chronology have some TimeFields (example: YEAR, MONTH, HOUR...)
• A TimeField have only a limited set of possible values (example: 0-23 for hour..., JANUARY..DECEMBER for month)
• A TimeMask groups several TimeField (so it is a collection of TimeField), and defines a time format
• A Time object is simply a map which keys are TimeField and values the value of those TimeField.

There is no relation between a Time object and the number of milliseconds since January 1, 1970, 00:00:00 GMT, and this is very important. The idea is to use theorical Time objects, that are the same for everyone. Indeed, the only important point with the 20th of October 2005, is that it is between the 19th and the 21st, wether you live in US or in Europe, or anywhere else. We should NOT care about the number millisecond since January 1, 1970, 00:00:00 GMT at this point.

Computations should be done through Chronology methods that allows:

• asSortedSet : to manipulate the Chronology as a SortedSet of all possible Time objects.
• asList : to manipulate the Chronology as a List of all possible Time objects.
• split : to manipulate a Time object as a SortedSet of its components. Examples:
  • a year as a set of its months
  • a year as a set of its weeks
  • a month as a set of days
  • a day is a set of hours
  • ...

Note than some operations can be done on Time objects, without using a specific chronology:

• compareTo : to compare chronologicaly Time objects.
• entrySet : useful to test in a Time object is part of another.

Of course, a Chronology provides methods to convert such a Time object into Interval , that allows to compute the number millisecond since January 1, 1970, 00:00:00 GMT and to provide compatibility with existing Java code.

Class diagram

Example of Code

If you want, here you can have a look at a code sample of usage of this API.

Future

If something important for you is missing in that proposal, feel free to discuss about it, so that this proposal get modified to take your need into account.

Please also note that today, the only implementation of Chronology is GregorianChronology, and is not finished.

Historical

2005, 15th of November

First public release

Copyleft notice

Copyleft notice: This is public-domain software and documentation with no restrictions of any kind. Please feel free to use any of it in any way you want. This work is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.