Update the javadoc with the suggestion to remove generics from
Era, ChronoLocalDate, and Chronology.
Still work in progress, the samples have not been updated
and the javadoc may still refer to generic parameters in places.
On 2/3/2013 8:59 AM, Roger Riggs wrote:
On 02/02/2013 06:26 PM, Stephen Colebourne wrote:
I've taken a quick look. It seems that the generics have changed from
Chronology to date class, which strikes me as different rather than
better. Can you give any examples where this makes user code simpler?
And why you see it as an improvement?
The move to generics around the date types makes the code written
easier to read without bloating the api with separate types of DT, ZDT.
My thoughts in #191 were trying to remove generics entirely from
Chronology and Era. My theory is that a user will work in one of three
a) only with ISO, and thus with concrete types
b) only with a non-ISO calendar system, and thus a public XxxDate class
c) only at the abstract chrono-level
A single user with a small application might have the luxury of working in only
one of those modes at their own choice. But real systems are mixes of imported
libraries and utilities.
And even a single developer may find value in developing utilities that are re-usable.
If there is a public XxxDate class, then (a) and (b) users are happy
(with the exception of (b) user accessing
The generics are useful in this case to avoid a forced shift between b and c.
The real question is whether those (c) users working with the abstract
chrono-level care about whether the calendar system object they are
passing around is the same as that of another object (which either
form form generics allows). The question would seem partly answered by
j.u.Calendar, which doesn't restrict or generify by calendar system.
At the interface between an application wanting to write a calendar specific
application and a library providing calendar independent functions the
generics provide type checking at the integration point. If the library provides
return types parameterized by the date types, the caller does not have
to drop down to the abstract chrono API to handle the returned datetime values.
We also have Oracle Globalization team comments that they would always
create a date in the abstract, without knowledge of the calendar
system. Given this, there is no way to ever populate the generic
argument from typical chrono-level usage. Thus whether the generic it
is a Chronology or a ChronoLocalDate is irrelevant.
They also recognize the value of being able to use both models.
No generics on any of the five key classes (Chronology, Era,
ChronoLocalDate, ChronoLocalDateTime, ChronoZonedDateTime) requires
three public classes for each calendar system, which seems overkill.
Yes, this is one reason to retain the generics .
A more practical/balanced approach would be:
- Chronology - no generics
- Era - no generics
- ChronoLocalDate - no generics
- ChronoLocalDateTime<D extends ChronoLocalDate>
- ChronoZonedDateTime<D extends ChronoLocalDate>
With this approach, chrono-level users (c) would use ungenerified
types Chronology/Era/ChronoLocalDate and wildcarded
ChronoLocalDateTime<?> and ChronoZonedDateTime<?>. Whereas (b) users
would use XxxChronology, Era, XxxDate, ChronoLocalDateTime<XxxDate>
For me, the question here was whether this approach could be made to
work, as it seemed to be the approach that met the needs of users (a),
(b) and (c) best.
If Chronology is not parameterized, there would be cases where it would be
desirable to pass in a particular known chronology and get back a date-time
object known to be of that chronology.
Perhaps a minor point, but without generics on ChronoLocalDate many
methods would need to be overridden to return the correct type.
I'll spend some more time this afternoon looking at this.
On 2 February 2013 21:43, Roger Riggs <Roger.Riggs@oracle.com> wrote:
I took another look at the use of generics in the Chrono classes and
drafted an alternative that is an improvement.
Issue #191 mentions that the generics do not add (enough) value.
Changing the parameter from Chronology to the concrete ChronoLocalDate type
is more usable for the case where the concrete date type is being used
and enable greater fluency.
Exposing the concrete date types along with the Chronology types makes
to write calendar specific applications and makes code using
and ChronoZonedDateTime more fluent.
Take a look at the comment.
This is not ready to commit, though the functionality of the local date
classes is stable, the javadoc needs improvement.
In particular, the exposure of useful methods in the javadoc of each class
is uneven since some are inherited and only appear in the inherited section
of the javadoc.