DateTimeCalendarTimeZoneClasses modified by Stephen Colebourne

Stephen Colebourne — Thu, 22 May 2014 22:08:11 -0000

This choice is about how to integrate time zones with the calendar classes.

Option 1 - Parallel classes
Option 2 - Superclass and two subclasses (zoned and local)
Option 3 - Special 'local' time zone
Option 4 -Zoned generic class

Option 1 - Parallel classes

With this option we would create one time zone aware class for every local class. Exactly which classes that would be depends on DateTimeCalendarClasses. One possible scenario would be:

ZonedYear
ZonedMonth
ZonedDate
ZonedHour
...

The advantage is consistency with the main set of local classes.

The disadvantage is another set of classes to use and be familiar with.

A related problem is that once you have two classes that are very similar, users expect there to be a common superclass.

This option only provides a method on

ZonedDate

called

getCalendarDate()

, or similar. If a use writes an API that can accept a date (and the API doesn't care whether it has a time zone or not), then the API must be written to take a

CalendarDate

. The caller of that API would have to extract the

CalendarDate

from their

ZonedDate

to call the API.

 public void doStuff(CalendarDate date);

 ZonedDate zd = ...
 doStuff( zd.getCalendarDate() );

Option 2 - Superclass and two subclasses (zoned and local)

This variation on option 1 has a superclass for each class and two subclasses - one zoned and one local:

CalendarDate - superclass - makes no statement on time zones
LocalDate - subclass - states that there is no time zone (date is local)
ZonedDate - subclass - has full time zone information and calculations

This does simplify the example in option 1, allowing the API to be defined to take any date, just a local date, or just a zoned date.

The disadvantage is a third set of classes in the JSR.

 public void doStuff(CalendarDate date);

 ZonedDate zd = ...
 doStuff( zd );

Option 3 - Special 'local' time zone

This option converts all the local datetime classes to be dual-use. Thus, CalendarDate would have a new time zone property. If the time zone is the special 'local' zone then the date is local. Otherwise, the date is zoned.

The advantage is reuse of a single API by passing in a parameter.

The disadvantage is that the javadoc would be very complex. It would have to try to describe what values are valid or not valid, and what will occur when it differs depending on whether it is a special local zone or not.

Option 4 -Zoned generic class

This option uses a single generic class to add time zone aware datetimes:

 Zoned&lt;CalendarDate&gt; zonedDate = Zoned.create(calDate, timeZone);

The advantage is a single implementation class.

The disadvantage of this option is that any methods to access fields such as day of week would throw an exception if the precision of the underlying class is not sufficient.

Home page

Recent changes to DateTimeCalendarTimeZoneClasses

DateTimeCalendarTimeZoneClasses modified by Stephen Colebourne

Option 1 - Parallel classes

Option 2 - Superclass and two subclasses (zoned and local)

Option 3 - Special 'local' time zone

Option 4 -Zoned generic class