[VOTE] API elements

[Werner Keil]

Hi,

Thanks everyone for voting on https://github.com/unitsofmeasurement/unit-api/issues/184

It lead to a discussion about API elements or calls and there have been a few open for some time now.

Please use GitHub "thumbs" on 4 design questions:

• https://github.com/unitsofmeasurement/unit-api/issues/54
• https://github.com/unitsofmeasurement/unit-api/issues/103
  
• https://github.com/unitsofmeasurement/unit-api/issues/58
  
• https://github.com/unitsofmeasurement/unit-api/issues/185

To help answer, which to apply in the API for version 2.

Thanks,

Werner

[Martin Desruisseaux]

Except for #58, the issues listed below do not describe what are the proposals or are still subject to discussion. I think it is too early for vote! First, is there any discussion on those topics? On my side I have:

• request for clarification on #54 and #103
• request for discussion on #185

Martin

--
You received this message because you are subscribed to the Google Groups "Units Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to units-dev+...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Werner Keil]

The JSR should finish around the time of the new SI reform, that's two months from now. So there's not much time, at least for the API.

The question is, which of the calls are widely used and should be in the API, while others may be left to an implementation?

#54 and #103 look like they are not to frequently used even inside implementations. 

#185 is a common enough use case that Wolfram also defined structures for it and measurement in "feet+inch" or "minutes, hours, seconds" etc. are extremely common, so I'd leave that to users and those who care, if they prefer to define them in the API or in an implementation-specific manner.

Prefix graduated to the API after it was already in the RI and other implementations in JSR 363.

Werner

To unsubscribe from this group and stop receiving emails from it, send an email to units-dev+unsubscribe@googlegroups.com.

[Werner Keil]

There is also https://github.com/unitsofmeasurement/unit-api/issues/186

Unit.alternate() is not called anywhere except in classes implementing Unit.

[Werner Keil]

A final reminder for the 4 votes on design questions in the API:

https://github.com/unitsofmeasurement/unit-api/issues?q=is%3Aissue+is%3Aopen+label%3Adesign

The guidelines for these votes are mostly inspired by the JSR Ballot Rules for the JCP (EC) itself. As the EC has more members, the only tweak that seems necessary is, that the minimum number of votes should be 3 (similar to many votes at Apache) instead of 5. 

Currently only https://github.com/unitsofmeasurement/unit-api/issues/185 has sufficient votes, and would pass with 4:1 votes.

The others have between zero and 2 "thumbs". As of JCP voting rules it would finish after 7 days, so that's today (this thread started a week ago) Let's keep it till the 31st, then everything that did not reach enough votes may be discussed among the Spec Leads (where e.g. the 3 of us allow a tie-breaker vote if all 3 cast a vote, note, that https://github.com/unitsofmeasurement/unit-api/issues/185 also has 3 +1 by each Spec Lead) and unless there was a solid consensus those features will not go into the 2.0 API. They may be revisited at a later point, e.g. if new revisions came up for particular Java features, etc.

JSR 385 succesfully graduated to JCP 2.11, so it should be ready for World Metrology Day in about 2 months.

There are just 4 open tickets in the RI for 2.0: https://github.com/unitsofmeasurement/indriya/milestone/1

Cheers,

Werner

[Martin Desruisseaux]

Le 29/03/2019 à 20:51, Werner Keil a écrit :
> Currently
> only https://github.com/unitsofmeasurement/unit-api/issues/185 has
> sufficient votes, and would pass with 4:1 votes.

The rule in other organization bodies is that if there is
technically-justified objections, those objections must be answered
before vote! I asked technical questions and got no answer except
authority arguments or "Indriya does that". Please let answer the
technical questions first!

    Martin

[Werner Keil]

Martin,

It's not "Indriya does that" but for certain methods that are specific to a particular Unit or Quantity subclass "It's implementation specific".

The only question in https://github.com/unitsofmeasurement/unit-api/issues/185 is, whether or not the API shall provide this in an implementation-independent manner. So it does not matter if you use Indriya, JScience (where that gets a new release using JSR 363 or 385), SIS, UOMo or Seshat, you're able to call the API no matter which implementation.

Thanks to Filip creating very detailed JUnit tests for most unit types I derived one for the mixed Unit implementation in the RI:

https://github.com/unitsofmeasurement/indriya/blob/master/src/test/java/tech/units/indriya/unit/MixedUnitTest.java and while not as extensive yet https://github.com/unitsofmeasurement/indriya/blob/master/src/test/java/tech/units/indriya/quantity/MixedQuantityTest.java shows the same for mixed quantities primarily on the API level not a concrete class.

Werner

[Martin Desruisseaux]

Le 30/03/2019 à 00:27, Werner Keil a écrit :

The only question in https://github.com/unitsofmeasurement/unit-api/issues/185 is, whether or not the API shall provide this in an implementation-independent manner.

Yes, but my point is that if the method has no visible effect on any method accessible through the public API, then it is still implementation-specific even if a method signature appears in the Unit interface. The whole 185 issue is about trying to define an implementation-independent contract for Unit.mix(Unit), and up to now we still have none.

    Martin

[Jean-Marie Dautelle]

Hi,

There could be one API contract at the Unit level:

interface Unit<Q> {

    MixedUnit<Q> with(Unit<Q>); // Sorry I really don't like the name 'mix'

}

and one for MixedUnit

interface MixedUnit<Q> extends Unit<Q> {

    List<Unit<Q>> subUnits();

}

Cheers,

Jean-Marie

--
You received this message because you are subscribed to the Google Groups "Units Developers" group.

To unsubscribe from this group and stop receiving emails from it, send an email to units-dev+...@googlegroups.com.

[Martin Desruisseaux]

Le 30/03/2019 à 11:44, Jean-Marie Dautelle a écrit :

There could be one API contract at the Unit level:

interface Unit<Q> {

    MixedUnit<Q> with(Unit<Q>); // Sorry I really don't like the name 'mix'

}

and one for MixedUnit

interface MixedUnit<Q> extends Unit<Q> {

    List<Unit<Q>> subUnits();

}

Thanks Jean-Marie. But an API contract also needs Javadoc detailing the effect of those methods. The following questions are part of the contract in my opinion, and need answers:

What is the result of converting a value in a unit to a mixed unit (or conversely)? For example what is the result of the following:

FOOT.getConverterTo(FOOT.mix(INCH)).convert(2.5);

What is the result of the following?

FOOT.mix(INCH).getSymbol();

Is the following valid?

INCH.min(FOOT);

What is the difference (except formatting) between the following:

• 2.5 feet
• 2 feet 6 inches

Thanks

    Martin

[Jean-Marie Dautelle]

Hi Martin,

I believe there are two choices: 

1 . A composite unit (a better name I think) has the same behaviour as its main unit (only useful in formatting/parsing).

interface CompositeUnit<Q> extends Unit<Q> {

    Unit<Q> mainUnit();

    Unit<Q> subUnit();

} 

 2. A composite unit works not only on numbers but also on tuples (a single number is a tuple of dimension one => same behavior as case 1.0 except that there is truncation to integer values)

interface Unit<Q>  {

    ...

    CompositeConverter<Q> getConverterTo(CompositeUnit<Q>);

} 

interface CompositeConverter<Q>  {

    ...

    long[] convert(double value);

}

In others words: 

FOOT.getConverterTo(FOOT.mix(INCH)).convert(2.5); // Returns [2, 6]

Personally, I prefer the second choice.

Thank you,

Jean-Marie

[Jean-Marie Dautelle]

Erratum: FOOT.getConverterTo(FOOT.with(INCH)).convert(2.5); // Returns [2, 6]

[Martin Desruisseaux]

Hello Jean-Marie

Le 30/03/2019 à 15:07, Jean-Marie Dautelle a écrit :

I believe there are two choices:

1. A composite unit (a better name I think) has the same behaviour as its main unit (only useful in formatting/parsing).
2. A composite unit works not only on numbers but also on tuples (a single number is a tuple of dimension one => same behavior as case 1.0 except that there is truncation to integer values) (…snip…) In others words:
   

FOOT.getConverterTo(FOOT.mix(INCH)).convert(2.5); // Returns [2, 6] 

So do we agree about the following?

• In the case of choice #1, "Composite units" is mostly a formatting features.
• In the case of choice #2, the use of "Composite units" requires more API than current proposal, in order to operate on tuples.
  

Next question. In the case of choice #2, what is the additional measurement information (leaving formatting information apart) in the [2, 6] tuple compared to a 2.5 value that can be decomposed on-the-fly as below?

double value = 2.5;
double feet = Math.floor(value);
double inch = (value - feet) * 12;

Martin

[Werner Keil]

I think that (returning some kind of array or https://reference.wolfram.com/language/ref/MixedMagnitude.html as Wolfram calls it) would be rather messy, but does it still matter based on threads https://github.com/unitsofmeasurement/unit-api/issues/185 or https://github.com/unitsofmeasurement/unit-api/issues/189 ?

"Composite" seems a little less polluted indeed, but https://en.wikipedia.org/wiki/Statistical_unit also speaks of 

composite unit is one which is formed by adding a qualification word or phrase to a simple unit. Example :labour-hours and passenger-killometer.

It may be the least polluted term if anybody still wishes to pursue the whole idea of a "mixed unit" as opposed to a Quantity only construct that won't need an extra unit?

Werner

[Werner Keil]

Guys,

Could you have a look at those two JUnit tests and regardless of the name (Composite* seems adequate and it is not as bound to other things and types of units or quantities than many others) see which one you find better:

https://github.com/unitsofmeasurement/indriya/blob/master/src/test/java/tech/units/indriya/quantity/CompositeQuantityTest.java

vs.

https://github.com/unitsofmeasurement/indriya/blob/master/src/test/java/tech/units/indriya/quantity/MixedQuantityTest.java

The one called CompositeQuantity which works without a special Unit extension but rather holds a set of units (not so different from Date/Time with Temporal) has fewer problems to solve like the dilemma between a "vector" and a single unit. 

The two quantity types share a single functional interface QuantityConverter (not quite the same but structurally similar to the TemporalAccessor on top of almost every base type of java.time) which in theory could also be in the API. It is the most common denominator allowing to convert into a target unit regardless of being a "composite" or a normal single quantity.

Which one feels better to you?

Because CompositeQuantity is not a full Quantity implementation, the way to decompose e.g. a quantity like 2.5 feet into [2 foot, 6 inch] won't require a UnitConverter, but there could be a helper method do to this in a class like Quantities. Almost everything would be implementation specific. At most we could factor QuantityConverter out of Quantity to allow them to be handled in an API compliant way instead of using the concrete class, the rest would be specific to an implementation like Indriya.

Werner

It 

[Werner Keil]

Sorry to bother you with one more vote: https://github.com/unitsofmeasurement/unit-api/issues/190

Could you please vote on either A or B by the end of the week. No later than Sunday. 

Should there be fewer votes than 3 (binding either EG members or Committers to JSR 385) votes, we could decide among Spec Leads, otherwise the vote would fail and no further action on the API side.

Sorry for the rush, but we should get it done roughly around World Metrology Day which is just 40 days away. Thanks to JCP 2.11 we could file Public Review in the course of this month and ask the EC for a ballot after a 2 week review. 

Thanks,

Werner

[Werner Keil]

https://github.com/unitsofmeasurement/unit-api/issues/190 is done, thanks everyone who voted.

It looks like the API level design decisions for 2.0 are done, just in time for a Public Review next month.

As we migrated to JCP 2.11, EDR is no longer a true milestone, but failing to release a Public Review Draft after more than 18 months would cause a Renewal Ballot. So under those new terms we must file it before July 8, but because of World Metrology Day it should be no later than May 8 or better a few days before that. At least for the license a Final Release has to change. If the SI redefinition e.g. at BIPM, NIST or other sites caused unexpected changes we'd also adjust to that.

Otherwise the code at least of the API shall be final-quality already even on the 2.0-PRD tag. 

Regards,

Werner