[JSR-354] Re: JSR API und Javadoc Updates
- From: Anatole Tresch <atsticks@...>
- To: Jsr 354 JavaMoney Public Mailinglist <jcurrency_mail@...>
- Subject: [JSR-354] Re: JSR API und Javadoc Updates
- Date: Mon, 23 Sep 2013 06:01:35 +0200
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?*
> 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).*
> 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
> 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?
*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.
> 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 about
> > 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 Harold
> > 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
Java Lead Engineer, JSR Spec Lead
CH - 8620 Wetzikon
*Switzerland, Europe Zurich, GMT+1*
Mobile +41-76 344 62 79*