[threeten-dev] [threeten-develop] Rough draft of TemporalAmount

[Stephen Colebourne]

On 25 January 2013 15:21, Roger Riggs <Roger.Riggs at oracle.com> wrote:
> So, the simplest option is
> Duration = SECONDS + NANOS
> Period + YEARS + MONTHS + DAYS + NANOS
>
> The javadoc for Period describes itself has supporting the most commonly
> used units
> including "time units with an exact duration".  To be consistent get(unit)
> should follow
> that pattern.

I think that we need to require that the combination of getUnits() and
get() returns the complete state of the object.

A Period is an amount, created by adding the total of years, months
days and time (in nanos). A user querying the period should be able to
get the total "amount". If hours/minutes/seconds are supported, then
get(HOURS)+get(MINUTES)+get(SECONDS)+get(NANOS) should be the total
amount, and all other units would be an error.

The alternate model for the interface is that it is just a "friendly"
get, like Temporal, that returns as much as it can. But we don't have
the rest of the infrastructure to do that in terms of converting a
user type of HALF_YEARS from the provided type of YEARS.

Given that there are multiple choices this gets tricky.

(I note again that adding this interface is risky because we don't
have the use cases to validate it. Adder and Subtractor are safe and
cannot be wrong. This interface may well not be what we really need,
forcing a TemporalAmount2 in the future)

I would say that these models:
 Period = YEARS + MONTHS + DAYS + NANOS
 Period = YEARS + MONTHS + DAYS + HOURS + MINUTES(excluding hours) +
SECONDS(excl hr/min) + NANOS(excl hr/min/sec)
provides sufficient data for later default interface methods. (ie.
where only the above units can be queried.) The former is a more
accurate representation of the state of the class and easier for
framework code to work with. The latter is more designed for human
code.

The choice of providing a general conversion mechanism using durations
in get(Unit) may be nice for users, but it would be non-extensible in
future JDKs (default interface methods would have insufficient
information to work with).


Given all this, I think  Period = YEARS + MONTHS + DAYS + NANOS is the
simplest model. But since its not very user friendly, it may be best
to return it as a Map<Unit,Long>, or to rename get(Unit) to something
less attractive.

Stephen