Early Draft

52 views
Skip to first unread message

Werner Keil

unread,
Nov 26, 2014, 10:56:54 AM11/26/14
to unit...@googlegroups.com
Hi,

JSR 363 is soon about to publish Early Draft.

Feedback is welcome either here on the mailing list or for those of you with java.net account feel free to use JIRA.

Cheers,
Werner

Jean-Marie Dautelle

unread,
Nov 26, 2014, 1:53:02 PM11/26/14
to unit...@googlegroups.com
Hi Werner and All,
I am fine with this early draft (it is very close to latest JSR-275 work). I am not sure we should keep the QuantityFactory and spi package in the API though (too implementation dependent).
Cheers,
Jean-Marie. 

--
You received this message because you are subscribed to the Google Groups "units-dev" 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.



--
It is not the strongest of the species that survives, nor the most intelligent. It is the one that is most adaptable to change. - Darwin's Origin of Species (digest)

Werner Keil

unread,
Dec 4, 2014, 5:47:24 PM12/4/14
to unit...@googlegroups.com
Jean-Marie/all,

Thanks a lot for the feedback.

Note, QuantityFactory in the API is the interface used by a concrete class like QuantityFactoryImpl or whatever you call it.
These classes may use either DynamicProxies under SE 8 or something else like Java SE Service Loader, LIBlets or OSGi. thus it makes sense in the API but say a static factory like Quantities in the RI could also work without it. We can discuss it and see, if it's necessary or not beyond EDR.

Thanks,
Werner


Am Mittwoch, 26. November 2014 19:53:02 UTC+1 schrieb Jean-Marie Dautelle:
Hi Werner and All,
I am fine with this early draft (it is very close to latest JSR-275 work). I am not sure we should keep the QuantityFactory and spi package in the API though (too implementation dependent).
Cheers,
Jean-Marie. 
On Wed, Nov 26, 2014 at 4:56 PM, Werner Keil wrote:
Hi,

JSR 363 is soon about to publish Early Draft.

Feedback is welcome either here on the mailing list or for those of you with java.net account feel free to use JIRA.

Cheers,
Werner

--
You received this message because you are subscribed to the Google Groups "units-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to units-dev+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

Werner Keil

unread,
Dec 11, 2014, 6:05:45 AM12/11/14
to unit...@googlegroups.com
Sharing this from units-users, as it is a little more developer specific...

Am Donnerstag, 11. Dezember 2014 11:44:11 UTC+1 schrieb Chapman Flack:

Hi,

It's possible I'm way too late with this suggestion (and it may have
been beaten to death in discussions I didn't see), but I think it could
be very useful to have more introspective access into a UnitConverter.

An example use would be: on a full environment with Java and a
comprehensive unit database, select any two obscure units and
construct a UnitConverter between them, then let some application-
supplied code-generator visitor be sent down the resulting UnitConverter
and its children, emitting custom code to perform that conversion on
some much more constrained device.

Doing this nicely would probably entail some attempt to enumerate what
basic kinds of UnitConverter may exist. My guess is there probably are
not very many. Two kinds are already treated specially with the
isIdentity() and isLinear() methods, but I could imagine a structure like:

interface UnitConverter {
  interface Polynomial extends UnitConverter { getCoefficients(); }
  interface Linear extends Polynomial { getSlope(); getIntercept(); }
  interface Log extends UnitConverter { getBase(); }
  interface Exp extends UnitConverter { getBase(); }
  interface Rational extends UnitConverter {
    UnitConverter getDividend(); UnitConverter getDivisor();
  }
}

Am I crazy in thinking a small set like that would cover a large
fraction of UnitConverters in practice? Weird things like currencies
might not fit the scheme, so they might not implement any of the more
specific subinterfaces, and not be easily rendered into code for another
environment.

With the current API, if you get a converter and its isLinear() returns
true, you could pump two values through it and determine what it is, but
that's a little hackish and could get you an approximate result.

Another subinterface that might be of interest could be:

interface Inexact extends UnitConverter {
  getRelativeError();
  getDomainMin();
  getDomainMax();
}

... for a converter that is known not to be using an exact conversion, but
has a known relative error for inputs in a certain range.  So a converter
from km to [mi_i] could be linear with slope 15625/25146 exactly, or the
often-used approximate slope 5/8 with getRelativeError() returning 6e-3...

Chapman Flack

Martin Desruisseaux

unread,
Dec 12, 2014, 7:58:03 AM12/12/14
to unit...@googlegroups.com

Hello Werner

Le 27/11/14 00:56, Werner Keil a écrit :

Sorry for being so late. I just had a look and the specification, and it looks okay. I fixed some formatting but otherwise did not edited the content. Below are my comments about the content:

Page 8 - Objective

The three last bullets at the bottom of the page (about concrete classes) are not part of the specification, but rather of the reference implementation. I suggest to either omit them, or insert a line before them saying "The reference implementation includes:".

Page 9 - Aspirations

First bullet ("Small or no runtime overhead compared with an implementation not using Unit-API") is not true: there is a huge overhead in using arithmetic operations on Quantity compared to double primitive type. I suggest to either remove that bullet, or explain that it may be true only when using UnitConverter directly, not Quantity.

Page 12 - Online-shop

Paragraph contains "decimal point number" words. Do you mean "floating point number", or maybe "decimal number"?

Page 12 - Internet of Things

Where the picture come from? Do we have the right to insert it in our document (does the picture has a license)?

Could the Medical & Healthcare and Quantified Self use cases give actual examples of units or quantities?

I wonder if the following sentence should be rephrased? In particular starting with something else the "See", avoiding acronyms not defined in the specification. I'm also do not quite understand what is a "connected scale".

See a few personal health devices from “Smart Pill Boxes” (knowing the dosage a patient needs based on their EHR) to connected scales, blood pressure, heartbeat or sugar sensors.

Page 16 - code example

I don't think that Vector should implement Quantity. It could have implemented Measurement if we had kept that interface, but not Quantity if we understand it as a scalar measurement. I suggest to replace the first line by:

public class Vector<Q extends Quantity> {


I have not yet finished. Will continue the review a little bit later...

    Martin


Werner Keil

unread,
Dec 12, 2014, 1:40:29 PM12/12/14
to unit...@googlegroups.com
Hello Martin,

Please see answers  inline.

Hello Werner

Le 27/11/14 00:56, Werner Keil a écrit :

Sorry for being so late. I just had a look and the specification, and it looks okay. I fixed some formatting but otherwise did not edited the content. Below are my comments about the content:

Page 8 - Objective

The three last bullets at the bottom of the page (about concrete classes) are not part of the specification, but rather of the reference implementation. I suggest to either omit them, or insert a line before them saying "The reference implementation includes:".


Could you do what you think is better? Either remove or since there's a whole "Implementation" chapter dedicated to the RI move it there.
 

Page 9 - Aspirations

First bullet ("Small or no runtime overhead compared with an implementation not using Unit-API") is not true: there is a huge overhead in using arithmetic operations on Quantitycompared to double primitive type. I suggest to either remove that bullet, or explain that it may be true only when using UnitConverter directly, not Quantity.

Well, if you use BigDecimal together with Unit (or worse, a String saying "kg" or similar;-) is there really such a big overhead compared to that?
Java aims to completely eliminate primitives in the near future, so I would leave it. This sentence does not go into specifics like Quantity or UnitConverter, it talks about the whole JSR. 

Page 12 - Online-shop

Paragraph contains "decimal point number" words. Do you mean "floating point number", or maybe "decimal number"?


This was derived almost entirely from https://github.com/JavaMoney/jsr354-api/blob/master/src/main/asciidoc/JavaMoneySpecification.adoc so something that needs to be phrased differently, please advice. And if the source really got it wrong, it should also be fixed in the 354 Spec (which I could take care of;-)
 

Page 12 - Internet of Things

Where the picture come from? Do we have the right to insert it in our document (does the picture has a license)?


It's from presentations I did for a long time about UOMo, so the original image is from Eclipse Foundation and the former M2M IWG (now simply Eclipse IoT)
All images are either Creative Commons or more likely EPL licenced at Eclipse. 

I put a disclaimer there similar to the one from earlier slides (as they are publicly visible from DemoCamps, etc. any issue by Eclipse Foundation would have been raised, but they're of course in the EC so they would tell  us in the review;-)
 

Could the Medical & Healthcare and Quantified Self use cases give actual examples of units or quantities?

I wonder if the following sentence should be rephrased? In particular starting with something else the "See", avoiding acronyms not defined in the specification. I'm also do not quite understand what is a "connected scale". 

See a few personal health devices from “Smart Pill Boxes” (knowing the dosage a patient needs based on their EHR) to connected scales, blood pressure, heartbeat or sugar sensors.

This is an example for a "smart" or connected scale: http://www.withings.com/eu/ws-30.html I don't want to refer to a particular product, but the general type of device seems rather clear.
 

Page 16 - code example

I don't think that Vector should implement Quantity. It could have implemented Measurement if we had kept that interface, but not Quantity if we understand it as a scalar measurement. I suggest to replace the first line by:

public class Vector<Q extends Quantity> {



Please correct or remove, some lines go back all the way to JSR 275


Thanks,
Werner 

Martin Desruisseaux

unread,
Dec 12, 2014, 8:42:14 PM12/12/14
to unit...@googlegroups.com
Hello Werner

Thanks for the reply. I will apply the agreed modifications later today, and will post an other email for the remaining of the spec. Sorry for being so late, I have been busy all last week with an other Open Geospatial Consortium meeting.

Le 13/12/14 03:40, Werner Keil a écrit :

Page 9 - Aspirations

First bullet ("Small or no runtime overhead compared with an implementation not using Unit-API") is not true: there is a huge overhead in using arithmetic operations on Quantitycompared to double primitive type. I suggest to either remove that bullet, or explain that it may be true only when using UnitConverter directly, not Quantity.

Well, if you use BigDecimal together with Unit (or worse, a String saying "kg" or similar;-) is there really such a big overhead compared to that?
Do sentence do not specify under which circumstances there is no overhead. The vast majority of developers use the double primitive types, for which there is a huge overhead. Furthermore even in the case of BigDecimal, we still have the cost of checking the unit, potentially applying conversion or unit multiplication.

So this sentence rather looks like false advertisement - I don't think that we can honestly keep it.

    Martin

Martin Desruisseaux

unread,
Dec 13, 2014, 5:58:43 AM12/13/14
to unit...@googlegroups.com

Hello Werner, Frank and all

Answers below, separated in 3 sections (types, coefficients and errors):

On unit conversion types

I agree with Frank that some way to get the formulas used by a UnitConverter may be useful. The interfaces proposed by Frank could work, but it may be a little bit late for introducing them. Furthermore defining those interfaces may expose more implementation details than desired:

  • An implementation could choose to implement logbase(x) as ln(x)/ln(base).
  • An other implementation could choose to implement logbase(x) as the concatenation of ln(x) with a linear conversion.

If we provide the proposed UnitConverter sub-interfaces, it would make the above implementation choices more visible.

A partial alternative could be to replace the isIdentity() and isLinear() methods by a single getConversionType() method which would returns one of the following enum values:

enum ConversionType {IDENTITY, LINEAR, LOGARITHMIC, EXPONENTIAL, OTHER}

I think the identity, linear, logarithmic and exponential cases cover almost all unit conversions in SI and imperial system, except conversions of sexagesimal degrees to decimal degrees. Admittedly this enum proposal does not provide the function coefficients.

On unit conversion coefficients

On Frank's point about the difficulty to get the coefficients of the underlying conversion (current API leads to approximative values), I agree with him. I proposed a while ago the following methods in UnitConverter:

/**
 * Returns the derivative of this conversion function at the given value.
 * Note that for a linear conversion, the derivative is the slope and is the same for all x values.
 */
double derivative(double x);

Derivatives are really needed for advanced users. For those who are not so comfortable with mathematics, at least this method allow them to get the slope of a linear function, which meets part (admittedly not all) of Frank's request.

On unit conversion errors

If we take inspiration from ISO 19111 (coordinate operations) terminology, a conversion is by definition exact to the accuracy allowed by floating point operations. An operation with known errors (not due to floating point rounding errors) is called transformation, and I think is out of scope of JSR-363 since there is many kinds of such errors. Furthermore, unit conversions are often exact by definition. For example the conversion factor from inches to centimetres is 2.54 by definition, so I don't think that we need (or should) handle the case of approximative transformations. I would rather said in the specification that implementations shall use the official definitions with all the accuracy given by the standard body.


    Martin

Le 11/12/14 20:05, Werner Keil a écrit :

Werner Keil

unread,
Dec 19, 2014, 7:56:37 AM12/19/14
to unit...@googlegroups.com
Let's discuss that further beyond EDR 1.

Most enums were moved to RI or always stayed there (see UCUMFormat.Variant)
I can't say, if a ConversionType makes sense in the public API, if so, likely just as (static) inner enum of UnitConverter like the UCUM Variant)
Otherwise maybe better in the RI and other implementations. 

Werner

Werner Keil

unread,
Dec 19, 2014, 8:03:40 AM12/19/14
to unit...@googlegroups.com
Please find the Early Draft (0.7) version of the JSR 363 Specification on java.net:

At least after the Christmas break, JCP PMO should publish the Early Draft on jcp.org.

We won't all go into "hibernation", but some may be less active during the holidays.

So for those who won't come by in the next couple of weeks

Merry Christmas and a Happy New Year,

Werner
on behalf of the JSR 363 EG

Werner Keil

unread,
Jan 1, 2015, 9:40:45 AM1/1/15
to unit...@googlegroups.com
Just before the end of 2014, the EDR was published on jcp.orghttps://jcp.org/aboutJava/communityprocess/edr/jsr363/index.html

Werner Keil

unread,
Aug 10, 2018, 1:03:18 PM8/10/18
to Units Developers
Hi,

JSR 385 is about to publish an Early Draft soon (based on JCP.next it should be no later than 9 months after the JSR was approved)


While comments and recommendations about arithmetics have also been added to JavaDoc, actual measures like RI or API changes are for the next stage as per our pre EDR call. 
A new project in the GitHub organization exists for the PR of JSR 385: https://github.com/orgs/unitsofmeasurement/projects/2

Kind Regards,
Werner

Jean-Marie Dautelle

unread,
Aug 12, 2018, 8:39:09 AM8/12/18
to unit...@googlegroups.com
Hi Werner and All,

It looks good, but is there a way to identify what has changed from version 1.0 (e.g. font color different).
This would be useful for people who already know v 1.0 and want only look at the changes.

Thanks,
Jean-Marie


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

Werner Keil

unread,
Aug 12, 2018, 4:10:34 PM8/12/18
to Units Developers
Hi Jean-Marie,

I cannot say, if Google Docs has this kind of feature? 
Has someone seen such a "diff" or used it?

Werner


Am Sonntag, 12. August 2018 14:39:09 UTC+2 schrieb Jean-Marie Dautelle:
Hi Werner and All,

It looks good, but is there a way to identify what has changed from version 1.0 (e.g. font color different).
This would be useful for people who already know v 1.0 and want only look at the changes.

Thanks,
Jean-Marie

Martin Desruisseaux

unread,
Aug 13, 2018, 7:59:02 AM8/13/18
to unit...@googlegroups.com
Le 12/08/2018 à 22:10, Werner Keil a écrit :
> I cannot say, if Google Docs has this kind of feature? 
> Has someone seen such a "diff" or used it?

I have not seen, but I agree that a diff would be useful. Or
alternatively, an annex listing the changes.

    Martin


Werner Keil

unread,
Aug 13, 2018, 11:03:36 AM8/13/18
to Units Developers

Werner Keil

unread,
Aug 17, 2018, 8:55:25 AM8/17/18
to Units Developers
Hi,

As there are no more open items for EDR (https://github.com/orgs/unitsofmeasurement/projects/1) I plan to tag it by tomorrow.
The Final Release of 1.0 was frozen on August 16, 2016, so 18-08-18 sounds like an equally nice date for the EDR code-freeze ;-)

As we are now approaching 2.0 a pattern similar to CDI
looks good. The CDI team was not always completely consistent with their tagging, but a pattern like "X.Y-EDR1" or "X.Y-PFD" was followed.

I plan to stick to the JCP numbering, as long as there is no 2nd EDR (we do not envision it at this point) it is called "Early Draft 2" but the initial EDR is simply called "Early Draft Review", so the label can just be "2.0-EDR".

The Spec Document is still open for comments or updates till we actually file the EDR. Should be within the next 2 weeks.

Werner

Martin Desruisseaux

unread,
Aug 17, 2018, 9:24:27 AM8/17/18
to unit...@googlegroups.com

Hello Werner

Sorry if my question is trivial. Could we summarize the situation please?

  • Could you remind us what is EDR?
  • What is final for this EDR; is it the Java classes for the API, or the implementation?
  • Can we have a summary of what has changed in the specification document compared to JSR-363?

Thanks

    Martin


Werner Keil

unread,
Aug 17, 2018, 4:14:54 PM8/17/18
to Units Developers
Hi Martin,

I thought you would know the answer to the first one, but since not everyone has a long history with the JCP who may follow this list,
EDR is the Early Draft Review of a JSR, same as https://jcp.org/aboutJava/communityprocess/edr/jsr363/index.html for JSR 363

Nothing is final, that's what the Final Release will be.
There are at least 2 other milestones (ignoring possible repeating steps for each of those) like Public Review and Proposed Final Draft.
Both of these also get a vote by the Executive Committee, EDR is not voted on.

I'm afraid, Google Docs is not so helpful when it comes to comparing. I got to name a particular version at the end of August 2016 (the last change was 2017 long after the Final release) JSR 363 Final Release, but the compare of Google Docs is messy and takes too much space. The Delta printed to PDF is nearly 12MB big, so please for now try it yourself but under no circumstances restore the old version !!!

I try to upload the big PDF to https://bintray.com/unitsofmeasurement/downloads, we have larger files there, e.g. the history of JIRA tickets from java.net.

HTH,
Werner

Werner Keil

unread,
Sep 3, 2018, 7:32:12 AM9/3/18
to Units Developers
Hi,

As the PMO is now back from their vacation and most changes including Daniel as recent EG Member (after he had already been contributor, but he is a full JCP Member, so he decided to "upgrade") are now in place, I plan to submit the EDR within a few days.

So it should be processed (it's not like the JCP has too many JSRs right now anyway;-) in the course of September.
It may be a bit of a challenge for that, but in about a week Filip got a JSR 385 session at JavaZone (https://2018.javazone.no/) which also is a perfect occasion to mention the EDR and invite people to review it and participate if they want.

Regards,
Werner

daniel.dias.analistati

unread,
Sep 3, 2018, 12:57:47 PM9/3/18
to Units Developers
Hi all, 

thanks Werner  for support  .

Werner Keil

unread,
Sep 4, 2018, 5:41:39 AM9/4/18
to Units Developers
You're welcome. And thanks for the input on the spec.

I sent out the EDR last night. Hope it can be published soon?

daniel.dias.analistati

unread,
Sep 4, 2018, 10:19:26 AM9/4/18
to Units Developers
in case it was sent to JCP?

Werner Keil

unread,
Sep 4, 2018, 5:42:31 PM9/4/18
to Units Developers
Yes it was.

Werner Keil

unread,
Oct 17, 2018, 8:50:24 AM10/17/18
to Units Developers
The Early Draft of JSR 385 concluded last Saturday.

Otavio (who should be there before OC1) and maybe myself by phone are expected to summarize the progress of the JSR at this stage. Either on Bintray or via jcp.org in the minutes those slides should also be available after the F2F. 

Thanks everyone who helped by contributing.

Werner
Reply all
Reply to author
Forward
This conversation is locked
You cannot reply and perform actions on locked conversations.
0 new messages