[JSR-354] Re: JSR API und Javadoc Updates
- From: Werner Keil <werner.keil@...>
- To: "jcurrency_mail@javamoney java. net" <jcurrency_mail@...>
- Subject: [JSR-354] Re: JSR API und Javadoc Updates
- Date: Sun, 22 Sep 2013 21:56:08 -0700
Some comments inline
Am 22.09.2013 21:02 schrieb "Anatole Tresch" <atsticks@...>:
> Hi Stephen
> a few comments from my side -inline -, other comments from EG colleagues
> 2013/9/23 Stephen Colebourne <scolebourne@...>
>> Some comments on more specific items.
>> The interfaces specify a serialization format, but that does not make
>> sense. Different implementations cannot be serialization compatible as
>> the format includes the class name of the implementation.
> This is obviously the case, so it may be sifficient to state that
implementations must be serializable.
>> CurrencyUnit adds getCashRounding(), but doesn't explain why it is
>> needed compared to fraction digits. If there is a use case, then an
>> example would be beneficial.
> I will update the JavaDoc...
>> MonetaryAmount makes an attempt to define lots of implementation rules
>> in the spec, but it is really difficult to make it happen.Trying to
>> specify constructors for example is difficult as some implementers may
>> want only factory methods. The Money class does not implement the
> should we leave the choice to the implementation, how amounts are
created? That would possibly lead to incompatibilities... WDYT?
Since when does the Money class not implement MonetaryAmount?
I guess this is up to implementations, whether they provide a constructor,
factory methods or both. BigDecimal itself also does both. And especially
in Java 8 I came across cases, where a constructor works perfectly fine, a
static of() or value of() method however fails. Maybe it's due to SE 8 and
underlying JSRs still a bit unstable?;-)
(it's only going EDR so by reaching PDR any week this JSR has bypassed all
of it in stability and maturity it seems;-)
>> More broadly, the API is designed in terms of BigDecimal methods, yet
>> does not expose BigDecimal.
> Yes, we had quite a couple of discussions about that. With the latest
update the overall footprint of BD related methods, was at least reduced
(floatValue, byteVale, for example, where removed).
Today's JavaOne keynote showed quite clearly, that Java 9 and beyond the
"SE ring" outside what is common to all Java editions (except EE) will
shrink drastically. Everything else, quite likely also bigger APIs like 310
become optional. In this Single-source world Java is also heading similar
to Windows 8 or Apple's latest OS we shall not expose anything specific to
Java SE like BigDecimal that may never enter the Java "core".
Implementations are free to use it internally, but the main API elements
should be free from such overhead.
>> MonetaryAmount uses from() as an instance method, where that is now
>> used by JSR-310 as a static method.
> Should we use with instead?
>> The Function/Operator/Predicate interfaces should really have the same
>> method names as their JDK8 counterparts.
> That would make it difficult that users can distinguish between them,
once JDK8 is under the hood. Why this should a good idea, my experience
says that naming things differently is not a bad thing, if they are the
same the will be easily confused. Are there explicit criterias, why it
should be better to name them the same, but in a different packages...?
>> MoneyCurrency.withCacheRounding() method name is incorrect Cache ->
>> Cash. Cache/no-cache isn't generally an exposed aspect of design.
>> The main class is Money, yet the unsigned version is
>> UnsignedMonetaryAmount. UnsignedMoney would b better. The real
>> question is whether unsigned vs signed is a distinction for runtime or
>> compile time.
> UnsignedMonetaryAmount is not anymore part of the API. There is a
singleton factory class ConstraintMonetaryAmount, which allows to create
MonetaryAmounts that ensure a Predicate is true, after each operation
returning an amount as result. Creating an unsigned amount is also possible
by a separate factory method. Must check, if the spec is not up to date
It never was part of the API, but did it get moved from the RI to another
>> MoneyContext is not an appropriate part of the state of a money
>> object. The concept of money consists only of a number and a currency.
> If we would leave open, how implementations would serialize, this is not
necessary to define in more detail...? We can specify that both the
currency and the numeric part have to be serialized, but leave open how
>> Money.equals() is ill-defined. For example, is 2.0 equal to 2.00? What
>> about MathContext?
That is a problem of Java and in this special case BigDecimal. E.g. new
Integer(2) is not equal to new BigInteger(2) and if you look at some of the
unit tests, there is great sensitivity of MathContext or whether you even
construct BD values with double, float or int primitives.
> The current spec defines that in SE both numeric parts must be converted
to BD, which then is tested for equality (with all advantages/disadvantages
of using BD), beside the currencies, of course.
> Adding the MathContext may be not easy, since one of the numeric types,
might not be able to fullfill the precision required...
> So basically, we should at the end finally discuss, if its not better, to
drop interoperability for different numeric implementation types. With the
ability to extract a BD and create new amounts, we could delegate the
clients the burden of bridging between different implementation types, if
they really have to mix types... WDYT?
>> Money.of() does not specify how numbers are converted to BigDecimal.
>> There are two different Double to BigDecimal conversions for example.
> How this is best done, from your experience?
> 1) checking if Number type == BD;
> 2) Checking if Number == BigInteger
> 3) Checking if numbers scale==0 -> extract long value,
> 4) extract to a double
> 5) create a BD with the extacted value (for 2-4)
>> MoneyFunctions/MoneyRoundings don't give examples of their expected use.
> OK, will add some examples.
>> This is just a high level review of the core of the API. I'm not
>> repeating broader comments where I disagree with the style and
>> approach in general.
> Thanks, Anatole
>> On 20 September 2013 19:30, Anatole Tresch <atsticks@...> wrote:
>> > Hi all
>> > I now have gone through almost every Javadoc class description and
>> > I catched up everything that was missing, especially documentations
>> > thread safety, immutability etc.
>> > It could still be that there is something missing, but from my side, I
>> > think, we have a state, that we now can show to the public.
>> > I want to ask you (EVERYBODY please), to have a look into the attached
>> > JavaDoc and source code repo, and really give FAST feedback, so we
>> > forward it for publishing again.
>> > Feedback deadline will be 16:00 MET tomorrow 21th September.
>> > Regards,
>> > Anatole
>> > --
>> > Anatole Tresch
>> > Java Lead Engineer, JSR Spec Lead
>> > Glärnischweg 10
>> > CH - 8620 Wetzikon
>> > Switzerland, Europe Zurich, GMT+1
>> > Twitter: @atsticks
>> > Blogs: http://javaremarkables.blogspot.ch/
>> > Google: atsticks
>> > Mobile +41-76 344 62 79
> Anatole Tresch
> Java Lead Engineer, JSR Spec Lead
> Glärnischweg 10
> CH - 8620 Wetzikon
> Switzerland, Europe Zurich, GMT+1
> Twitter: @atsticks
> Blogs: http://javaremarkables.blogspot.ch/
> Google: atsticks
> Mobile +41-76 344 62 79