 All Superinterfaces:
java.lang.Comparable<MonetaryAmount>
,CurrencySupplier
,NumberSupplier
public interface MonetaryAmount extends CurrencySupplier, NumberSupplier, java.lang.Comparable<MonetaryAmount>
Each instance of an amount provides additional metadata in form of a MonetaryContext
.
This context contains detailed information on the numeric capabilities, e.g. the supported
precision and maximal scale, as well as the common implementation flavor.
Also a MonetaryAmount
provides a NumberValue
, which allows easily to extract the
numeric value, of the amount. And finally getFactory()
provides a
MonetaryAmountFactory
, which allows to of instances of MonetaryAmount
based
on the same numeric implementation.
This JSR additionally recommends to consider the following aspects:
 Arithmetic operations should throw an
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 format rounding, as required by the format numeric representation of a monetary amount.  Monetary amounts should allow numbers as argument for arithmetic operations like division and
multiplication. Adding or subtracting of amounts must only be possible by passing instances of
MonetaryAmount
.  Nevertheless numeric truncation is also explicitly supported when calling
NumberValue.numberValue(Class)
, whereas the exact counterpart,NumberValue.numberValueExact(Class)
, works similar toBigDecimal.longValueExact()
.  Since implementations are recommended to be immutable, an operation should never change any format state of an instance. Given an instance, all operations are required to be fully reproducible.
 Finally the result of calling
with(MonetaryOperator)
must be of the same type as type on whichwith
was called. Thewith
method also defines additional interoperability requirements that are important to enable this invariant.  To enable further interoperability a static method
from(MonetaryAmount)
is recommended to be implemented on each implementation class, that allows conversion of aMonetaryAmount
to a concrete instance. E.g.a classMyMoney extends MonetaryAmount
would contain the following method:public final class MyMoney implements MonetaryAmount{ ... public static MyMoney from(MonetaryAmount amount)(...) }
Implementation specification
Implementations of this interface must be threadsafe
 final
 serializable, hereby writing the numeric value, the
MonetaryContext
and a serializedCurrencyUnit
.
 threadsafe
 immutable
 comparable
 must implement
equals/hashCode
, hereby considering Implementation type
 CurrencyUnit
 Numeric value.
 Version:
 1.1
 Author:
 Anatole Tresch, Werner Keil
 See Also:
with(MonetaryOperator)

Method Summary
Modifier and Type Method Description MonetaryAmount
abs()
Returns aMonetaryAmount
whose value is the absolute value of thisMonetaryAmount
, and whose scale isthis.getContext().getMaxScale()
.MonetaryAmount
add(MonetaryAmount augend)
Returns aMonetaryAmount
whose value isthis + augend
, and whose scale ismax(this.getContext().getMaxScale(), augend.getContext().getMaxScale())
.MonetaryAmount
divide(double divisor)
Returns aMonetaryAmount
whose value isthis / divisor
, and whose preferred scale isthis.getContext().getMaxScale()  divisor.getContext().getMaxScale()
; if the exact quotient cannot be represented anArithmeticException
is thrown.MonetaryAmount
divide(long divisor)
Returns aMonetaryAmount
whose value isthis / divisor
, and whose preferred scale isthis.getContext().getMaxScale()  divisor.getContext().getMaxScale()
; if the exact quotient cannot be represented anArithmeticException
is thrown.MonetaryAmount
divide(java.lang.Number divisor)
Returns aMonetaryAmount
whose value isthis / divisor
, and whose preferred scale isthis.getContext().getMaxScale()  divisor.getContext().getMaxScale()
; if the exact quotient cannot be represented anArithmeticException
is thrown.MonetaryAmount[]
divideAndRemainder(double divisor)
Returns a twoelementMonetaryAmount
array containing the result ofdivideToIntegralValue
followed by the result ofremainder
on the two operands.MonetaryAmount[]
divideAndRemainder(long divisor)
Returns a twoelementMonetaryAmount
array containing the result ofdivideToIntegralValue
followed by the result ofremainder
on the two operands.MonetaryAmount[]
divideAndRemainder(java.lang.Number divisor)
Returns a twoelementMonetaryAmount
array containing the result ofdivideToIntegralValue
followed by the result ofremainder
on the two operands.MonetaryAmount
divideToIntegralValue(double divisor)
Returns aMonetaryAmount
whose value is the integer part of the quotientthis / divisor
rounded down.MonetaryAmount
divideToIntegralValue(long divisor)
Returns aMonetaryAmount
whose value is the integer part of the quotientthis / divisor
rounded down.MonetaryAmount
divideToIntegralValue(java.lang.Number divisor)
Returns aMonetaryAmount
whose value is the integer part of the quotientthis / divisor
rounded down.MonetaryContext
getContext()
Returns theMonetaryContext
of thisMonetaryAmount
.MonetaryAmountFactory<? extends MonetaryAmount>
getFactory()
Creates a newMonetaryAmountFactory
, returning the same implementation type Hereby this given amount is used as a template, so reusing theCurrencyUnit
, its numeric value, the algorithmic implementation as well as the currentMonetaryContext
.boolean
isEqualTo(MonetaryAmount amount)
Compares two instances ofMonetaryAmount
, hereby ignoring non significant trailing zeroes and different numeric capabilities.boolean
isGreaterThan(MonetaryAmount amount)
Compares two instances ofMonetaryAmount
, hereby ignoring non significant trailing zeroes and different numeric capabilities.boolean
isGreaterThanOrEqualTo(MonetaryAmount amount)
Compares two instances ofMonetaryAmount
, hereby ignoring non significant trailing zeroes and different numeric capabilities.boolean
isLessThan(MonetaryAmount amount)
Compares two instances ofMonetaryAmount
, hereby ignoring non significant trailing zeroes and different numeric capabilities.boolean
isLessThanOrEqualTo(MonetaryAmount amt)
Compares two instances ofMonetaryAmount
, hereby ignoring non significant trailing zeroes and different numeric capabilities.default boolean
isNegative()
Checks if aMonetaryAmount
is negative.default boolean
isNegativeOrZero()
Checks if aMonetaryAmount
is negative or zero.default boolean
isPositive()
Checks if aMonetaryAmount
is positive.default boolean
isPositiveOrZero()
Checks if aMonetaryAmount
is positive or zero.default boolean
isZero()
Checks if anMonetaryAmount
is zero.MonetaryAmount
multiply(double multiplicand)
Returns aMonetaryAmount
whose value is(this × multiplicand)
, and whose scale isthis.getContext().getMaxScale() + multiplicand.getContext().getMaxScale()
.MonetaryAmount
multiply(long multiplicand)
Returns aMonetaryAmount
whose value is(this × multiplicand)
, and whose scale isthis.getContext().getMaxScale() + multiplicand.getContext().getMaxScale()
.MonetaryAmount
multiply(java.lang.Number multiplicand)
Returns aMonetaryAmount
whose value is(this × multiplicand)
, and whose scale isthis.getContext().getMaxScale() + multiplicand.getContext().getMaxScale()
.MonetaryAmount
negate()
Returns aMonetaryAmount
whose value isthis
, and whose scale isthis.getContext().getMaxScale()
, with rounding according to the context settings.MonetaryAmount
plus()
Returns aMonetaryAmount
whose value is+this
.default <R> R
query(MonetaryQuery<R> query)
Queries this monetary amount for a value.MonetaryAmount
remainder(double divisor)
Returns aMonetaryAmount
whose value isthis % divisor
.MonetaryAmount
remainder(long divisor)
Returns aMonetaryAmount
whose value isthis % divisor
.MonetaryAmount
remainder(java.lang.Number divisor)
Returns aMonetaryAmount
whose value isthis % divisor
.MonetaryAmount
scaleByPowerOfTen(int power)
Returns aMonetaryAmount
whose numerical value is equal to (this
* 10^{n}).int
signum()
Returns the signum function of thisMonetaryAmount
.MonetaryAmount
stripTrailingZeros()
Returns aMonetaryAmount
which is numerically equal to this one but with any trailing zeros removed from the representation.MonetaryAmount
subtract(MonetaryAmount subtrahend)
Returns aMonetaryAmount
whose value isthis  amount
, and whose scale ismax(this.getContext().getMaxScale(), subtrahend.getContext().getMaxScale()
.default MonetaryAmount
with(MonetaryOperator operator)
Returns an operated object of the same type as this object with the operation made.

Method Details

getContext
MonetaryContext getContext()Returns theMonetaryContext
of thisMonetaryAmount
. TheMonetaryContext
provides additional information about the numeric representation and the numeric capabilities. This information can be used by code to determine situations whereMonetaryAmount
instances must be converted to avoid implicit truncation, which can lead to invalid results. Returns:
 the
MonetaryContext
of thisMonetaryAmount
, nevernull
.

query
Queries this monetary amount for a value.This queries this amount using the specified query strategy object.
Implementations must ensure that no observable state is altered when this readonly method is invoked.
 Type Parameters:
R
 the type of the result Parameters:
query
 the query to invoke, not null Returns:
 the query result, null may be returned (defined by the query)

with
Returns an operated object of the same type as this object with the operation made. Hereby returning an instance of the same type is very important to prevent uncontrolled mixup of implementations. Switching between implementations is still easily possible, e.g. by using accordingMonetaryAmountFactory
instances:// converting from Money to MyMoney Money m = ...; MonetartyAmountFactory<MyMoney> f = Monetary.queryAmountFactory(MyMoney.class); MyMoney myMoney = f.setAmount(m).of();
This converts this monetary amount according to the rules of the specified operator. A typical operator will change the amount and leave the currency unchanged. A more complex operator might also change the currency.
Some example code indicating how and why this method is used:
MonetaryAmount money = money.with(amountMultipliedBy(2)); money = money.with(amountRoundedToNearestWholeUnit());
Hereby also the method signature on the implementation type must return the concrete type, to enable a fluent API, e.g.
public final class MyMoney implements MonetaryAmount{ ... public MyMoney with(MonetaryOperator operator){ ... } ... }
 Parameters:
operator
 the operator to use, not null Returns:
 an object of the same type with the specified conversion made, not null

getFactory
MonetaryAmountFactory<? extends MonetaryAmount> getFactory()Creates a newMonetaryAmountFactory
, returning the same implementation type Hereby this given amount is used as a template, so reusing theCurrencyUnit
, its numeric value, the algorithmic implementation as well as the currentMonetaryContext
.This method is used for creating a new amount result after having done calculations that are not directly mappable to the default monetary arithmetics, e.g. currency conversion.
 Returns:
 the new
MonetaryAmountFactory
with the givenMonetaryAmount
as its default values.

isGreaterThan
Compares two instances ofMonetaryAmount
, hereby ignoring non significant trailing zeroes and different numeric capabilities. Parameters:
amount
 theMonetaryAmount
to be compared with this instance. Returns:
true
ifamount > this
. Throws:
MonetaryException
 if the amount's currency is not equal to the currency of this instance.

isGreaterThanOrEqualTo
Compares two instances ofMonetaryAmount
, hereby ignoring non significant trailing zeroes and different numeric capabilities. Parameters:
amount
 theMonetaryAmount
to be compared with this instance. Returns:
true
ifamount >= this
. Throws:
MonetaryException
 if the amount's currency is not equal to the currency of this instance.

isLessThan
Compares two instances ofMonetaryAmount
, hereby ignoring non significant trailing zeroes and different numeric capabilities. Parameters:
amount
 theMonetaryAmount
to be compared with this instance. Returns:
true
ifamount < this
. Throws:
MonetaryException
 if the amount's currency is not equal to the currency of this instance.

isLessThanOrEqualTo
Compares two instances ofMonetaryAmount
, hereby ignoring non significant trailing zeroes and different numeric capabilities. Parameters:
amt
 theMonetaryAmount
to be compared with this instance. Returns:
true
ifamount <= this
. Throws:
MonetaryException
 if the amount's currency is not equal to the currency of this instance.

isEqualTo
Compares two instances ofMonetaryAmount
, hereby ignoring non significant trailing zeroes and different numeric capabilities. Parameters:
amount
 theMonetaryAmount
to be compared with this instance. Returns:
true
ifamount == this
. Throws:
MonetaryException
 if the amount's currency is not equal to the currency of this instance.

isNegative
default boolean isNegative()Checks if aMonetaryAmount
is negative. Returns:
true
ifsignum()
< 0.

isNegativeOrZero
default boolean isNegativeOrZero()Checks if aMonetaryAmount
is negative or zero. Returns:
true
ifsignum()
<= 0.

isPositive
default boolean isPositive()Checks if aMonetaryAmount
is positive. Returns:
true
ifsignum()
> 0.

isPositiveOrZero
default boolean isPositiveOrZero()Checks if aMonetaryAmount
is positive or zero. Returns:
true
ifsignum()
>= 0.

isZero
default boolean isZero()Checks if anMonetaryAmount
is zero. Returns:
true
ifsignum()
== 0.

signum
int signum()Returns the signum function of thisMonetaryAmount
. Returns:
 1, 0, or 1 as the value of this
MonetaryAmount
is negative, zero, or positive.

add
Returns aMonetaryAmount
whose value isthis + augend
, and whose scale ismax(this.getContext().getMaxScale(), augend.getContext().getMaxScale())
. Parameters:
augend
 value to be added to thisMonetaryAmount
. Returns:
this + augend
 Throws:
java.lang.ArithmeticException
 if the result exceeds the numeric capabilities of this implementation class, i.e. theMonetaryContext
cannot be adapted as required.

subtract
Returns aMonetaryAmount
whose value isthis  amount
, and whose scale ismax(this.getContext().getMaxScale(), subtrahend.getContext().getMaxScale()
. Parameters:
subtrahend
 value to be subtracted from thisMonetaryAmount
. Returns:
this  subtrahend
 Throws:
java.lang.ArithmeticException
 if the result exceeds the numeric capabilities of this implementation class, i.e. theMonetaryContext
cannot be adapted as required.

multiply
Returns aMonetaryAmount
whose value is(this × multiplicand)
, and whose scale isthis.getContext().getMaxScale() + multiplicand.getContext().getMaxScale()
. Parameters:
multiplicand
 value to be multiplied by thisMonetaryAmount
. Returns:
this * multiplicand
 Throws:
java.lang.ArithmeticException
 if the result exceeds the numeric capabilities of this implementation class, i.e. theMonetaryContext
cannot be adapted as required.

multiply
Returns aMonetaryAmount
whose value is(this × multiplicand)
, and whose scale isthis.getContext().getMaxScale() + multiplicand.getContext().getMaxScale()
. By default the input value's scale will be rounded to accommodate the format capabilities, and noArithmeticException
is thrown if the input number's scale exceeds the capabilities. Parameters:
multiplicand
 value to be multiplied by thisMonetaryAmount
. If the multiplicand's scale exceeds the capabilities of the implementation, it may be rounded implicitly. Returns:
this * multiplicand
 Throws:
java.lang.ArithmeticException
 if the result exceeds the numeric capabilities of this implementation class, i.e. theMonetaryContext
cannot be adapted as required.

multiply
Returns aMonetaryAmount
whose value is(this × multiplicand)
, and whose scale isthis.getContext().getMaxScale() + multiplicand.getContext().getMaxScale()
. Parameters:
multiplicand
 value to be multiplied by thisMonetaryAmount
. If the multiplicand's scale exceeds the capabilities of the implementation, it may be rounded implicitly. Returns:
this * multiplicand
 Throws:
java.lang.ArithmeticException
 if the result exceeds the numeric capabilities of this implementation class, i.e. theMonetaryContext
cannot be adapted as required.

divide
Returns aMonetaryAmount
whose value isthis / divisor
, and whose preferred scale isthis.getContext().getMaxScale()  divisor.getContext().getMaxScale()
; if the exact quotient cannot be represented anArithmeticException
is thrown. Parameters:
divisor
 value by which thisMonetaryAmount
is to be divided. Returns:
this / divisor
 Throws:
java.lang.ArithmeticException
 if the exact quotient does not have a terminating decimal expansion, or if the result exceeds the numeric capabilities of this implementation class, i.e. theMonetaryContext
cannot be adapted as required.

divide
Returns aMonetaryAmount
whose value isthis / divisor
, and whose preferred scale isthis.getContext().getMaxScale()  divisor.getContext().getMaxScale()
; if the exact quotient cannot be represented anArithmeticException
is thrown. Parameters:
divisor
 value by which thisMonetaryAmount
is to be divided. Returns:
this / divisor
 Throws:
java.lang.ArithmeticException
 if the exact quotient does not have a terminating decimal expansion, or if the result exceeds the numeric capabilities of this implementation class, i.e. theMonetaryContext
cannot be adapted as required.

divide
Returns aMonetaryAmount
whose value isthis / divisor
, and whose preferred scale isthis.getContext().getMaxScale()  divisor.getContext().getMaxScale()
; if the exact quotient cannot be represented anArithmeticException
is thrown. Parameters:
divisor
 value by which thisMonetaryAmount
is to be divided. Returns:
this / divisor
 Throws:
java.lang.ArithmeticException
 if the exact quotient does not have a terminating decimal expansion, or if the result exceeds the numeric capabilities of this implementation class, i.e. theMonetaryContext
cannot be adapted as required.

remainder
Returns aMonetaryAmount
whose value isthis % divisor
.The remainder is given by
this.subtract(this.divideToIntegralValue(divisor).multiply(divisor)
. Note that this is not the modulo operation (the result can be negative). Parameters:
divisor
 value by which thisMonetaryAmount
is to be divided. Returns:
this % divisor
. Throws:
java.lang.ArithmeticException
 ifdivisor==0
, or if the result exceeds the numeric capabilities of this implementation class, i.e. theMonetaryContext
cannot be adapted as required.

remainder
Returns aMonetaryAmount
whose value isthis % divisor
.The remainder is given by
this.subtract(this.divideToIntegralValue(divisor).multiply(divisor)
. Note that this is not the modulo operation (the result can be negative). Parameters:
divisor
 value by which thisMonetaryAmount
is to be divided. Returns:
this % divisor
. Throws:
java.lang.ArithmeticException
 ifdivisor==0
, or if the result exceeds the numeric capabilities of this implementation class, i.e. theMonetaryContext
cannot be adapted as required.

remainder
Returns aMonetaryAmount
whose value isthis % divisor
.The remainder is given by
this.subtract(this.divideToIntegralValue(divisor).multiply(divisor)
. Note that this is not the modulo operation (the result can be negative). Parameters:
divisor
 value by which thisMonetaryAmount
is to be divided. Returns:
this % divisor
. Throws:
java.lang.ArithmeticException
 ifdivisor==0
, or if the result exceeds the numeric capabilities of this implementation class, i.e. theMonetaryContext
cannot be adapted as required.

divideAndRemainder
Returns a twoelementMonetaryAmount
array containing the result ofdivideToIntegralValue
followed by the result ofremainder
on the two operands.Note that if both the integer quotient and remainder are needed, this method is faster than using the
divideToIntegralValue
andremainder
methods separately because the division need only be carried out once. Parameters:
divisor
 value by which thisMonetaryAmount
is to be divided, and the remainder computed. Returns:
 a two element
MonetaryAmount
array: the quotient (the result ofdivideToIntegralValue
) is the initial element and the remainder is the final element.  Throws:
java.lang.ArithmeticException
 ifdivisor==0
, or if the result exceeds the numeric capabilities of this implementation class, i.e. theMonetaryContext
cannot be adapted as required. See Also:
divideToIntegralValue(long)
,remainder(long)

divideAndRemainder
Returns a twoelementMonetaryAmount
array containing the result ofdivideToIntegralValue
followed by the result ofremainder
on the two operands.Note that if both the integer quotient and remainder are needed, this method is faster than using the
divideToIntegralValue
andremainder
methods separately because the division need only be carried out once. Parameters:
divisor
 value by which thisMonetaryAmount
is to be divided, and the remainder computed. Returns:
 a two element
MonetaryAmount
array: the quotient (the result ofdivideToIntegralValue
) is the initial element and the remainder is the final element.  Throws:
java.lang.ArithmeticException
 ifdivisor==0
, or if the result exceeds the numeric capabilities of this implementation class, i.e. theMonetaryContext
cannot be adapted as required. See Also:
divideToIntegralValue(double)
,remainder(double)

divideAndRemainder
Returns a twoelementMonetaryAmount
array containing the result ofdivideToIntegralValue
followed by the result ofremainder
on the two operands.Note that if both the integer quotient and remainder are needed, this method is faster than using the
divideToIntegralValue
andremainder
methods separately because the division need only be carried out once. Parameters:
divisor
 value by which thisMonetaryAmount
is to be divided, and the remainder computed. Returns:
 a two element
MonetaryAmount
array: the quotient (the result ofdivideToIntegralValue
) is the initial element and the remainder is the final element.  Throws:
java.lang.ArithmeticException
 ifdivisor==0
, or if the result exceeds the numeric capabilities of this implementation class, i.e. theMonetaryContext
cannot be adapted as required. See Also:
divideToIntegralValue(Number)
,remainder(Number)

divideToIntegralValue
Returns aMonetaryAmount
whose value is the integer part of the quotientthis / divisor
rounded down. The preferred scale of the result isthis.getContext().getMaxScale()  divisor.getContext().getMaxScale()
. Parameters:
divisor
 value by which thisBigDecimal
is to be divided. Returns:
 The integer part of
this / divisor
.  Throws:
java.lang.ArithmeticException
 ifdivisor==0
 See Also:
BigDecimal.divideToIntegralValue(java.math.BigDecimal)

divideToIntegralValue
Returns aMonetaryAmount
whose value is the integer part of the quotientthis / divisor
rounded down. The preferred scale of the result isthis.getContext().getMaxScale()  divisor.getContext().getMaxScale()
. Parameters:
divisor
 value by which thisBigDecimal
is to be divided. Returns:
 The integer part of
this / divisor
.  Throws:
java.lang.ArithmeticException
 ifdivisor==0
 See Also:
BigDecimal.divideToIntegralValue(java.math.BigDecimal)

divideToIntegralValue
Returns aMonetaryAmount
whose value is the integer part of the quotientthis / divisor
rounded down. The preferred scale of the result isthis.getContext().getMaxScale()  divisor.getContext().getMaxScale()
. Parameters:
divisor
 value by which thisBigDecimal
is to be divided. Returns:
 The integer part of
this / divisor
.  Throws:
java.lang.ArithmeticException
 ifdivisor==0
 See Also:
BigDecimal.divideToIntegralValue(java.math.BigDecimal)

scaleByPowerOfTen
Returns aMonetaryAmount
whose numerical value is equal to (this
* 10^{n}). The scale of the result isthis.getContext().getMaxScale()  n
. Parameters:
power
 the power. Returns:
 the calculated amount value.
 Throws:
java.lang.ArithmeticException
 if the scale would be outside the range of a 32bit integer, or if the result exceeds the numeric capabilities of this implementation class, i.e. theMonetaryContext
cannot be adapted as required.

abs
MonetaryAmount abs()Returns aMonetaryAmount
whose value is the absolute value of thisMonetaryAmount
, and whose scale isthis.getContext().getMaxScale()
. Returns:
abs(this

negate
MonetaryAmount negate()Returns aMonetaryAmount
whose value isthis
, and whose scale isthis.getContext().getMaxScale()
, with rounding according to the context settings. Returns:
this
, rounded as necessary. Throws:
java.lang.ArithmeticException
 if rounding fails. See Also:
BigDecimal.negate()

plus
MonetaryAmount plus()Returns aMonetaryAmount
whose value is+this
.This method, which simply returns this
MonetaryAmount
is included for symmetry with the unary minus methodnegate()
. Returns:
this
. See Also:
negate()
,BigDecimal.plus()

stripTrailingZeros
MonetaryAmount stripTrailingZeros()Returns aMonetaryAmount
which is numerically equal to this one but with any trailing zeros removed from the representation. For example, stripping the trailing zeros from theMonetaryAmount
valueCHF 600.0
, which has [BigInteger
,scale
] components equals to [6000, 1], yields6E2
with [BigInteger
,scale
] components equals to [6, 2] Returns:
 a numerically equal
MonetaryAmount
with any trailing zeros removed.
