[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 09:41:09 +0200
Hi Stephen, all
the key points regarding serialization are the following:
according serialization the key issues, why we defined in more detail, what
should be done are the following::
1. Should there be subclasses, or not. For example, for CurrencyUnit,
the namespace and code appear sufficient to me, since it is an
identification object, and shouldn't in and of itself have other state or
2. Should it be a concrete class with subclasses, or an abstract class,
or an interface? Advantages and disadvantages to all of these.
3. When it is serialized, how is that done? The default Java
serialization is bloated, and causes misery for updating if you have to do
That were the reasons for defiining how serialization should be done.
Now we have discuss, how the serialization is exactly to be defined, e.g.
- CurrencyUnit: all fields as of now, or only namespace, code. If the
namespace/code is not defined on the receiving side, this might create a
IOException exception. Whereas serializing all fields, always makes it
possible to deserialize (when the impl class is there, of course).
- CurrencyNamespace: the id (String) (final API class)
- MonetaryAmount: a BigDecimal and the CurrencyUnit, nothing else.
- RegionType: the id (String), followed by other fields... (final API class)
- Region: RegionType, , followed by other fields...
- RegionTreeNode: node, parent, node children, linked Region
- ExchangeRateType: id (final API class)
- ExchangeRate: id and all fields as described as of now (is nevertheless a
final class, which is part of the API).
We might add in general an example link to the spec, how serialization
should be implemented in general. But in general following a clear
description in the Javadoc should be sufficient.
2013/9/23 Anatole Tresch <atsticks@...>
> Hi Stephen
> a few comments from my side -*inline *-, other comments from EG
> colleagues are welcome!
> 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.
> *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*
Java Lead Engineer, JSR Spec Lead
CH - 8620 Wetzikon
*Switzerland, Europe Zurich, GMT+1*
Mobile +41-76 344 62 79*