Class Currency

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<Currency>

    public final class Currency
    extends java.lang.Object
    implements java.lang.Comparable<Currency>, java.io.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 Summary

      Fields 
      Modifier and Type Field Description
      static Currency AED
      The currency 'AED' - UAE Dirham.
      static Currency ARS
      The currency 'ARS' - Argentine Peso.
      static Currency AUD
      The currency 'AUD' - Australian Dollar.
      static Currency BGN
      The currency 'BGN' - Bulgarian Lev.
      static Currency BHD
      The currency 'BHD' - Bahraini Dinar.
      static Currency BRL
      The currency 'BRL' - Brazilian Real.
      static Currency CAD
      The currency 'CAD' - Canadian Dollar.
      static Currency CHF
      The currency 'CHF' - Swiss Franc.
      static Currency CLP
      The currency 'CLP' - Chilean Peso.
      static Currency CNY
      The currency 'CNY' - Chinese Yuan.
      static Currency COP
      The currency 'COP' - Colombian Peso.
      static Currency CZK
      The currency 'CZK' - Czeck Krona.
      static Currency DKK
      The currency 'DKK' - Danish Krone.
      static Currency EGP
      The currency 'EGP' - Egyptian Pound.
      static Currency EUR
      The currency 'EUR' - Euro.
      static Currency GBP
      The currency 'GBP' - British pound.
      static Currency HKD
      The currency 'HKD' - Hong Kong Dollar.
      static Currency HRK
      The currency 'HRK' - Croatian Kuna.
      static Currency HUF
      The currency 'HUF' = Hugarian Forint.
      static Currency IDR
      The currency 'IDR' = Indonesian Rupiah.
      static Currency ILS
      The currency 'ILS' = Israeli Shekel.
      static Currency INR
      The currency 'INR' = Indian Rupee.
      static Currency ISK
      The currency 'ISK' = Icelandic Krone.
      static Currency JPY
      The currency 'JPY' - Japanese Yen.
      static Currency KRW
      The currency 'KRW' = South Korean Won.
      static Currency MXN
      The currency 'MXN' - Mexican Peso.
      static Currency MYR
      The currency 'MYR' - Malaysian Ringgit.
      static Currency NOK
      The currency 'NOK' - Norwegian Krone.
      static Currency NZD
      The currency 'NZD' - New Zealand Dollar.
      static Currency PEN
      The currency 'PEN' - Peruvian Nuevo Sol.
      static Currency PHP
      The currency 'PHP' - Philippine Peso.
      static Currency PKR
      The currency 'PKR' - Pakistani Rupee.
      static Currency PLN
      The currency 'PLN' - Polish Zloty.
      static Currency RON
      The currency 'RON' - Romanian New Leu.
      static Currency RUB
      The currency 'RUB' - Russian Ruble.
      static Currency SAR
      The currency 'SAR' - Saudi Riyal.
      static Currency SEK
      The currency 'SEK' - Swedish Krona.
      static Currency SGD
      The currency 'SGD' - Singapore Dollar.
      static Currency THB
      The currency 'THB' - Thai Baht.
      static Currency TRY
      The currency 'TRY' - Turkish Lira.
      static Currency TWD
      The currency 'TWD' - New Taiwan Dollar.
      static Currency UAH
      The currency 'UAH' - Ukrainian Hryvnia.
      static Currency USD
      The currency 'USD' - United States Dollar.
      static Currency XAG
      The currency 'XAG' - Silver (troy ounce).
      static Currency XAU
      The currency 'XAU' - Gold (troy ounce).
      static Currency XPD
      The currency 'XPD' - Paladium (troy ounce).
      static Currency XPT
      The currency 'XPT' - Platinum (troy ounce).
      static Currency XXX
      The currency 'XXX' - No applicable currency.
      static Currency ZAR
      The currency 'ZAR' - South African Rand.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(Currency other)
      Compares this currency to another.
      boolean equals​(java.lang.Object obj)
      Checks if this currency equals another currency.
      static java.util.Set<Currency> getAvailableCurrencies()
      Obtains the set of configured currencies.
      java.lang.String getCode()
      Gets the three letter ISO code.
      int getMinorUnitDigits()
      Gets the number of digits in the minor unit.
      Currency getTriangulationCurrency()
      Gets the preferred triangulation currency.
      int hashCode()
      Returns a suitable hash code for the currency.
      static Currency of​(java.lang.String currencyCode)
      Obtains an instance for the specified ISO-4217 three letter currency code.
      static Currency parse​(java.lang.String currencyCode)
      Parses a string to obtain a Currency.
      double roundMinorUnits​(double amount)
      Rounds the specified amount according to the minor units.
      java.math.BigDecimal roundMinorUnits​(java.math.BigDecimal amount)
      Rounds the specified amount according to the minor units.
      java.lang.String toString()
      Returns a string representation of the currency, which is the three letter code.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • 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.
      • CNY

        public static final Currency CNY
        The currency 'CNY' - Chinese 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.
      • 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.
      • 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.
      • 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.
      • 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 java.util.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​(java.lang.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:
        java.lang.IllegalArgumentException - if the currency code is invalid
      • parse

        public static Currency parse​(java.lang.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:
        java.lang.IllegalArgumentException - if the currency code is invalid
      • getCode

        public java.lang.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 java.math.BigDecimal roundMinorUnits​(java.math.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
      • 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 java.lang.Comparable<Currency>
        Parameters:
        other - the other currency
        Returns:
        negative if less, zero if equal, positive if greater
      • equals

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

        The comparison checks the three letter currency code.

        Overrides:
        equals in class java.lang.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 java.lang.Object
        Returns:
        the hash code
      • toString

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