[threeten-dev] Comments from Oracle on Threeten APIs

[Roger Riggs]

Several senior Oracle JDK developers reviewed the Threeten API and made 
the following proposals and comments to address incongruities between 
the JSR 310 java.time APIs and the organization and design patterns of 
the JDK.

  * java.time.temporal package should be reorganized to improve
    usability and gather functionally similar types together.
      o The support for non-Iso calendars should be consolidated in a
        new package.
        javax.time.chrono includes Chronology (renamed from Chrono),
        ChronoLocalDate, ChronoLocalDateTime, ChronoZonedDateTime, Era,
        and ISOChrono classes.  This will help cleanup the mixed-bag of
        types in temporal.
      o The OffsetDate, OffsetDateTime, and OffsetTime classes are moved
        to java.time; these classes have the same level of use as
        LocalDate, ZonedDateTime and developers will expect them to be
        co-located.
      o The Year, YearMonth, and MonthDay classes are not central to the
        API and should be removed; if not removed they are moved to the
        java.time package since they are functionally similar to the
        other classes in java.time.
      o The Temporal package has the interfaces for date-time types, the
        frameworks for fields and units, and the adjusters.
  * java.time.format package improvements to better align with other JDK
    designs and patterns:
      o The DateTimeFormatter factory methods currently in
        DateTimeFormatters are moved to DateTimeFormatter; it is natural
        to look in DateTimeFormatters for the factories and predefined
        DateTimeFormatters.  Currently, there are no constructors or
        factory methods in DTF.
      o The print method is renamed to format throughout the 310 API; 
        the name is a better fit for the function and follows the more
        naming pattern used in java.lang.String and the java.util.Formatter.
      o For improved usability, concrete date-time classes with a format
        (aka print) method should also have a format method that takes
        the pattern as an argument, i.e.  format("yyyy-mm-dd").
  * In JDK class and method names camel-case is prevalent and more
    readable, change ISO to Iso.
  * Add  @FunctionalInterface where appropriate
  * Duration.parse - parsing grammars should be specified in EBNF
  * The Clocks class would be better as an interface with static methods
    (when available).
  * The TemporalAdder and TemporalSubtractor should be a single interface.
  * The plethora of plusXXX(n), minusXXX(n), methods are adequately
    covered by the plus(n, UNIT) and minus(n, UNIT) methods and are
    unnecessary and add to the excessive number of methods.
  * Implementation notes that are normative should not be labeled
    implementation notes which implies the implementation has a choice
    of implementation.
  * The ISO specific class Month should be named ISOMonth, similarly
    perhaps DayOfWeek as ISODay
  * The Queries class name is too generic, perhaps TemporalQueries or
    move them to the TemporalQuery interface.
  * DateTimeBuilder needs work or does not belong in the format package.

Thanks to Mark Reinhold, Joe Darcy, and Brian Goetz and others for comments.

I will followup with issues in the tracker to gather any additional 
discussion, comments and resolution.

Since the M6 cutoff is next week, it is unlikely that these can be 
addressed for M6.

Roger