javax.money.CurrencyUnit Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of money-api-bp Show documentation

JSR 354 provides an API for representing, transporting, and performing comprehensive calculations with Money and Currency. This module provides a forward compatible backport of the API.

There is a newer version: 1.0.4

Show newest version

/*
 * CREDIT SUISSE IS WILLING TO LICENSE THIS SPECIFICATION TO YOU ONLY UPON THE
 * CONDITION THAT YOU ACCEPT ALL OF THE TERMS CONTAINED IN THIS AGREEMENT.
 * PLEASE READ THE TERMS AND CONDITIONS OF THIS AGREEMENT CAREFULLY. BY
 * DOWNLOADING THIS SPECIFICATION, YOU ACCEPT THE TERMS AND CONDITIONS OF THE
 * AGREEMENT. IF YOU ARE NOT WILLING TO BE BOUND BY IT, SELECT THE "DECLINE"
 * BUTTON AT THE BOTTOM OF THIS PAGE. Specification: JSR-354 Money and Currency
 * API ("Specification") Copyright (c) 2012-2014, Credit Suisse All rights
 * reserved.
 */
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 0.7
 * 
 * @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 CurrencyContext} of a a currency. This context contains additional information
     * on the type and capabilities of a CurrencyUnit, e.g. its provider and more.
     * @return the currency's context, never null.
     */
    CurrencyContext getContext();

}