Package org.joda.money

Class CurrencyUnit

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<CurrencyUnit>
    public final class CurrencyUnit
extends java.lang.Object
implements java.lang.Comparable<CurrencyUnit>, java.io.Serializable
    A unit of currency.

    This class represents a unit of currency such as the British Pound, Euro or US Dollar.

    The set of loaded currencies is provided by an instance of CurrencyUnitDataProvider. The provider used is determined by the system property org.joda.money.CurrencyUnitDataProvider which should be the fully qualified class name of the provider. The default provider loads the first resource named /org/joda/money/MoneyData.csv on the classpath.

    This class is immutable and thread-safe.

    See Also:
    Serialized Form

    • Constructor Summary

      Constructors 
      Constructor Description
      CurrencyUnit​(java.lang.String code, short numericCode, short decimalPlaces)
      Constructor, creating a new currency instance.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(CurrencyUnit other)
      Compares this currency to another by alphabetical comparison of the code.
      boolean equals​(java.lang.Object obj)
      Checks if this currency equals another currency.
      java.lang.String getCode()
      Gets the ISO-4217 three-letter currency code.
      java.util.Set<java.lang.String> getCountryCodes()
      Gets the country codes applicable to this currency.
      int getDecimalPlaces()
      Gets the number of decimal places typically used by this currency.
      java.lang.String getNumeric3Code()
      Gets the ISO-4217 numeric currency code as a three digit string.
      int getNumericCode()
      Gets the ISO-4217 numeric currency code.
      java.lang.String getSymbol()
      Gets the symbol for this locale from the JDK.
      java.lang.String getSymbol​(java.util.Locale locale)
      Gets the symbol for this locale from the JDK.
      int hashCode()
      Returns a suitable hash code for the currency.
      boolean isPseudoCurrency()
      Checks if this is a pseudo-currency.
      static CurrencyUnit of​(java.lang.String currencyCode)
      Obtains an instance of CurrencyUnit for the specified three letter currency code.
      static CurrencyUnit of​(java.util.Currency currency)
      Obtains an instance of CurrencyUnit matching the specified JDK currency.
      static CurrencyUnit of​(java.util.Locale locale)
      Obtains an instance of CurrencyUnit for the specified locale.
      static CurrencyUnit ofCountry​(java.lang.String countryCode)
      Obtains an instance of CurrencyUnit for the specified ISO-3166 country code.
      static CurrencyUnit ofNumericCode​(int numericCurrencyCode)
      Obtains an instance of CurrencyUnit for the specified ISO-4217 numeric currency code.
      static CurrencyUnit ofNumericCode​(java.lang.String numericCurrencyCode)
      Obtains an instance of CurrencyUnit for the specified ISO-4217 numeric currency code.
      private void readObject​(java.io.ObjectInputStream ois)
      Block malicious data streams.
      static void registerCountry​(java.lang.String countryCode, CurrencyUnit currency)
      Registers a country code, typically ISO 3166-1-alpha-2.
      static CurrencyUnit registerCurrency​(java.lang.String currencyCode, int numericCurrencyCode, int decimalPlaces, boolean force)
      Registers a currency allowing it to be used, allowing replacement.
      static CurrencyUnit registerCurrency​(java.lang.String currencyCode, int numericCurrencyCode, int decimalPlaces, java.util.List<java.lang.String> countryCodes)
      Registers a currency and associated countries allowing it to be used.
      static CurrencyUnit registerCurrency​(java.lang.String currencyCode, int numericCurrencyCode, int decimalPlaces, java.util.List<java.lang.String> countryCodes, boolean force)
      Registers a currency and associated countries allowing it to be used, allowing replacement.
      static java.util.List<java.lang.String> registeredCountries()
      Gets the list of all registered countries.
      static java.util.List<CurrencyUnit> registeredCurrencies()
      Gets the list of all registered currencies.
      java.util.Currency toCurrency()
      Gets the JDK currency instance equivalent to this currency.
      java.lang.String toString()
      Gets the currency code as a string.
      private java.lang.Object writeReplace()
      Uses a serialization delegate.

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • serialVersionUID

        private static final long serialVersionUID
        The serialisation version.
        See Also:
        Constant Field Values

      • CODE

        private static final java.util.regex.Pattern CODE
        The currency code pattern.

      • currenciesByCode

        private static final java.util.concurrent.ConcurrentMap<java.lang.String,​CurrencyUnit> currenciesByCode
        Map of registered currencies by text code.

      • currenciesByNumericCode

        private static final java.util.concurrent.ConcurrentMap<java.lang.Integer,​CurrencyUnit> currenciesByNumericCode
        Map of registered currencies by numeric code.

      • currenciesByCountry

        private static final java.util.concurrent.ConcurrentMap<java.lang.String,​CurrencyUnit> currenciesByCountry
        Map of registered currencies by country.

      • USD

        public static final CurrencyUnit USD
        The currency 'USD' - United States Dollar.

      • EUR

        public static final CurrencyUnit EUR
        The currency 'EUR' - Euro.

      • JPY

        public static final CurrencyUnit JPY
        The currency 'JPY' - Japanese Yen.

      • GBP

        public static final CurrencyUnit GBP
        The currency 'GBP' - British pound.

      • CHF

        public static final CurrencyUnit CHF
        The currency 'CHF' - Swiss Franc.

      • AUD

        public static final CurrencyUnit AUD
        The currency 'AUD' - Australian Dollar.

      • CAD

        public static final CurrencyUnit CAD
        The currency 'CAD' - Canadian Dollar.

      • code

        private final java.lang.String code
        The currency code, not null.

      • numericCode

        private final short numericCode
        The numeric currency code.

      • decimalPlaces

        private final short decimalPlaces
        The number of decimal places.

    • Constructor Detail

      • CurrencyUnit

        CurrencyUnit​(java.lang.String code,
             short numericCode,
             short decimalPlaces)
        Constructor, creating a new currency instance.
        Parameters:
        code - the three-letter currency code, not null
        numericCode - the numeric currency code, from 0 to 999, -1 if none
        decimalPlaces - the decimal places, not null

    • Method Detail

      • registerCurrency

        public static CurrencyUnit registerCurrency​(java.lang.String currencyCode,
                                            int numericCurrencyCode,
                                            int decimalPlaces,
                                            java.util.List<java.lang.String> countryCodes)
        Registers a currency and associated countries allowing it to be used.

        This class only permits known currencies to be returned. To achieve this, all currencies have to be registered in advance.

        Since this method is public, it is possible to add currencies in application code. It is recommended to do this only at startup, however it is safe to do so later as the internal implementation is thread-safe.

        The currency code must be three upper-case ASCII letters, based on ISO-4217. The numeric code must be from 0 to 999, or -1 if not applicable.

        Parameters:
        currencyCode - the three-letter upper-case currency code, not null
        numericCurrencyCode - the numeric currency code, from 0 to 999, -1 if none
        decimalPlaces - the number of decimal places that the currency normally has, from 0 to 30 (normally 0, 2 or 3), or -1 for a pseudo-currency
        countryCodes - the country codes to register the currency under, not null
        Returns:
        the new instance, never null
        Throws:
        java.lang.IllegalArgumentException - if the code is already registered, or the specified data is invalid

      • registerCurrency

        public static CurrencyUnit registerCurrency​(java.lang.String currencyCode,
                                            int numericCurrencyCode,
                                            int decimalPlaces,
                                            java.util.List<java.lang.String> countryCodes,
                                            boolean force)
        Registers a currency and associated countries allowing it to be used, allowing replacement.

        This class only permits known currencies to be returned. To achieve this, all currencies have to be registered in advance.

        Since this method is public, it is possible to add currencies in application code. It is recommended to do this only at startup, however it is safe to do so later as the internal implementation is thread-safe.

        This method uses a flag to determine whether the registered currency must be new, or can replace an existing currency.

        The currency code must be three upper-case ASCII letters, based on ISO-4217. The numeric code must be from 0 to 999, or -1 if not applicable.

        Parameters:
        currencyCode - the three-letter upper-case currency code, not null
        numericCurrencyCode - the numeric currency code, from 0 to 999, -1 if none
        decimalPlaces - the number of decimal places that the currency normally has, from 0 to 30 (normally 0, 2 or 3), or -1 for a pseudo-currency
        countryCodes - the country codes to register the currency under, use of ISO-3166 is recommended, not null
        force - true to register forcefully, replacing any existing matching currency, false to validate that there is no existing matching currency
        Returns:
        the new instance, never null
        Throws:
        java.lang.IllegalArgumentException - if the code is already registered and force is false; or if the specified data is invalid

      • registerCurrency

        public static CurrencyUnit registerCurrency​(java.lang.String currencyCode,
                                            int numericCurrencyCode,
                                            int decimalPlaces,
                                            boolean force)
        Registers a currency allowing it to be used, allowing replacement.

        This class only permits known currencies to be returned. To achieve this, all currencies have to be registered in advance.

        Since this method is public, it is possible to add currencies in application code. It is recommended to do this only at startup, however it is safe to do so later as the internal implementation is thread-safe.

        This method uses a flag to determine whether the registered currency must be new, or can replace an existing currency.

        The currency code must be three upper-case ASCII letters, based on ISO-4217. The numeric code must be from 0 to 999, or -1 if not applicable.

        Parameters:
        currencyCode - the three-letter upper-case currency code, not null
        numericCurrencyCode - the numeric currency code, from 0 to 999, -1 if none
        decimalPlaces - the number of decimal places that the currency normally has, from 0 to 30 (normally 0, 2 or 3), or -1 for a pseudo-currency use of ISO-3166 is recommended, not null
        force - true to register forcefully, replacing any existing matching currency, false to validate that there is no existing matching currency
        Returns:
        the new instance, never null
        Throws:
        java.lang.IllegalArgumentException - if the code is already registered and force is false; or if the specified data is invalid

      • registerCountry

        public static void registerCountry​(java.lang.String countryCode,
                                   CurrencyUnit currency)
        Registers a country code, typically ISO 3166-1-alpha-2.

        This registers a country code and the associated currency.

        The country code is typically from ISO 3166-1-alpha-2, and is therefore two upper-case ASCII letters.

        If the country code already exists, the data is replaced.

        Parameters:
        countryCode - the country code, two upper case letters if following ISO 3166-1-alpha-2, not null
        currency - the associated currency
        Throws:
        java.lang.IllegalArgumentException - if the code is already registered and force is false; or if the specified data is invalid

      • registeredCurrencies

        public static java.util.List<CurrencyUnit> registeredCurrencies()
        Gets the list of all registered currencies.

        This class only permits known currencies to be returned, thus this list is the complete list of valid singleton currencies. The list may change after application startup, however this isn't recommended.

        Returns:
        the sorted, independent, list of all registered currencies, never null

      • registeredCountries

        public static java.util.List<java.lang.String> registeredCountries()
        Gets the list of all registered countries.

        This returns the list of known countries. The list may change after application startup, however this isn't recommended.

        Returns:
        the sorted, independent, list of all registered countries, never null

      • of

        public static CurrencyUnit of​(java.util.Currency currency)
        Obtains an instance of CurrencyUnit matching the specified JDK currency.

        This converts the JDK currency instance to a currency unit using the code.

        Parameters:
        currency - the currency, not null
        Returns:
        the singleton instance, never null
        Throws:
        IllegalCurrencyException - if the currency is unknown

      • of

        public static CurrencyUnit of​(java.lang.String currencyCode)
        Obtains an instance of CurrencyUnit for the specified three letter currency code.

        A currency is uniquely identified by a three letter code, based on ISO-4217. Valid currency codes are three upper-case ASCII letters.

        Parameters:
        currencyCode - the three-letter currency code, not null
        Returns:
        the singleton instance, never null
        Throws:
        IllegalCurrencyException - if the currency is unknown

      • ofNumericCode

        public static CurrencyUnit ofNumericCode​(java.lang.String numericCurrencyCode)
        Obtains an instance of CurrencyUnit for the specified ISO-4217 numeric currency code.

        The numeric code is an alternative to the three letter code. This method is lenient and does not require the string to be left padded with zeroes.

        Parameters:
        numericCurrencyCode - the currency code, not null
        Returns:
        the singleton instance, never null
        Throws:
        IllegalCurrencyException - if the currency is unknown

      • ofNumericCode

        public static CurrencyUnit ofNumericCode​(int numericCurrencyCode)
        Obtains an instance of CurrencyUnit for the specified ISO-4217 numeric currency code.

        The numeric code is an alternative to the three letter code.

        Parameters:
        numericCurrencyCode - the numeric currency code, not null
        Returns:
        the singleton instance, never null
        Throws:
        IllegalCurrencyException - if the currency is unknown

      • of

        public static CurrencyUnit of​(java.util.Locale locale)
        Obtains an instance of CurrencyUnit for the specified locale.

        Only the country is used from the locale.

        Parameters:
        locale - the locale, not null
        Returns:
        the singleton instance, never null
        Throws:
        IllegalCurrencyException - if the currency is unknown

      • ofCountry

        public static CurrencyUnit ofCountry​(java.lang.String countryCode)
        Obtains an instance of CurrencyUnit for the specified ISO-3166 country code.

        Country codes should generally be in upper case. This method is case sensitive.

        Parameters:
        countryCode - the country code, typically ISO-3166, not null
        Returns:
        the singleton instance, never null
        Throws:
        IllegalCurrencyException - if the currency is unknown

      • readObject

        private void readObject​(java.io.ObjectInputStream ois)
                 throws java.io.InvalidObjectException
        Block malicious data streams.
        Parameters:
        ois - the input stream, not null
        Throws:
        java.io.InvalidObjectException - if an error occurs

      • writeReplace

        private java.lang.Object writeReplace()
        Uses a serialization delegate.
        Returns:
        the replacing object, never null

      • getCode

        public java.lang.String getCode()
        Gets the ISO-4217 three-letter currency code.

        Each currency is uniquely identified by a three-letter upper-case code, based on ISO-4217.

        Returns:
        the three-letter upper-case currency code, never null

      • getNumericCode

        public int getNumericCode()
        Gets the ISO-4217 numeric currency code.

        The numeric code is an alternative to the standard string-based code.

        Returns:
        the numeric currency code, -1 if no numeric code

      • getNumeric3Code

        public java.lang.String getNumeric3Code()
        Gets the ISO-4217 numeric currency code as a three digit string.

        This formats the numeric code as a three digit string prefixed by zeroes if necessary. If there is no valid code, then an empty string is returned.

        Returns:
        the three digit numeric currency code, empty is no code, never null

      • getCountryCodes

        public java.util.Set<java.lang.String> getCountryCodes()
        Gets the country codes applicable to this currency.

        A currency is typically valid in one or more countries. The codes are typically defined by ISO-3166. An empty set indicates that no the currency is not associated with a country code.

        Returns:
        the country codes, may be empty, not null

      • getDecimalPlaces

        public int getDecimalPlaces()
        Gets the number of decimal places typically used by this currency.

        Different currencies have different numbers of decimal places by default. For example, 'GBP' has 2 decimal places, but 'JPY' has zero. Pseudo-currencies will return zero.

        Returns:
        the decimal places, from 0 to 9 (normally 0, 2 or 3)

      • isPseudoCurrency

        public boolean isPseudoCurrency()
        Checks if this is a pseudo-currency.
        Returns:
        true if this is a pseudo-currency

      • getSymbol

        public java.lang.String getSymbol()
        Gets the symbol for this locale from the JDK.

        If this currency doesn't have a JDK equivalent, then the currency code is returned.

        This method matches the API of Currency.

        Returns:
        the JDK currency instance, never null

      • getSymbol

        public java.lang.String getSymbol​(java.util.Locale locale)
        Gets the symbol for this locale from the JDK.

        If this currency doesn't have a JDK equivalent, then the currency code is returned.

        This method matches the API of Currency.

        Parameters:
        locale - the locale to get the symbol for, not null
        Returns:
        the JDK currency instance, never null

      • toCurrency

        public java.util.Currency toCurrency()
        Gets the JDK currency instance equivalent to this currency.

        This attempts to convert a CurrencyUnit to a JDK Currency.

        Returns:
        the JDK currency instance, never null
        Throws:
        java.lang.IllegalArgumentException - if no matching currency exists in the JDK

      • compareTo

        public int compareTo​(CurrencyUnit other)
        Compares this currency to another by alphabetical comparison of the code.
        Specified by:
        compareTo in interface java.lang.Comparable<CurrencyUnit>
        Parameters:
        other - the other currency, not null
        Returns:
        negative if earlier alphabetically, 0 if equal, positive if greater alphabetically

      • equals

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

        The comparison checks the 3 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()
        Gets the currency code as a string.
        Overrides:
        toString in class java.lang.Object
        Returns:
        the currency code, never null