[threeten-develop] Feedback on the threeten apis

[Roger R. <Roger.Riggs@Oracle.com>]

Hi,

As a test case for the APIs, I implemented a simple algorithm using
the current the LocalDate API and the ChronoDate API.

The algorithm would be used in an application on a tablet, phone, or 
desktop to
show the user the date of the next payday and tell how many days until 
payday.
Payday is the 15th or last day of the month unless it falls on a weekend 
and
then it is the previous Friday.

The Chrono API  would be needed to be able to display the dates in the 
calendar
of the locale of choice by the user.

The developer will need to choose from the available APIs and after making
a choice  it should be easy to change if the other API satisfies some 
late requirement.

Here's what I ran into for the LocalDate version:

    * LocalDate's weekday enums made it awkward to compute and skip back
      to Friday.
          o   int pastFriday = payday.getDayOfWeek().getValue() -
            DayOfWeek.FRIDAY.getValue();
                     if (pastFriday > 0) {
                         payday = payday.minusDays(pastFriday);
                     }
          o The compound condition on the date and the day of the week
            are not supported
            by the adjusters.  Of course, any number of special cases
            could be provided but
            the developer still has to look/know.
    * The LocalDate last day of the month seems to deserve some special
      treatment.
      How about withDay(-1) or withDay(-n) to compute from the end of
      the month.
    * For LocalDate, computing the number of days until payday isn't too bad
      once you find the pieces of the API but they are not that easy to
      find:
          o

                 return LocalDateUnit.DAYS.between(payday, date).getAmountInt();

For the ChronoDate version the problems included:

    * No definition of the days of the week, no symbolic names for
      MONDAY..SUNDAY 1..7.
          o int pastFriday = payday.getDayOfWeek() - 5;
                     if (pastFriday > 0) {
                         payday = payday.minusDays(pastFriday);
                     }
    * The last day of the month computation was not directly available
      but easily computed as:
          o

            date.withDayOfMonth(1).plusMonths(1).minusDays(1);

    * Computing the number of days until payday  or days between dates was
      not directly available but computable the hard way from
      day-of-year and handling wrap-around.
      But the number of days in the year was not directly available and
      had to be computed.
          o   int daysinyear =
            date.withDayOfMonth(1).withMonthOfYear(1).plusYears(1).minusDays(1).get(ChronoDateField.DAY_OF_YEAR);

Some of these are simple omissions in the API and can be fixed.

This is an example where the same algorithm has to be coded differently
depending on the API chosen. There doesn't seem to be a compelling reason
that the ISO and Chrono APIs are different but developers will have to 
deal with
different APIs and their quirks.

Roger

BTW, The CopticChrono does not produce reasonable dates.

The names for the Days of the Week are all upper-case (FRIDAY) in LocalDate
and in java.util.Calendar are Cap-case (Friday).