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

[Roger Riggs]

Hi,

Some revisions and comments inline:

javadoc:
   http://cr.openjdk.java.net/~rriggs/javadoc-temporalamount/

webrev:
   http://cr.openjdk.java.net/~rriggs/webrev-temporalamount/

On 1/25/2013 10:54 AM, Stephen Colebourne wrote:
> 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.
right
>
> 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.
All Units have a Duration, sometimes estimated that can be used for 
conversions
if deemed necessary.
>
> 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.
Period is defined to be the 7 values that make up the amount and with
the Units and Durations the caller can convert to any desired Unit.
>
> 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).
The methods getUnits and get(unit) provide a complete picture of the 
TemporalAmount
(as long as there is no overlap between the units) any caller can 
iterate over the
supported Units and get the total value.

And the missing information is?

For example, the default method for addTo(Temporal) might be:
     Temporal plus(Temporal t) {
         Temporal accum = t;
          for (TemporalUnit unit: this.getUnits()) {
              long v = this.get(unit);
              if (v != 0) {
                  accum = accum.plus(v, unit);
              }
         }
         return accum;
      }

Changing getUnits to return List<TemporalUnit> and returning them
in decreasing duration will allow predicable use and results.
>
>
> 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.
The TemporalAmount is already effectively a Map<Unit, Long>.

Roger