javax.money.CurrencyUnit Maven / Gradle / Ivy
Show all versions of money-api Show documentation
/*
* 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 {@link #getCurrencyCode()} codes,
* similar to {@link java.util.Currency}.
*
Implementation specification
* Implementation of this class
*
* - are required to implement {@code 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
* @author Stephen Colebourne
* @author Anatole Tresch
*
* @version 1.0
*
* @see Wikipedia: Currency
*/
public interface CurrencyUnit extends Comparable{
/**
* 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 {@link CurrencyUnit} and not
* {@code null} or empty.
*
* 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 {@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 {@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 {@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();
}