Moneta (JSR 354 RI) 1.4.5 · org.javamoney.moneta.convert.DefaultExchangeRate

This class models an exchange rate, which defines the factor the numeric value of a base amount in some currency 'A' must be multiplied to get the corresponding amount in the terminating currency 'B'. Hereby

an exchange rate always models one rate from a base (source) to a term (target) javax.money.CurrencyUnit.
an exchange rate is always bound to a rate type, which typically matches the data source of the conversion data, e.g. different credit card providers may use different rates for the same conversion.
an exchange rate may restrict its validity. In most of the use cases a rates' validity will be well defined, but it is also possible that the data provider is not able to support the rate's validity, leaving it undefined-
an exchange rate has a provider, which is responsible for defining the rate. A provider hereby may be, but must not be the same as the rate's data source.
an exchange rate can be a direct rate, where its factor is represented by a single conversion step. Or it can model a derived rate, where multiple conversion steps are required to define the overall base/term conversion. In case of derived rates the chained rates define the overall factor, by multiplying the individual chain rate factors. Of course, this also requires that each subsequent rate's base currency in the chain does match the previous term currency (and vice versa):
Whereas the factor should be directly implied by the format rate chain for derived rates, this is obviously not the case for the validity range, since rates can have a undefined validity range. Nevertheless in many cases also the validity range can (but must not) be derived from the rate chain.
Finally a conversion rate is always unidirectional. There might be cases where the reciprocal value of factor matches the correct reverse rate. But in most use cases the reverse rate either has a different rate (not equal to the reciprocal value), or might not be defined at all. Therefore for reversing a ExchangeRate one must access an javax.money.convert.ExchangeRateProvider and query for the reverse rate.

The class also implements Comparable to allow sorting of multiple exchange rates using the following sorting order;

Exchange rate type
Exchange rate provider
base currency
term currency

Finally ExchangeRate is modeled as an immutable and thread safe type. Also exchange rates are java.io.Serializable, hereby serializing in the following form and order:

The base javax.money.CurrencyUnit
The target javax.money.CurrencyUnit
The factor (NumberValue)
The javax.money.convert.ConversionContext
The rate chain

Field Summary

Modifier and Type	Field and Description
private final CurrencyUnit	base The base currency.
private final List<ExchangeRate>	chain The full chain, at least one instance long.
private final ConversionContext	conversionContext The `javax.money.convert.ConversionContext`
private final NumberValue	factor The conversion factor.
private static final long	serialVersionUID serialVersionUID.
private final CurrencyUnit	term The terminating currency.

Access	Constructor and Description
pack-priv	DefaultExchangeRate(ExchangeRateBuilder The Builder, never `null`. builder) Creates a new instance with a custom chain of exchange rate type, e.g. or creating derived rates.

Method Summary

Modifier and Type	Method and Description
public int	compareTo(ExchangeRate o) Implements java.lang.Comparable.compareTo. Compares this object with the specified object for order.
public boolean	equals(Object obj) Overrides java.lang.Object.equals. Indicates whether some other object is "equal to" this one.
public final CurrencyUnit	Returns: the base `javax.money.CurrencyUnit`. getBaseCurrency() Implements javax.money.convert.ExchangeRate.getBaseCurrency. Get the base (source) `javax.money.CurrencyUnit`.
public final ConversionContext	Returns: the conversion context, never null. getContext() Implements javax.money.convert.ExchangeRate.getContext. Access the `javax.money.convert.ConversionContext` of `javax.money.convert.ExchangeRate`.
public final CurrencyUnit	Returns: the term `javax.money.CurrencyUnit`. getCurrency() Implements javax.money.convert.ExchangeRate.getCurrency. Get the term (target) `javax.money.CurrencyUnit`.
public final List<ExchangeRate>	Returns: the chain of rates, in case of a derived rate, this may be several instances. For a direct exchange rate, this equals to `new ExchangeRate[]{this}`. getExchangeRateChain() Implements javax.money.convert.ExchangeRate.getExchangeRateChain. Access the chain of exchange rates.
public final NumberValue	Returns: the bid factor for this exchange rate, or `null`. getFactor() Implements javax.money.convert.ExchangeRate.getFactor. Access the rate's bid factor.
public int	hashCode() Overrides java.lang.Object.hashCode. Returns a hash code value for this object.
public final boolean	Returns: true, if the exchange rate is derived. isDerived() Overrides default javax.money.convert.ExchangeRate.isDerived. Allows to evaluate if this exchange rate is a derived exchange rate.
private void	setExchangeRateChain(List<ExchangeRate> the chain to set. chain) Internal method to set the rate chain, which also ensure that the chain passed, when not null, contains valid elements.
public ExchangeRateBuilder	Returns: a new `ExchangeRateBuilder`, never `null`. toBuilder() Create a `ExchangeRateBuilder` based on the current rate instance.
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.

Inherited from java.lang.Object:: clone finalize getClass notify notifyAll wait wait wait

Field Detail

base	back to summary
private final CurrencyUnit base The base currency.

chain	back to summary
private final List<ExchangeRate> chain The full chain, at least one instance long.

conversionContext	back to summary
private final ConversionContext conversionContext The `javax.money.convert.ConversionContext`

factor	back to summary
private final NumberValue factor The conversion factor.

serialVersionUID	back to summary
private static final long serialVersionUID serialVersionUID.

term	back to summary
private final CurrencyUnit term The terminating currency.

Constructor Detail

DefaultExchangeRate back to summary

DefaultExchangeRate	back to summary
pack-priv DefaultExchangeRate(ExchangeRateBuilder builder) Creates a new instance with a custom chain of exchange rate type, e.g. or creating derived rates. Parameters builder:ExchangeRateBuilder The Builder, never `null`.

pack-priv DefaultExchangeRate(ExchangeRateBuilder builder)

Creates a new instance with a custom chain of exchange rate type, e.g. or creating derived rates.

Parameters

builder:ExchangeRateBuilder: The Builder, never null.

Method Detail

compareTo back to summary

compareTo	back to summary
public int compareTo(ExchangeRate o) Implements java.lang.Comparable.compareTo. Doc from java.lang.Comparable.compareTo. Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object. The implementor must ensure `signum(x.compareTo(y)) == -signum(y.compareTo(x))` for all `x` and `y`. (This implies that `x.compareTo(y)` must throw an exception if and only if `y.compareTo(x)` throws an exception.) The implementor must also ensure that the relation is transitive: `(x.compareTo(y) > 0 && y.compareTo(z) > 0)` implies `x.compareTo(z) > 0`. Finally, the implementor must ensure that `x.compareTo(y)==0` implies that `signum(x.compareTo(z)) == signum(y.compareTo(z))`, for all `z`. Annotations @Override

public int compareTo(ExchangeRate o)

Implements java.lang.Comparable.compareTo.

Doc from java.lang.Comparable.compareTo.

Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

The implementor must ensure signum(x.compareTo(y)) == -signum(y.compareTo(x)) for all x and y. (This implies that x.compareTo(y) must throw an exception if and only if y.compareTo(x) throws an exception.)

The implementor must also ensure that the relation is transitive: (x.compareTo(y) > 0 && y.compareTo(z) > 0) implies x.compareTo(z) > 0.

Finally, the implementor must ensure that x.compareTo(y)==0 implies that signum(x.compareTo(z)) == signum(y.compareTo(z)), for all z.

Annotations

@Override

equals back to summary

equals	back to summary
public boolean equals(Object obj) Overrides java.lang.Object.equals. Doc from java.lang.Object.equals. Indicates whether some other object is "equal to" this one. The `equals` method implements an equivalence relation on non-null object references: It is reflexive: for any non-null reference value `x`, `x.equals(x)` should return `true`. It is symmetric: for any non-null reference values `x` and `y`, `x.equals(y)` should return `true` if and only if `y.equals(x)` returns `true`. It is transitive: for any non-null reference values `x`, `y`, and `z`, if `x.equals(y)` returns `true` and `y.equals(z)` returns `true`, then `x.equals(z)` should return `true`. It is consistent: for any non-null reference values `x` and `y`, multiple invocations of `x.equals(y)` consistently return `true` or consistently return `false`, provided no information used in `equals` comparisons on the objects is modified. For any non-null reference value `x`, `x.equals(null)` should return `false`. An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes. Annotations @Override

public boolean equals(Object obj)

Overrides java.lang.Object.equals.

Doc from java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

It is reflexive: for any non-null reference value x, x.equals(x) should return true.
It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Annotations

@Override

getBaseCurrency back to summary

getBaseCurrency	back to summary
public final CurrencyUnit getBaseCurrency() Implements javax.money.convert.ExchangeRate.getBaseCurrency. Get the base (source) `javax.money.CurrencyUnit`. Returns:CurrencyUnit the base `javax.money.CurrencyUnit`. Annotations @Override

public final CurrencyUnit getBaseCurrency()

Implements javax.money.convert.ExchangeRate.getBaseCurrency.

Get the base (source) javax.money.CurrencyUnit.

Returns:CurrencyUnit

the base javax.money.CurrencyUnit.

Annotations

@Override

getContext back to summary

getContext	back to summary
public final ConversionContext getContext() Implements javax.money.convert.ExchangeRate.getContext. Access the `javax.money.convert.ConversionContext` of `javax.money.convert.ExchangeRate`. Returns:ConversionContext the conversion context, never null. Annotations @Override

public final ConversionContext getContext()

Implements javax.money.convert.ExchangeRate.getContext.

Access the javax.money.convert.ConversionContext of javax.money.convert.ExchangeRate.

Returns:ConversionContext

the conversion context, never null.

Annotations

@Override

getCurrency back to summary

getCurrency	back to summary
public final CurrencyUnit getCurrency() Implements javax.money.convert.ExchangeRate.getCurrency. Get the term (target) `javax.money.CurrencyUnit`. Returns:CurrencyUnit the term `javax.money.CurrencyUnit`. Annotations @Override

public final CurrencyUnit getCurrency()

Implements javax.money.convert.ExchangeRate.getCurrency.

Get the term (target) javax.money.CurrencyUnit.

Returns:CurrencyUnit

the term javax.money.CurrencyUnit.

Annotations

@Override

getExchangeRateChain back to summary

getExchangeRateChain	back to summary
public final List<ExchangeRate> getExchangeRateChain() Implements javax.money.convert.ExchangeRate.getExchangeRateChain. Access the chain of exchange rates. Returns:List<ExchangeRate> the chain of rates, in case of a derived rate, this may be several instances. For a direct exchange rate, this equals to `new ExchangeRate[]{this}`. Annotations @Override

public final List<ExchangeRate> getExchangeRateChain()

Implements javax.money.convert.ExchangeRate.getExchangeRateChain.

Access the chain of exchange rates.

Returns:List<ExchangeRate>

the chain of rates, in case of a derived rate, this may be several instances. For a direct exchange rate, this equals to new ExchangeRate[]{this}.

Annotations

@Override

getFactor back to summary

getFactor	back to summary
public final NumberValue getFactor() Implements javax.money.convert.ExchangeRate.getFactor. Access the rate's bid factor. Returns:NumberValue the bid factor for this exchange rate, or `null`. Annotations @Override

public final NumberValue getFactor()

Implements javax.money.convert.ExchangeRate.getFactor.

Access the rate's bid factor.

Returns:NumberValue

the bid factor for this exchange rate, or null.

Annotations

@Override

hashCode back to summary

hashCode	back to summary
public int hashCode() Overrides java.lang.Object.hashCode. Doc from java.lang.Object.hashCode. Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by `java.util.HashMap`. The general contract of `hashCode` is: Whenever it is invoked on the same object more than once during an execution of a Java application, the `hashCode` method must consistently return the same integer, provided no information used in `equals` comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application. If two objects are equal according to the `equals` method, then calling the `hashCode` method on each of the two objects must produce the same integer result. It is not required that if two objects are unequal according to the `equals` method, then calling the `hashCode` method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables. Annotations @Override

public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.

Annotations

@Override

isDerived back to summary

isDerived	back to summary
public final boolean isDerived() Overrides default javax.money.convert.ExchangeRate.isDerived. Allows to evaluate if this exchange rate is a derived exchange rate. Derived exchange rates are defined by an ordered list of subconversions with intermediate steps, whereas a direct conversion is possible in one steps. This method always returns `true`, if the chain contains more than one rate. Direct rates, have also a chain, but with exact one rate. Returns:boolean true, if the exchange rate is derived. Annotations @Override

public final boolean isDerived()

Overrides default javax.money.convert.ExchangeRate.isDerived.

Allows to evaluate if this exchange rate is a derived exchange rate.

Derived exchange rates are defined by an ordered list of subconversions with intermediate steps, whereas a direct conversion is possible in one steps.

This method always returns true, if the chain contains more than one rate. Direct rates, have also a chain, but with exact one rate.

Returns:boolean

true, if the exchange rate is derived.

Annotations

@Override

setExchangeRateChain	back to summary
private void setExchangeRateChain(List<ExchangeRate> chain) Internal method to set the rate chain, which also ensure that the chain passed, when not null, contains valid elements. Parameters chain:List<ExchangeRate> the chain to set.

setExchangeRateChain

back to summary

private void setExchangeRateChain(List<ExchangeRate> chain)

Internal method to set the rate chain, which also ensure that the chain passed, when not null, contains valid elements.

Parameters

chain:List<ExchangeRate>: the chain to set.

toBuilder back to summary

toBuilder	back to summary
public ExchangeRateBuilder toBuilder() Create a `ExchangeRateBuilder` based on the current rate instance. Returns:ExchangeRateBuilder a new `ExchangeRateBuilder`, never `null`.

public ExchangeRateBuilder toBuilder()

Create a ExchangeRateBuilder based on the current rate instance.

Returns:ExchangeRateBuilder: a new ExchangeRateBuilder, never null.

toString back to summary

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Doc from java.lang.Object.toString. Returns a string representation of the object. Satisfying this method's contract implies a non-`null` result must be returned. Annotations @Override

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Annotations

@Override

pack-priv Class DefaultExchangeRate

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail