public interface MonetaryAmount
This JSR additionally recommends to consider the following aspects:
ArithmeticException
, if
performing arithmetic operations between amounts exceeds the capabilities of
the numeric representation type used. Any implicit truncating, that would
lead to complete invalid and useless results, should be avoided. This
recommendation does not affect internal rounding, as required by the internal
numeric representation of a monetary amount.
Number
should be avoided, since
it does not allow to extract its numeric value in a feasible way.MonetaryAmount
exceeds the
numeric capabilities of the concrete type T from(MonetaryAmount)
, an
implementation should throw an ArithemticOperationException
.ArithmeticException
should be thrown. Never should truncation be
performed implicitly.BigDecimal.longValueExact()
.
with(MonetaryAdjuster)
should be
of the same type as type on which with
was called. The with
method also defines additional interoperability requirements.from(MonetaryAmount)
is recommended to be implemented, that allows conversion of a
MonetaryAmount
to a concrete type T
:public static T from(MonetaryAmount amount);}This is particularly useful when implementing monetary adjusters or queries, since arithmetic operations are not available on the MonetaryAmount interface, which is defined for interoperability only.
getAmount()
. This methid is reserved for future integration into the JDK.CurrencyUnit
.equals/hashCode
, hereby considering
given w = getAmountWhole() n = getFractionNominator() d = getFractionDenominator() the following must be always true: !(w<0 && n>0) and !(w>0 && n<0) and d>0 and |n| < d // || = absolute value
Since Number
is not an interface, this type is not extending
Number
.
with(MonetaryAdjuster)
Modifier and Type | Method and Description |
---|---|
long |
getAmountFractionDenominator()
Gets the denominator of the fractional amount of the currency.
|
long |
getAmountFractionNumerator()
Gets the numerator of the fractional amount of the currency.
|
long |
getAmountWhole()
Gets the amount in terms of whole units of the currency.
|
CurrencyUnit |
getCurrency()
Returns the amount’s currency, modelled as
CurrencyUnit . |
<R> R |
query(MonetaryQuery<R> query)
Queries this monetary amount for a value.
|
MonetaryAmount |
with(MonetaryAdjuster adjuster)
Returns an adjusted object of the same type as this object with
the adjustment made.
|
CurrencyUnit getCurrency()
CurrencyUnit
.
Implementations may co-variantly change the return type to a more
specific implementation of CurrencyUnit
if desired.null
long getAmountWhole()
An amount is defined to consist of an amount of whole currency units plus a fraction of the unit. This method returns the amount of whole units, such as the number of complete US dollars represented.
For example, the amount of '12 dollars and 25 cents' would return 12 from this method, as there are 12 whole US dollars in the amount.
Hereby it is always required that
!(amountWhole<0 && fractionNumerator > 0)
!(amountWhole>0 && fractionNumerator < 0)
long getAmountFractionNumerator()
An amount is defined to consist of an amount of whole currency units plus a fraction of the unit. This method returns the numerator of the fraction of the whole currency unit.
For example, the amount of '12 dollars and 25 cents' would typically return 25 from this method and 100 from the denominator method.
Hereby it is always required that
fractionNumerator < fractionDenominator
long getAmountFractionDenominator()
An amount is defined to consist of an amount of whole currency units plus a fraction of the unit. This method returns the denominator of the fraction of the whole currency unit.
For example, the amount of '12 dollars and 25 cents' would typically return 100 from this method and 25 from the numerator method.
Hereby it is always required that
fractionDenominator > 0
.
fractionDenominator > abs(fractionNominator)
.
<R> R query(MonetaryQuery<R> query)
This queries this amount using the specified query strategy object.
Implementations must ensure that no observable state is altered when this read-only method is invoked.
R
- the type of the resultadjuster
- the query to invoke, not nullMonetaryAmount with(MonetaryAdjuster adjuster)
This adjusts this monetary amount according to the rules of the specified adjuster. A typical adjuster will change the amount and leave the currency unchanged. A more complex adjuster might also change the currency.
Some example code indicating how and why this method is used:
money = money.with(amountMultipliedBy(2)); date = date.with(amountRoundedToNearestWholeUnit());Hereby also the method signatur on the implementation type must return the concrete type, to enable a fluent API, e.g.
public final class MM implements MonetaryAmount{ ... public MM with(MonetaryAdjuster adjuster){ ... } ... }
adjuster
- the adjuster to use, not nullCopyright © 2012–2013 JSR 354 - Expert Group. All rights reserved.