public interface MonetaryAmount extends CurrencySupplier, NumberSupplier, 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:
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.
MonetaryAmount
.NumberValue.numberValue(Class)
, whereas the exact counterpart,
NumberValue.numberValueExact(Class)
, works similar to
BigDecimal.longValueExact()
.
with(MonetaryOperator)
must be of the same type as
type on which with
was called. The with
method also defines additional
interoperability requirements that are important to enable this invariant.from(MonetaryAmount)
is
recommended to be implemented on each implementation class, that allows conversion of a
MonetaryAmount
to a concrete instance. E.g.a class MyMoney extends MonetaryAmount
would contain the following method:
public final class MyMoney implements MonetaryAmount{ ... public static MyMoney from(MonetaryAmount amount)(...) }
MonetaryContext
and a serialized
CurrencyUnit
.equals/hashCode
, hereby considering
with(MonetaryOperator)
Modifier and Type  Method and Description 

MonetaryAmount 
abs()
Returns a
MonetaryAmount whose value is the absolute value of this
MonetaryAmount , and whose scale is this.scale() . 
MonetaryAmount 
add(MonetaryAmount amount)
Returns a
MonetaryAmount whose value is this + amount , and whose scale is max(this.scale(),
amount.scale() . 
MonetaryAmount 
divide(double divisor)
Returns a
MonetaryAmount whose value is this /
divisor , and whose preferred scale is this.scale() 
divisor.scale() ; if the exact quotient cannot be represented an ArithmeticException
is thrown. 
MonetaryAmount 
divide(long divisor)
Returns a
MonetaryAmount whose value is this /
divisor , and whose preferred scale is this.scale() 
divisor.scale() ; if the exact quotient cannot be represented an ArithmeticException
is thrown. 
MonetaryAmount 
divide(Number divisor)
Returns a
MonetaryAmount whose value is this /
divisor , and whose preferred scale is this.scale() 
divisor.scale() ; if the exact quotient cannot be represented an ArithmeticException
is thrown. 
MonetaryAmount[] 
divideAndRemainder(double divisor)
Returns a twoelement
MonetaryAmount array containing the result of
divideToIntegralValue followed by the result of remainder on the two
operands. 
MonetaryAmount[] 
divideAndRemainder(long divisor)
Returns a twoelement
MonetaryAmount array containing the result of
divideToIntegralValue followed by the result of remainder on the two
operands. 
MonetaryAmount[] 
divideAndRemainder(Number divisor)
Returns a twoelement
MonetaryAmount array containing the result of
divideToIntegralValue followed by the result of remainder on the two
operands. 
MonetaryAmount 
divideToIntegralValue(double divisor)
Returns a
MonetaryAmount whose value is the integer part of the quotient
this / divisor rounded down. 
MonetaryAmount 
divideToIntegralValue(long divisor)
Returns a
MonetaryAmount whose value is the integer part of the quotient
this / divisor rounded down. 
MonetaryAmount 
divideToIntegralValue(Number divisor)
Returns a
MonetaryAmount whose value is the integer part of the quotient
this / divisor rounded down. 
MonetaryContext 
getContext()
Returns the
MonetaryContext of this MonetaryAmount . 
MonetaryAmountFactory<? extends MonetaryAmount> 
getFactory()
Creates a new
MonetaryAmountFactory , returning the same implementation type Hereby
this given amount is used as a template, so reusing the CurrencyUnit , its numeric
value, the algorithmic implementation as well as the current MonetaryContext . 
boolean 
isEqualTo(MonetaryAmount amount)
Compares two instances of
MonetaryAmount , hereby ignoring non significant trailing
zeroes and different numeric capabilities. 
boolean 
isGreaterThan(MonetaryAmount amount)
Compares two instances of
MonetaryAmount , hereby ignoring non significant trailing
zeroes and different numeric capabilities. 
boolean 
isGreaterThanOrEqualTo(MonetaryAmount amount)
Compares two instances of
MonetaryAmount , hereby ignoring non significant trailing
zeroes and different numeric capabilities. 
boolean 
isLessThan(MonetaryAmount amount)
Compares two instances of
MonetaryAmount , hereby ignoring non significant trailing
zeroes and different numeric capabilities. 
boolean 
isLessThanOrEqualTo(MonetaryAmount amt)
Compares two instances of
MonetaryAmount , hereby ignoring non significant trailing
zeroes and different numeric capabilities. 
default boolean 
isNegative()
Checks if a
MonetaryAmount is negative. 
default boolean 
isNegativeOrZero()
Checks if a
MonetaryAmount is negative or zero. 
default boolean 
isPositive()
Checks if a
MonetaryAmount is positive. 
default boolean 
isPositiveOrZero()
Checks if a
MonetaryAmount is positive or zero. 
default boolean 
isZero()
Checks if an
MonetaryAmount is zero. 
MonetaryAmount 
multiply(double multiplicand)
Returns a
MonetaryAmount whose value is (this ×
multiplicand), and whose scale is this.scale() +
multiplicand.scale() . 
MonetaryAmount 
multiply(long multiplicand)
Returns a
MonetaryAmount whose value is (this ×
multiplicand), and whose scale is this.scale() +
multiplicand.scale() . 
MonetaryAmount 
multiply(Number multiplicand)
Returns a
MonetaryAmount whose value is (this ×
multiplicand), and whose scale is this.scale() +
multiplicand.scale() . 
MonetaryAmount 
negate()
Returns a
MonetaryAmount whose value is this , and whose scale is
this.scale() . 
MonetaryAmount 
plus()
Returns a
MonetaryAmount whose value is +this , with rounding according to
the context settings. 
default <R> R 
query(MonetaryQuery<R> query)
Queries this monetary amount for a value.

MonetaryAmount 
remainder(double divisor)
Returns a
MonetaryAmount whose value is this % divisor . 
MonetaryAmount 
remainder(long divisor)
Returns a
MonetaryAmount whose value is this % divisor . 
MonetaryAmount 
remainder(Number divisor)
Returns a
MonetaryAmount whose value is this % divisor . 
MonetaryAmount 
scaleByPowerOfTen(int power)
Returns a
MonetaryAmount whose numerical value is equal to ( this *
10^{n}). 
int 
signum()
Returns the signum function of this
MonetaryAmount . 
MonetaryAmount 
stripTrailingZeros()
Returns a
MonetaryAmount which is numerically equal to this one but with any trailing
zeros removed from the representation. 
MonetaryAmount 
subtract(MonetaryAmount amount)
Returns a
MonetaryAmount whose value is this 
amount , and whose scale is max(this.scale(),
subtrahend.scale() . 
default MonetaryAmount 
with(MonetaryOperator operator)
Returns an operated object of the same type as this object with the operation made.

getCurrency
getNumber
compareTo
MonetaryContext getContext()
MonetaryContext
of this MonetaryAmount
. The
MonetaryContext
provides additional information about the numeric representation and
the numeric capabilities. This information can be used by code to determine situations where
MonetaryAmount
instances must be converted to avoid implicit truncation, which can
lead to invalid results.MonetaryContext
of this MonetaryAmount
, never null
.default <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 readonly method is invoked.
R
 the type of the resultquery
 the query to invoke, not nulldefault MonetaryAmount with(MonetaryOperator operator)
MonetaryAmountFactory
instances:
// converting from Money to MyMoney Money m = ...; MonetartyAmountFactoryf = 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){ ... } ... }
operator
 the operator to use, not nullMonetaryAmountFactory<? extends MonetaryAmount> getFactory()
MonetaryAmountFactory
, returning the same implementation type Hereby
this given amount is used as a template, so reusing the CurrencyUnit
, its numeric
value, the algorithmic implementation as well as the current MonetaryContext
.
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.
MonetaryAmountFactory
with the given MonetaryAmount
as its
default values.boolean isGreaterThan(MonetaryAmount amount)
MonetaryAmount
, hereby ignoring non significant trailing
zeroes and different numeric capabilities.amount
 the MonetaryAmount
to be compared with this instance.true
if amount > this
.MonetaryException
 if the amount's currency is not equals to the currency of this instance.boolean isGreaterThanOrEqualTo(MonetaryAmount amount)
MonetaryAmount
, hereby ignoring non significant trailing
zeroes and different numeric capabilities.amount
 the MonetaryAmount
to be compared with this instance.true
if amount >= this
.MonetaryException
 if the amount's currency is not equals to the currency of this instance.boolean isLessThan(MonetaryAmount amount)
MonetaryAmount
, hereby ignoring non significant trailing
zeroes and different numeric capabilities.amount
 the MonetaryAmount
to be compared with this instance.true
if amount < this
.MonetaryException
 if the amount's currency is not equals to the currency of this instance.boolean isLessThanOrEqualTo(MonetaryAmount amt)
MonetaryAmount
, hereby ignoring non significant trailing
zeroes and different numeric capabilities.amt
 the MonetaryAmount
to be compared with this instance.true
if amount <= this
.MonetaryException
 if the amount's currency is not equals to the currency of this instance.boolean isEqualTo(MonetaryAmount amount)
MonetaryAmount
, hereby ignoring non significant trailing
zeroes and different numeric capabilities.amount
 the MonetaryAmount
to be compared with this instance.true
if amount == this
.MonetaryException
 if the amount's currency is not equals to the currency of this instance.default boolean isNegative()
MonetaryAmount
is negative.true
if signum()
< 0.default boolean isNegativeOrZero()
MonetaryAmount
is negative or zero.true
if signum()
<= 0.default boolean isPositive()
MonetaryAmount
is positive.true
if signum()
> 0.default boolean isPositiveOrZero()
MonetaryAmount
is positive or zero.true
if signum()
>= 0.default boolean isZero()
MonetaryAmount
is zero.true
if signum()
== 0.int signum()
MonetaryAmount
.MonetaryAmount
is negative, zero, or
positive.MonetaryAmount add(MonetaryAmount amount)
MonetaryAmount
whose value is this + amount
, and whose scale is max(this.scale(),
amount.scale()
.amount
 value to be added to this MonetaryAmount
.this + amount
ArithmeticException
 if the result exceeds the numeric capabilities of this implementation class, i.e.
the MonetaryContext
cannot be adapted as required.MonetaryAmount subtract(MonetaryAmount amount)
MonetaryAmount
whose value is this 
amount
, and whose scale is max(this.scale(),
subtrahend.scale()
.amount
 value to be subtracted from this MonetaryAmount
.this  amount
ArithmeticException
 if the result exceeds the numeric capabilities of this implementation class, i.e.
the MonetaryContext
cannot be adapted as required.MonetaryAmount multiply(long multiplicand)
MonetaryAmount
whose value is (this ×
multiplicand), and whose scale is this.scale() +
multiplicand.scale()
.multiplicand
 value to be multiplied by this MonetaryAmount
.this * multiplicand
ArithmeticException
 if the result exceeds the numeric capabilities of this implementation class, i.e.
the MonetaryContext
cannot be adapted as required.MonetaryAmount multiply(double multiplicand)
MonetaryAmount
whose value is (this ×
multiplicand), and whose scale is this.scale() +
multiplicand.scale()
.
By default the input value's scale will be rounded to
accommodate the format capabilities, and no ArithmeticException
is thrown if the input number's scale exceeds the capabilities.multiplicand
 value to be multiplied by this MonetaryAmount
. If the multiplicand's scale exceeds
the
capabilities of the implementation, it may be rounded implicitly.this * multiplicand
ArithmeticException
 if the result exceeds the numeric capabilities of this implementation class, i.e.
the MonetaryContext
cannot be adapted as required.MonetaryAmount multiply(Number multiplicand)
MonetaryAmount
whose value is (this ×
multiplicand), and whose scale is this.scale() +
multiplicand.scale()
.multiplicand
 value to be multiplied by this MonetaryAmount
. If the multiplicand's scale exceeds
the
capabilities of the implementation, it may be rounded implicitly.this * multiplicand
ArithmeticException
 if the result exceeds the numeric capabilities of this implementation class, i.e.
the MonetaryContext
cannot be adapted as required.MonetaryAmount divide(long divisor)
MonetaryAmount
whose value is this /
divisor
, and whose preferred scale is this.scale() 
divisor.scale()
; if the exact quotient cannot be represented an ArithmeticException
is thrown.divisor
 value by which this MonetaryAmount
is to be divided.this / divisor
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. the
MonetaryContext
cannot be adapted as required.MonetaryAmount divide(double divisor)
MonetaryAmount
whose value is this /
divisor
, and whose preferred scale is this.scale() 
divisor.scale()
; if the exact quotient cannot be represented an ArithmeticException
is thrown.divisor
 value by which this MonetaryAmount
is to be divided.this / divisor
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. the
MonetaryContext
cannot be adapted as required.MonetaryAmount divide(Number divisor)
MonetaryAmount
whose value is this /
divisor
, and whose preferred scale is this.scale() 
divisor.scale()
; if the exact quotient cannot be represented an ArithmeticException
is thrown.divisor
 value by which this MonetaryAmount
is to be divided.this / divisor
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. the
MonetaryContext
cannot be adapted as required.MonetaryAmount remainder(long divisor)
MonetaryAmount
whose value is this % 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).
divisor
 value by which this MonetaryAmount
is to be divided.this % divisor
.ArithmeticException
 if divisor==0
, or if the result exceeds the numeric capabilities of this
implementation class, i.e. the MonetaryContext
cannot be adapted as
required.MonetaryAmount remainder(double divisor)
MonetaryAmount
whose value is this % 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).
divisor
 value by which this MonetaryAmount
is to be divided.this % divisor
.ArithmeticException
 if divisor==0
, or if the result exceeds the numeric capabilities of this
implementation class, i.e. the MonetaryContext
cannot be adapted as
required.MonetaryAmount remainder(Number divisor)
MonetaryAmount
whose value is this % 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).
divisor
 value by which this MonetaryAmount
is to be divided.this % divisor
.ArithmeticException
 if divisor==0
, or if the result exceeds the numeric capabilities of this
implementation class, i.e. the MonetaryContext
cannot be adapted as
required.MonetaryAmount[] divideAndRemainder(long divisor)
MonetaryAmount
array containing the result of
divideToIntegralValue
followed by the result of remainder
on the two
operands.
Note that if both the integer quotient and remainder are needed, this method is faster than
using the divideToIntegralValue
and remainder
methods separately because the
division need only be carried out once.
divisor
 value by which this MonetaryAmount
is to be divided, and the remainder
computed.MonetaryAmount
array: the quotient (the result of
divideToIntegralValue
) is the initial element and the remainder is the final
element.ArithmeticException
 if divisor==0
, or if the result exceeds the numeric capabilities of this
implementation class, i.e. the MonetaryContext
cannot be adapted as
required.divideToIntegralValue(long)
,
remainder(long)
MonetaryAmount[] divideAndRemainder(double divisor)
MonetaryAmount
array containing the result of
divideToIntegralValue
followed by the result of remainder
on the two
operands.
Note that if both the integer quotient and remainder are needed, this method is faster than
using the divideToIntegralValue
and remainder
methods separately because the
division need only be carried out once.
divisor
 value by which this MonetaryAmount
is to be divided, and the remainder
computed.MonetaryAmount
array: the quotient (the result of
divideToIntegralValue
) is the initial element and the remainder is the final
element.ArithmeticException
 if divisor==0
, or if the result exceeds the numeric capabilities of this
implementation class, i.e. the MonetaryContext
cannot be adapted as
required.divideToIntegralValue(double)
,
remainder(double)
MonetaryAmount[] divideAndRemainder(Number divisor)
MonetaryAmount
array containing the result of
divideToIntegralValue
followed by the result of remainder
on the two
operands.
Note that if both the integer quotient and remainder are needed, this method is faster than
using the divideToIntegralValue
and remainder
methods separately because the
division need only be carried out once.
divisor
 value by which this MonetaryAmount
is to be divided, and the remainder
computed.MonetaryAmount
array: the quotient (the result of
divideToIntegralValue
) is the initial element and the remainder is the final
element.ArithmeticException
 if divisor==0
, or if the result exceeds the numeric capabilities of this
implementation class, i.e. the MonetaryContext
cannot be adapted as
required.divideToIntegralValue(Number)
,
remainder(Number)
MonetaryAmount divideToIntegralValue(long divisor)
MonetaryAmount
whose value is the integer part of the quotient
this / divisor
rounded down. The preferred scale of the result is
this.scale() 
divisor.scale()
.divisor
 value by which this BigDecimal
is to be divided.this / divisor
.ArithmeticException
 if divisor==0
BigDecimal.divideToIntegralValue(java.math.BigDecimal)
MonetaryAmount divideToIntegralValue(double divisor)
MonetaryAmount
whose value is the integer part of the quotient
this / divisor
rounded down. The preferred scale of the result is
this.scale()  divisor.scale()
.divisor
 value by which this BigDecimal
is to be divided.this / divisor
.ArithmeticException
 if divisor==0
BigDecimal.divideToIntegralValue(java.math.BigDecimal)
MonetaryAmount divideToIntegralValue(Number divisor)
MonetaryAmount
whose value is the integer part of the quotient
this / divisor
rounded down. The preferred scale of the result is
this.scale() 
divisor.scale()
.divisor
 value by which this BigDecimal
is to be divided.this / divisor
.ArithmeticException
 if divisor==0
BigDecimal.divideToIntegralValue(java.math.BigDecimal)
MonetaryAmount scaleByPowerOfTen(int power)
MonetaryAmount
whose numerical value is equal to ( this
*
10^{n}). The scale of the result is this.scale()  n
.power
 the power.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. the
MonetaryContext
cannot be adapted as required.MonetaryAmount abs()
MonetaryAmount
whose value is the absolute value of this
MonetaryAmount
, and whose scale is this.scale()
.abs(this
MonetaryAmount negate()
MonetaryAmount
whose value is this
, and whose scale is
this.scale()
.this
.MonetaryAmount plus()
MonetaryAmount
whose value is +this
, with rounding according to
the context settings.this
, rounded as necessary. A zero result will have a scale of 0.ArithmeticException
 if rounding fails.BigDecimal.plus()
MonetaryAmount stripTrailingZeros()
MonetaryAmount
which is numerically equal to this one but with any trailing
zeros removed from the representation. For example, stripping the trailing zeros from the
MonetaryAmount
value CHF 600.0
, which has [BigInteger
, scale
]
components equals to [6000, 1], yields 6E2
with [ BigInteger
, scale
]
components equals to [6, 2]MonetaryAmount
with any trailing zeros removed.Copyright © 2012–2016 JSR 354  Expert Group. All rights reserved.