001/*
002 * CREDIT SUISSE IS WILLING TO LICENSE THIS SPECIFICATION TO YOU ONLY UPON THE
003 * CONDITION THAT YOU ACCEPT ALL OF THE TERMS CONTAINED IN THIS AGREEMENT.
004 * PLEASE READ THE TERMS AND CONDITIONS OF THIS AGREEMENT CAREFULLY. BY
005 * DOWNLOADING THIS SPECIFICATION, YOU ACCEPT THE TERMS AND CONDITIONS OF THE
006 * AGREEMENT. IF YOU ARE NOT WILLING TO BE BOUND BY IT, SELECT THE "DECLINE"
007 * BUTTON AT THE BOTTOM OF THIS PAGE. Specification: JSR-354 Money and Currency
008 * API ("Specification") Copyright (c) 2012-2013, Credit Suisse All rights
009 * reserved.
010 */
011package javax.money;
012
013/**
014 * A unit of currency.
015 * <p>
016 * This interface represents a unit of currency such as the British Pound, Euro,
017 * US Dollar, Bitcoin or other. It is mainly defined to provide interoperability
018 * between different implementations.
019 * <p>
020 * Currencies can be distinguished by separate {@link #getCurrencyCode()} codes,
021 * similar to {@link java.util.Currency}.
022 * <h4>Implementation specification</h4>
023 * Implementation of this class
024 * <ul>
025 * <li>are required to be implement {@code equals/hashCode} considering the
026 * concrete implementation type and currency code.
027 * <li>are required to be thread-safe
028 * <li>are required to be immutable
029 * <li>are required to be comparable
030 * <li>are highly recommended to be serializable.
031 * </ul>
032 * 
033 * @author Werner Keil
034 * @author Stephen Colebourne
035 * @author Anatole Tresch
036 * 
037 * @see <a href="https://en.wikipedia.org/wiki/Currency">Wikipedia: Currency</a>
038 */
039public interface CurrencyUnit {
040
041        /**
042         * Gets the unique currency code, the effective code depends on the
043         * currency.
044         * <p>
045         * Since each currency is identified by this code, the currency code is
046         * required to be defined for every {@link CurrencyUnit} and not
047         * {@code null} or empty.
048         * <p>
049         * For ISO codes the 3-letter ISO code should be returned. For non ISO
050         * currencies no constraints are defined.
051         * 
052         * @return the currency code, never {@code null}. For ISO-4217 this this
053         *         will be the three letter ISO-4217 code. However, alternate
054         *         currencies can have different codes. Also there is no constraint
055         *         about the formatting of alternate codes, despite they fact that
056         *         the currency codes must be unique.
057         */
058        public String getCurrencyCode();
059
060}