/*
* Copyright 2012-2016 Credit Suisse
* Copyright 2018-2020 Werner Keil, Otavio Santana, Trivadis AG
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package javax.money;
A unit of currency.
This interface represents a unit of currency such as the British Pound, Euro,
US Dollar, Bitcoin or other. It provides interoperability between different
implementations.
Currencies can be distinguished by separate getCurrencyCode() codes, similar to Currency.
Implementation specification
Implementation of this class
- are required to implement
equals/hashCode considering the concrete implementation type and currency code.
- are required to be thread-safe
- are required to be immutable
- are required to be comparable
- should be serializable (on platforms providing serialization).
Author: Werner Keil, Stephen Colebourne, Anatole Tresch See Also: Version: 1.0
/**
* A unit of currency.
* <p>
* This interface represents a unit of currency such as the British Pound, Euro,
* US Dollar, Bitcoin or other. It provides interoperability between different
* implementations.
* <p>
* Currencies can be distinguished by separate {@link #getCurrencyCode()} codes,
* similar to {@link java.util.Currency}.
* <h3>Implementation specification</h3>
* Implementation of this class
* <ul>
* <li>are required to implement {@code equals/hashCode} considering the
* concrete implementation type and currency code.</li>
* <li>are required to be thread-safe</li>
* <li>are required to be immutable</li>
* <li>are required to be comparable</li>
* <li>should be serializable (on platforms providing serialization).</li>
* </ul>
*
* @author Werner Keil
* @author Stephen Colebourne
* @author Anatole Tresch
*
* @version 1.0
*
* @see <a href="https://en.wikipedia.org/wiki/Currency">Wikipedia: Currency</a>
*/
public interface CurrencyUnit extends Comparable<CurrencyUnit>{
Gets the unique currency code, the effective code depends on the
currency.
Since each currency is identified by this code, the currency code is required to be defined for every CurrencyUnit and not null or empty.
For ISO codes the 3-letter ISO code should be returned. For non ISO
currencies no constraints are defined.
Returns: the currency code, never null. For ISO-4217 this this will be the three letter ISO-4217 code. However, alternate currencies can have different codes. Also there is no constraint about the formatting of alternate codes, despite the fact that the currency codes must be unique.
/**
* Gets the unique currency code, the effective code depends on the
* currency.
* <p>
* Since each currency is identified by this code, the currency code is
* required to be defined for every {@link CurrencyUnit} and not
* {@code null} or empty.
* <p>
* For ISO codes the 3-letter ISO code should be returned. For non ISO
* currencies no constraints are defined.
*
* @return the currency code, never {@code null}. For ISO-4217 this this
* will be the three letter ISO-4217 code. However, alternate
* currencies can have different codes. Also there is no constraint
* about the formatting of alternate codes, despite the fact that
* the currency codes must be unique.
*/
String getCurrencyCode();
Gets a numeric currency code. within the ISO-4217 name space, this equals
to the ISO numeric code. In other currency name spaces this number may be
different, or even undefined (-1).
The numeric code is an optional alternative to the standard currency
code. If defined, the numeric code is required to be unique.
This method matches the API of Currency.
Returns: the numeric currency code
/**
* Gets a numeric currency code. within the ISO-4217 name space, this equals
* to the ISO numeric code. In other currency name spaces this number may be
* different, or even undefined (-1).
* <p>
* The numeric code is an optional alternative to the standard currency
* code. If defined, the numeric code is required to be unique.
* <p>
* This method matches the API of {@link java.util.Currency}.
*
* @return the numeric currency code
*/
int getNumericCode();
Gets the number of fractional digits typically used by this currency.
Different currencies have different numbers of fractional digits by
default. For example, 'GBP' has 2 fractional digits, but 'JPY' has zero.
virtual currencies or those with no applicable fractional are indicated
by -1.
This method matches the API of Currency.
Returns: the fractional digits, from 0 to 9 (normally 0, 2 or 3), or 0 for
pseudo-currencies.
/**
* Gets the number of fractional digits typically used by this currency.
* <p>
* Different currencies have different numbers of fractional digits by
* default. For example, 'GBP' has 2 fractional digits, but 'JPY' has zero.
* virtual currencies or those with no applicable fractional are indicated
* by -1.
* <p>
* This method matches the API of {@link java.util.Currency}.
*
* @return the fractional digits, from 0 to 9 (normally 0, 2 or 3), or 0 for
* pseudo-currencies.
*
*/
int getDefaultFractionDigits();
Returns the CurrencyContext of a currency. This context contains additional information about the type and capabilities of a CurrencyUnit, e.g. its provider and more. Returns: the currency's context, never null.
/**
* Returns the {@link javax.money.CurrencyContext} of a currency. This context contains additional information
* about the type and capabilities of a CurrencyUnit, e.g. its provider and more.
* @return the currency's context, never null.
*/
CurrencyContext getContext();
}