Class Currency

  • All Implemented Interfaces:
    Serializable, Comparable<Currency>

    public final class Currency
    extends Object
    implements Comparable<Currency>, Serializable
    A unit of currency.

    This class represents a unit of currency such as the British Pound, Euro or US Dollar. The currency is represented by a three letter code, intended to be ISO-4217.

    It is recommended to define currencies in advance using the Currency.ini file. Standard configuration includes many commonly used currencies.

    Only currencies listed in configuration will be returned by getAvailableCurrencies(). If a currency is requested that is not defined in configuration, it will still be created, however it will have the default value of zero for the minor units and 'USD' for the triangulation currency.

    This class is immutable and thread-safe.

    See Also:
    Serialized Form
    • Field Detail

      • USD

        public static final Currency USD
        The currency 'USD' - United States Dollar.
      • EUR

        public static final Currency EUR
        The currency 'EUR' - Euro.
      • JPY

        public static final Currency JPY
        The currency 'JPY' - Japanese Yen.
      • GBP

        public static final Currency GBP
        The currency 'GBP' - British pound.
      • CHF

        public static final Currency CHF
        The currency 'CHF' - Swiss Franc.
      • AUD

        public static final Currency AUD
        The currency 'AUD' - Australian Dollar.
      • CAD

        public static final Currency CAD
        The currency 'CAD' - Canadian Dollar.
      • NZD

        public static final Currency NZD
        The currency 'NZD' - New Zealand Dollar.
      • AED

        public static final Currency AED
        The currency 'AED' - UAE Dirham.
      • ARS

        public static final Currency ARS
        The currency 'ARS' - Argentine Peso.
      • BGN

        public static final Currency BGN
        The currency 'BGN' - Bulgarian Lev.
      • BHD

        public static final Currency BHD
        The currency 'BHD' - Bahraini Dinar.
      • BRL

        public static final Currency BRL
        The currency 'BRL' - Brazilian Real.
      • CLP

        public static final Currency CLP
        The currency 'CLP' - Chilean Peso.
      • CNH

        public static final Currency CNH
        The currency 'CNH' - Chinese Offshore Yuan.
      • CNY

        public static final Currency CNY
        The currency 'CNY' - Chinese Onshore Yuan.
      • COP

        public static final Currency COP
        The currency 'COP' - Colombian Peso.
      • CZK

        public static final Currency CZK
        The currency 'CZK' - Czeck Krona.
      • DKK

        public static final Currency DKK
        The currency 'DKK' - Danish Krone.
      • EGP

        public static final Currency EGP
        The currency 'EGP' - Egyptian Pound.
      • HKD

        public static final Currency HKD
        The currency 'HKD' - Hong Kong Dollar.
      • HRK

        public static final Currency HRK
        The currency 'HRK' - Croatian Kuna.
      • HUF

        public static final Currency HUF
        The currency 'HUF' = Hugarian Forint.
      • IDR

        public static final Currency IDR
        The currency 'IDR' = Indonesian Rupiah.
      • ILS

        public static final Currency ILS
        The currency 'ILS' = Israeli Shekel.
      • INR

        public static final Currency INR
        The currency 'INR' = Indian Rupee.
      • ISK

        public static final Currency ISK
        The currency 'ISK' = Icelandic Krone.
      • KRW

        public static final Currency KRW
        The currency 'KRW' = South Korean Won.
      • KZT

        public static final Currency KZT
        The currency 'KZT' = Kazakhstani Tenge.
      • MAD

        public static final Currency MAD
        The currency 'MAD' - Moroccan Dirham.
      • MXN

        public static final Currency MXN
        The currency 'MXN' - Mexican Peso.
      • MYR

        public static final Currency MYR
        The currency 'MYR' - Malaysian Ringgit.
      • NOK

        public static final Currency NOK
        The currency 'NOK' - Norwegian Krone.
      • OMR

        public static final Currency OMR
        The currency 'OMR' - Omani Rial.
      • PEN

        public static final Currency PEN
        The currency 'PEN' - Peruvian Nuevo Sol.
      • PHP

        public static final Currency PHP
        The currency 'PHP' - Philippine Peso.
      • PKR

        public static final Currency PKR
        The currency 'PKR' - Pakistani Rupee.
      • PLN

        public static final Currency PLN
        The currency 'PLN' - Polish Zloty.
      • QAR

        public static final Currency QAR
        The currency 'QAR' - Qatari Riyal.
      • RON

        public static final Currency RON
        The currency 'RON' - Romanian New Leu.
      • RUB

        public static final Currency RUB
        The currency 'RUB' - Russian Ruble.
      • SAR

        public static final Currency SAR
        The currency 'SAR' - Saudi Riyal.
      • SEK

        public static final Currency SEK
        The currency 'SEK' - Swedish Krona.
      • SGD

        public static final Currency SGD
        The currency 'SGD' - Singapore Dollar.
      • THB

        public static final Currency THB
        The currency 'THB' - Thai Baht.
      • TRY

        public static final Currency TRY
        The currency 'TRY' - Turkish Lira.
      • TWD

        public static final Currency TWD
        The currency 'TWD' - New Taiwan Dollar.
      • UAH

        public static final Currency UAH
        The currency 'UAH' - Ukrainian Hryvnia.
      • VND

        public static final Currency VND
        The currency 'VND' - Vietnamese Dong.
      • ZAR

        public static final Currency ZAR
        The currency 'ZAR' - South African Rand.
      • XXX

        public static final Currency XXX
        The currency 'XXX' - No applicable currency.
      • XAG

        public static final Currency XAG
        The currency 'XAG' - Silver (troy ounce).
      • XAU

        public static final Currency XAU
        The currency 'XAU' - Gold (troy ounce).
      • XPD

        public static final Currency XPD
        The currency 'XPD' - Paladium (troy ounce).
      • XPT

        public static final Currency XPT
        The currency 'XPT' - Platinum (troy ounce).
    • Method Detail

      • getAvailableCurrencies

        public static Set<Currency> getAvailableCurrencies()
        Obtains the set of configured currencies.

        This contains all the currencies that have been defined in configuration. Any currency instances that have been dynamically created are not included.

        Returns:
        an immutable set containing all registered currencies
      • of

        public static Currency of​(String currencyCode)
        Obtains an instance for the specified ISO-4217 three letter currency code.

        A currency is uniquely identified by ISO-4217 three letter code. Currencies should be defined in configuration before they can be used. If the requested currency is not defined in configuration, it will still be created, however it will have the default value of zero for the minor units and 'USD' for the triangulation currency.

        Parameters:
        currencyCode - the three letter currency code, ASCII and upper case
        Returns:
        the singleton instance
        Throws:
        IllegalArgumentException - if the currency code is invalid
      • parse

        public static Currency parse​(String currencyCode)
        Parses a string to obtain a Currency.

        The parse is identical to of(String) except that it will convert letters to upper case first. If the requested currency is not defined in configuration, it will still be created, however it will have the default value of zero for the minor units and 'USD' for the triangulation currency.

        Parameters:
        currencyCode - the three letter currency code, ASCII
        Returns:
        the singleton instance
        Throws:
        IllegalArgumentException - if the currency code is invalid
      • getCode

        public String getCode()
        Gets the three letter ISO code.
        Returns:
        the three letter ISO code
      • getMinorUnitDigits

        public int getMinorUnitDigits()
        Gets the number of digits in the minor unit.

        For example, 'USD' will return 2, indicating that there are two digits, corresponding to cents in the dollar.

        Returns:
        the number of fraction digits
      • getTriangulationCurrency

        public Currency getTriangulationCurrency()
        Gets the preferred triangulation currency.

        When obtaining a market quote for a currency, the triangulation currency is used if no direct rate can be found. For example, there is no direct rate for 'CZK/SGD'. Instead 'CZK' might be defined to triangulate via 'EUR' and 'SGD' with 'USD'. Since the three rates, 'CZK/EUR', 'EUR/USD' and 'USD/SGD' can be obtained, a rate can be determined for 'CZK/SGD'. Note that most currencies triangulate via 'USD'.

        Returns:
        the triangulation currency
      • roundMinorUnits

        public double roundMinorUnits​(double amount)
        Rounds the specified amount according to the minor units.

        For example, 'USD' has 2 minor digits, so 63.347 will be rounded to 63.35.

        Parameters:
        amount - the amount to round
        Returns:
        the rounded amount
      • roundMinorUnits

        public BigDecimal roundMinorUnits​(BigDecimal amount)
        Rounds the specified amount according to the minor units.

        For example, 'USD' has 2 minor digits, so 63.347 will be rounded to 63.35.

        Parameters:
        amount - the amount to round
        Returns:
        the rounded amount
      • roundMinorUnits

        public Decimal roundMinorUnits​(Decimal amount)
        Rounds the specified amount according to the minor units.

        For example, 'USD' has 2 minor digits, so 63.347 will be rounded to 63.35.

        Parameters:
        amount - the amount to round
        Returns:
        the rounded amount
      • compareTo

        public int compareTo​(Currency other)
        Compares this currency to another.

        The comparison sorts alphabetically by the three letter currency code.

        Specified by:
        compareTo in interface Comparable<Currency>
        Parameters:
        other - the other currency
        Returns:
        negative if less, zero if equal, positive if greater
      • equals

        public boolean equals​(Object obj)
        Checks if this currency equals another currency.

        The comparison checks the three letter currency code.

        Overrides:
        equals in class Object
        Parameters:
        obj - the other currency, null returns false
        Returns:
        true if equal
      • hashCode

        public int hashCode()
        Returns a suitable hash code for the currency.
        Overrides:
        hashCode in class Object
        Returns:
        the hash code
      • toString

        public String toString()
        Returns a string representation of the currency, which is the three letter code.
        Overrides:
        toString in class Object
        Returns:
        the three letter currency code