org.joda.money
Class CurrencyUnit

java.lang.Object
  extended by org.joda.money.CurrencyUnit
All Implemented Interfaces:
Serializable, Comparable<CurrencyUnit>

public final class CurrencyUnit
extends Object
implements Comparable<CurrencyUnit>, 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

Field Summary
static CurrencyUnit AUD
          The currency 'AUD' - Australian Dollar.
static CurrencyUnit CAD
          The currency 'CAD' - Canadian Dollar.
static CurrencyUnit CHF
          The currency 'CHF' - Swiss Franc.
static CurrencyUnit EUR
          The currency 'EUR' - Euro.
static CurrencyUnit GBP
          The currency 'GBP' - British pound.
static CurrencyUnit JPY
          The currency 'JPY' - Japanese Yen.
static CurrencyUnit USD
          The currency 'USD' - United States Dollar.
 
Method Summary
 int compareTo(CurrencyUnit other)
          Compares this currency to another by alphabetical comparison of the code.
 boolean equals(Object obj)
          Checks if this currency equals another currency.
 String getCode()
          Gets the ISO-4217 three letter currency code.
 String getCurrencyCode()
          Gets the ISO-4217 three-letter currency code.
 int getDecimalPlaces()
          Gets the number of decimal places typically used by this currency.
 int getDefaultFractionDigits()
          Gets the number of fractional digits typically used by this currency.
static CurrencyUnit getInstance(Locale locale)
          Obtains an instance of CurrencyUnit for the specified locale.
static CurrencyUnit getInstance(String currencyCode)
          Obtains an instance of CurrencyUnit for the specified currency code.
 String getNumeric3Code()
          Gets the ISO-4217 numeric currency code as a three digit string.
 int getNumericCode()
          Gets the ISO-4217 numeric currency code.
 String getSymbol()
          Gets the symbol for this locale from the JDK.
 String getSymbol(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(Currency currency)
          Obtains an instance of CurrencyUnit matching the specified JDK currency.
static CurrencyUnit of(Locale locale)
          Obtains an instance of CurrencyUnit for the specified locale.
static CurrencyUnit of(String currencyCode)
          Obtains an instance of CurrencyUnit for the specified ISO-4217 three letter currency code.
static CurrencyUnit ofCountry(String countryCode)
          Obtains an instance of CurrencyUnit for the specified country code.
static CurrencyUnit ofNumericCode(int numericCurrencyCode)
          Obtains an instance of CurrencyUnit for the specified ISO-4217 numeric currency code.
static CurrencyUnit ofNumericCode(String numericCurrencyCode)
          Obtains an instance of CurrencyUnit for the specified ISO-4217 numeric currency code.
static List<CurrencyUnit> registeredCurrencies()
          Gets the list of all registered currencies.
 Currency toCurrency()
          Gets the JDK currency instance equivalent to this currency.
 String toString()
          Gets the currency code as a string.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

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.

Method Detail

registeredCurrencies

public static 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

of

public static CurrencyUnit of(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

of

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

A currency is uniquely identified by ISO-4217 three letter code.

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

ofNumericCode

public static CurrencyUnit ofNumericCode(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(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(String countryCode)
Obtains an instance of CurrencyUnit for the specified country code.

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

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

getInstance

public static CurrencyUnit getInstance(String currencyCode)
Obtains an instance of CurrencyUnit for the specified currency code.

This method exists to match the API of Currency.

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

getInstance

public static CurrencyUnit getInstance(Locale locale)
Obtains an instance of CurrencyUnit for the specified locale.

This method exists to match the API of Currency.

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

getCode

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

Each currency is uniquely identified by a three-letter code.

Returns:
the three letter ISO-4217 currency code, never null

getNumericCode

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

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

Returns:
the numeric currency code

getNumeric3Code

public 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

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.

See also getDefaultFractionDigits().

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

getCurrencyCode

public String getCurrencyCode()
Gets the ISO-4217 three-letter currency code.

This method matches the API of Currency.

Returns:
the currency code, never null

getDefaultFractionDigits

public int getDefaultFractionDigits()
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. Pseudo-currencies are indicated by -1.

This method matches the API of Currency. The alternative method getDecimalPlaces() may be more useful.

Returns:
the fractional digits, from 0 to 9 (normally 0, 2 or 3), or -1 for pseudo-currencies

getSymbol

public 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 String getSymbol(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 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:
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 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(Object obj)
Checks if this currency equals another currency.

The comparison checks the 3 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()
Gets the currency code as a string.

Overrides:
toString in class Object
Returns:
the currency code, never null


Copyright © 2009-2013 Joda.org. All Rights Reserved.