Top Description Inners Fields Constructors Methods
java.util

public final Class Currency

extends Object
implements Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable
Imports
java.io.BufferedInputStream, .DataInputStream, .File, .FileReader, .InputStream, .IOException, .Serializable, java.security.AccessController, .PrivilegedAction, java.text.ParseException, .SimpleDateFormat, java.util.concurrent.ConcurrentHashMap, .ConcurrentMap, java.util.regex.Pattern, .Matcher, java.util.spi.CurrencyNameProvider, java.util.stream.Collectors, jdk.internal.util.StaticProperty, sun.util.locale.provider.CalendarDataUtility, .LocaleServiceProviderPool, sun.util.logging.PlatformLogger

Represents a currency. Currencies are identified by their ISO 4217 currency codes. Visit the ISO web site for more information.

The class is designed so that there's never more than one Currency instance for any given currency. Therefore, there's no public constructor. You obtain a Currency instance using the getInstance methods.

Users can supersede the Java runtime currency data by means of the system property java.util.currency.data. If this system property is defined then its value is the location of a properties file, the contents of which are key/value pairs of the ISO 3166 country codes and the ISO 4217 currency data respectively. The value part consists of three ISO 4217 values of a currency, i.e., an alphabetic code, a numeric code, and a minor unit. Those three ISO 4217 values are separated by commas. The lines which start with '#'s are considered comment lines. An optional UTC timestamp may be specified per currency entry if users need to specify a cutover date indicating when the new data comes into effect. The timestamp is appended to the end of the currency properties and uses a comma as a separator. If a UTC datestamp is present and valid, the JRE will only use the new currency properties if the current UTC date is later than the date specified at class loading time. The format of the timestamp must be of ISO 8601 format : 'yyyy-MM-dd'T'HH:mm:ss'. For example,

#Sample currency properties
JP=JPZ,999,0

will supersede the currency data for Japan. If JPZ is one of the existing ISO 4217 currency code referred by other countries, the existing JPZ currency data is updated with the given numeric code and minor unit value.

#Sample currency properties with cutover date
JP=JPZ,999,0,2014-01-01T00:00:00

will supersede the currency data for Japan if Currency class is loaded after 1st January 2014 00:00:00 GMT.

Where syntactically malformed entries are encountered, the entry is ignored and the remainder of entries in file are processed. For instances where duplicate country code entries exist, the behavior of the Currency information for that Currency is undefined and the remainder of entries in file are processed.

If multiple property entries with same currency code but different numeric code and/or minor unit are encountered, those entries are ignored and the remainder of entries in file are processed.

It is recommended to use java.math.BigDecimal class while dealing with Currency or monetary values as it provides better handling of floating point numbers and their operations.

Since
1.4
External Specification
ISO - ISO 4217 - Currency codes
See Also
java.math.BigDecimal

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
Currency.CurrencyNameGetter

Obtains a localized currency names from a CurrencyNameProvider implementation.

private static class
private static class
private static class

Field Summary

Modifier and TypeField and Description
private static final int
private static HashSet<Currency>
private static final int
private static final int
private final String
currencyCode

ISO 4217 currency code for this currency.

pack-priv static int
private final transient int
defaultFractionDigits

Default fraction digits for this currency.

private static final int
pack-priv static int
private static ConcurrentMap<String, Currency>
private static final int
private static final int
pack-priv static int[]
private static final int
private static final int
private final transient int
numericCode

ISO 4217 numeric code for this currency.

pack-priv static List<Currency.OtherCurrencyEntry>
private static final long
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
pack-priv static List<Currency.SpecialCaseEntry>
private static final int
SYMBOL

Constants for retrieving localized names from the name providers.

private static final int

Constructor Summary

AccessConstructor and Description
private
Currency(String currencyCode, int defaultFractionDigits, int numericCode)

Constructs a Currency instance.

Method Summary

Modifier and TypeMethod and Description
public static Set<Currency>

Returns:

the set of available currencies. If there is no currency available in the runtime, the returned set is empty.
getAvailableCurrencies
()

Gets the set of available currencies.

public String

Returns:

the ISO 4217 currency code of this currency.
getCurrencyCode
()

Gets the ISO 4217 currency code of this currency.

public int

Returns:

the default number of fraction digits used with this currency
getDefaultFractionDigits
()

Gets the default number of fraction digits used with this currency.

public String

Returns:

the display name of this currency for the default DISPLAY locale
getDisplayName
()

Gets the name that is suitable for displaying this currency for the default DISPLAY locale.

public String

Returns:

the display name of this currency for the specified locale
getDisplayName
(Locale
the locale for which a display name for this currency is needed
locale
)

Gets the name that is suitable for displaying this currency for the specified locale.

public static Currency

Returns:

the Currency instance for the given currency code
getInstance
(String
the ISO 4217 code of the currency
currencyCode
)

Returns the Currency instance for the given currency code.

private static Currency
getInstance(String currencyCode, int defaultFractionDigits, int numericCode)

public static Currency

Returns:

the Currency instance for the country of the given locale, or null
getInstance
(Locale
the locale for whose country a Currency instance is needed
locale
)

Returns the Currency instance for the country of the given locale.

private static int
getMainTableEntry(char char1, char char2)

Gets the main table entry for the country whose country code consists of char1 and char2.

public int

Returns:

the ISO 4217 numeric code of this currency
getNumericCode
()

Returns the ISO 4217 numeric code of this currency.

public String

Returns:

the 3 digit ISO 4217 numeric code of this currency as a String
getNumericCodeAsString
()

Returns the 3 digit ISO 4217 numeric code of this currency as a String.

public String

Returns:

the symbol of this currency for the default DISPLAY locale
getSymbol
()

Gets the symbol of this currency for the default DISPLAY locale.

public String

Returns:

the symbol of this currency for the specified locale
getSymbol
(Locale
the locale for which a display name for this currency is needed
locale
)

Gets the symbol of this currency for the specified locale.

private static List<Currency.CurrencyProperty>

Returns:

list of parsed property entries
getValidCurrencyData
(Properties
properties containing currency data
props
,
Pattern
regex pattern for the properties entry
pattern
)

Parse currency data found in the properties file (that java.util.currency.data designates) to a List of CurrencyProperty instances.

private static void
private static int[]
readIntArray(DataInputStream dis, int count)

private static List<Currency.OtherCurrencyEntry>
private Object
readResolve()

Resolves instances being deserialized to a single instance per currency.

private static List<Currency.SpecialCaseEntry>
private static void
replaceCurrencyData(Currency.CurrencyProperty
CurrencyProperty instance of the valid property entry
prop
)

Replaces currency data found in the properties file that java.util.currency.data designates.

private static void
setMainTableEntry(char char1, char char2, int entry)

Sets the main table entry for the country whose country code consists of char1 and char2.

public String

Returns:

the ISO 4217 currency code of this currency
toString
()

Overrides java.lang.Object.toString.

Returns the ISO 4217 currency code of this currency.

private static void
updateMainTableEntry(String code, int fraction, int numeric)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

A_TO_Zback to summary
private static final int A_TO_Z
availableback to summary
private static HashSet<Currency> available
COUNTRY_TYPE_MASKback to summary
private static final int COUNTRY_TYPE_MASK
COUNTRY_WITHOUT_CURRENCY_ENTRYback to summary
private static final int COUNTRY_WITHOUT_CURRENCY_ENTRY
currencyCodeback to summary
private final String currencyCode

ISO 4217 currency code for this currency.

dataVersionback to summary
pack-priv static int dataVersion
defaultFractionDigitsback to summary
private final transient int defaultFractionDigits

Default fraction digits for this currency. Set from currency data tables.

DISPLAYNAMEback to summary
private static final int DISPLAYNAME
formatVersionback to summary
pack-priv static int formatVersion
instancesback to summary
private static ConcurrentMap<String, Currency> instances
INVALID_COUNTRY_ENTRYback to summary
private static final int INVALID_COUNTRY_ENTRY
MAGIC_NUMBERback to summary
private static final int MAGIC_NUMBER
mainTableback to summary
pack-priv static int[] mainTable
NUMERIC_CODE_MASKback to summary
private static final int NUMERIC_CODE_MASK
NUMERIC_CODE_SHIFTback to summary
private static final int NUMERIC_CODE_SHIFT
numericCodeback to summary
private final transient int numericCode

ISO 4217 numeric code for this currency. Set from currency data tables.

otherCurrenciesListback to summary
pack-priv static List<Currency.OtherCurrencyEntry> otherCurrenciesList
serialVersionUIDback to summary
private static final long serialVersionUID
Annotations
@Serial
SIMPLE_CASE_COUNTRY_DEFAULT_DIGITS_MASKback to summary
private static final int SIMPLE_CASE_COUNTRY_DEFAULT_DIGITS_MASK
SIMPLE_CASE_COUNTRY_DEFAULT_DIGITS_SHIFTback to summary
private static final int SIMPLE_CASE_COUNTRY_DEFAULT_DIGITS_SHIFT
SIMPLE_CASE_COUNTRY_FINAL_CHAR_MASKback to summary
private static final int SIMPLE_CASE_COUNTRY_FINAL_CHAR_MASK
SIMPLE_CASE_COUNTRY_MASKback to summary
private static final int SIMPLE_CASE_COUNTRY_MASK
SIMPLE_CASE_COUNTRY_MAX_DEFAULT_DIGITSback to summary
private static final int SIMPLE_CASE_COUNTRY_MAX_DEFAULT_DIGITS
SPECIAL_CASE_COUNTRY_INDEX_DELTAback to summary
private static final int SPECIAL_CASE_COUNTRY_INDEX_DELTA
SPECIAL_CASE_COUNTRY_INDEX_MASKback to summary
private static final int SPECIAL_CASE_COUNTRY_INDEX_MASK
SPECIAL_CASE_COUNTRY_MASKback to summary
private static final int SPECIAL_CASE_COUNTRY_MASK
specialCasesListback to summary
pack-priv static List<Currency.SpecialCaseEntry> specialCasesList
SYMBOLback to summary
private static final int SYMBOL

Constants for retrieving localized names from the name providers.

VALID_FORMAT_VERSIONback to summary
private static final int VALID_FORMAT_VERSION

Constructor Detail

Currencyback to summary
private Currency(String currencyCode, int defaultFractionDigits, int numericCode)

Constructs a Currency instance. The constructor is private so that we can ensure that there's never more than one instance for a given currency.

Method Detail

getAvailableCurrenciesback to summary
public static Set<Currency> getAvailableCurrencies()

Gets the set of available currencies. The returned set of currencies contains all of the available currencies, which may include currencies that represent obsolete ISO 4217 codes. The set can be modified without affecting the available currencies in the runtime.

Returns:Set<Currency>

the set of available currencies. If there is no currency available in the runtime, the returned set is empty.

Since
1.7
getCurrencyCodeback to summary
public String getCurrencyCode()

Gets the ISO 4217 currency code of this currency.

Returns:String

the ISO 4217 currency code of this currency.

getDefaultFractionDigitsback to summary
public int getDefaultFractionDigits()

Gets the default number of fraction digits used with this currency. Note that the number of fraction digits is the same as ISO 4217's minor unit for the currency. For example, the default number of fraction digits for the Euro is 2, while for the Japanese Yen it's 0. In the case of pseudo-currencies, such as IMF Special Drawing Rights, -1 is returned.

Returns:int

the default number of fraction digits used with this currency

getDisplayNameback to summary
public String getDisplayName()

Gets the name that is suitable for displaying this currency for the default DISPLAY locale. If there is no suitable display name found for the default locale, the ISO 4217 currency code is returned.

This is equivalent to calling getDisplayName(Locale.getDefault(Locale.Category.DISPLAY)).

Returns:String

the display name of this currency for the default DISPLAY locale

Since
1.7
getDisplayNameback to summary
public String getDisplayName(Locale locale)

Gets the name that is suitable for displaying this currency for the specified locale. If there is no suitable display name found for the specified locale, the ISO 4217 currency code is returned.

Parameters
locale:Locale

the locale for which a display name for this currency is needed

Returns:String

the display name of this currency for the specified locale

Exceptions
NullPointerException:
if locale is null
Since
1.7
getInstanceback to summary
public static Currency getInstance(String currencyCode)

Returns the Currency instance for the given currency code.

Parameters
currencyCode:String

the ISO 4217 code of the currency

Returns:Currency

the Currency instance for the given currency code

Exceptions
NullPointerException:
if currencyCode is null
IllegalArgumentException:
if currencyCode is not a supported ISO 4217 code.
getInstanceback to summary
private static Currency getInstance(String currencyCode, int defaultFractionDigits, int numericCode)
getInstanceback to summary
public static Currency getInstance(Locale locale)

Returns the Currency instance for the country of the given locale. The language and variant components of the locale are ignored. The result may vary over time, as countries change their currencies. For example, for the original member countries of the European Monetary Union, the method returns the old national currencies until December 31, 2001, and the Euro from January 1, 2002, local time of the respective countries.

If the specified locale contains "cu" and/or "rg" Unicode extensions, the instance returned from this method reflects the values specified with those extensions. If both "cu" and "rg" are specified, the currency from the "cu" extension supersedes the implicit one from the "rg" extension.

The method returns null for territories that don't have a currency, such as Antarctica.

Parameters
locale:Locale

the locale for whose country a Currency instance is needed

Returns:Currency

the Currency instance for the country of the given locale, or null

Exceptions
NullPointerException:
if locale is null
IllegalArgumentException:
if the country of the given locale is not a supported ISO 3166 country code.
getMainTableEntryback to summary
private static int getMainTableEntry(char char1, char char2)

Gets the main table entry for the country whose country code consists of char1 and char2.

getNumericCodeback to summary
public int getNumericCode()

Returns the ISO 4217 numeric code of this currency.

Returns:int

the ISO 4217 numeric code of this currency

Since
1.7
getNumericCodeAsStringback to summary
public String getNumericCodeAsString()

Returns the 3 digit ISO 4217 numeric code of this currency as a String. Unlike getNumericCode(), which returns the numeric code as int, this method always returns the numeric code as a 3 digit string. e.g. a numeric value of 32 would be returned as "032", and a numeric value of 6 would be returned as "006".

Returns:String

the 3 digit ISO 4217 numeric code of this currency as a String

Since
9
getSymbolback to summary
public String getSymbol()

Gets the symbol of this currency for the default DISPLAY locale. For example, for the US Dollar, the symbol is "$" if the default locale is the US, while for other locales it may be "US$". If no symbol can be determined, the ISO 4217 currency code is returned.

If the default DISPLAY locale contains "rg" (region override) Unicode extensions, the symbol returned from this method reflects the value specified with that extension.

This is equivalent to calling getSymbol(Locale.getDefault(Locale.Category.DISPLAY)).

Returns:String

the symbol of this currency for the default DISPLAY locale

getSymbolback to summary
public String getSymbol(Locale locale)

Gets the symbol of this currency for the specified locale. For example, for the US Dollar, the symbol is "$" if the specified locale is the US, while for other locales it may be "US$". If no symbol can be determined, the ISO 4217 currency code is returned.

If the specified locale contains "rg" (region override) Unicode extensions, the symbol returned from this method reflects the value specified with that extension.

Parameters
locale:Locale

the locale for which a display name for this currency is needed

Returns:String

the symbol of this currency for the specified locale

Exceptions
NullPointerException:
if locale is null
getValidCurrencyDataback to summary
private static List<Currency.CurrencyProperty> getValidCurrencyData(Properties props, Pattern pattern)

Parse currency data found in the properties file (that java.util.currency.data designates) to a List of CurrencyProperty instances. Also, remove invalid entries and the multiple currency code inconsistencies.

Parameters
props:Properties

properties containing currency data

pattern:Pattern

regex pattern for the properties entry

Returns:List<Currency.CurrencyProperty>

list of parsed property entries

initStaticback to summary
private static void initStatic()
Annotations
@SuppressWarnings:removal
readIntArrayback to summary
private static int[] readIntArray(DataInputStream dis, int count) throws IOException
readOtherCurrenciesback to summary
private static List<Currency.OtherCurrencyEntry> readOtherCurrencies(DataInputStream dis, int count) throws IOException
readResolveback to summary
private Object readResolve()

Resolves instances being deserialized to a single instance per currency.

Annotations
@Serial
readSpecialCasesback to summary
private static List<Currency.SpecialCaseEntry> readSpecialCases(DataInputStream dis, int count) throws IOException
replaceCurrencyDataback to summary
private static void replaceCurrencyData(Currency.CurrencyProperty prop)

Replaces currency data found in the properties file that java.util.currency.data designates. This method is invoked for each valid currency entry.

Parameters
prop:Currency.CurrencyProperty

CurrencyProperty instance of the valid property entry

setMainTableEntryback to summary
private static void setMainTableEntry(char char1, char char2, int entry)

Sets the main table entry for the country whose country code consists of char1 and char2.

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns the ISO 4217 currency code of this currency.

Returns:String

the ISO 4217 currency code of this currency

Annotations
@Override
updateMainTableEntryback to summary
private static void updateMainTableEntry(String code, int fraction, int numeric)
java.util back to summary

private Class Currency.CurrencyNameGetter

extends Object
implements LocaleServiceProviderPool.LocalizedObjectGetter<CurrencyNameProvider, String>
Class Inheritance
All Implemented Interfaces
sun.util.locale.provider.LocaleServiceProviderPool.LocalizedObjectGetter

Obtains a localized currency names from a CurrencyNameProvider implementation.

Field Summary

Modifier and TypeField and Description
private static final Currency.CurrencyNameGetter

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public String
getObject(CurrencyNameProvider
the provider
currencyNameProvider
,
Locale
the locale
locale
,
String
key string to localize, or null if the provider is not a name provider
key
,
Object...
provider specific params
params
)

Implements sun.util.locale.provider.LocaleServiceProviderPool.LocalizedObjectGetter.getObject.

Returns an object from the provider

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

INSTANCEback to summary
private static final Currency.CurrencyNameGetter INSTANCE

Constructor Detail

CurrencyNameGetterback to summary
private CurrencyNameGetter()

Method Detail

getObjectback to summary
public String getObject(CurrencyNameProvider currencyNameProvider, Locale locale, String key, Object... params)

Implements sun.util.locale.provider.LocaleServiceProviderPool.LocalizedObjectGetter.getObject.

Doc from sun.util.locale.provider.LocaleServiceProviderPool.LocalizedObjectGetter.getObject.

Returns an object from the provider

Parameters
currencyNameProvider:CurrencyNameProvider

the provider

locale:Locale

the locale

key:String

key string to localize, or null if the provider is not a name provider

params:Object[]

provider specific params

Returns:String

localized object from the provider

Annotations
@Override
java.util back to summary

private Class Currency.CurrencyProperty

extends Object
Class Inheritance

Field Summary

Modifier and TypeField and Description
private final String
private final String
private final String
private final int
private final int

Constructor Summary

AccessConstructor and Description
private
CurrencyProperty(String country, String currencyCode, int fraction, int numericCode, String date)

Method Summary

Modifier and TypeMethod and Description
private static boolean
containsInconsistentInstances(List<Currency.CurrencyProperty> list)

Checks if the given list contains multiple inconsistent currency instances

private static Optional<Currency.CurrencyProperty>

Returns:

Optional containing CurrencyProperty instance, If valid; empty otherwise
getValidEntry
(String
country representing the currency data
ctry
,
String
currency data of the given ctry
curData
,
Pattern
regex pattern for the properties entry
pattern
)

Check the valid currency data and create/return an Optional instance of CurrencyProperty

private static void
info(String message, Throwable t)

private static boolean
private static Currency.CurrencyProperty
parseProperty(String ctry, String curData, Pattern pattern)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

countryback to summary
private final String country
currencyCodeback to summary
private final String currencyCode
dateback to summary
private final String date
fractionback to summary
private final int fraction
numericCodeback to summary
private final int numericCode

Constructor Detail

CurrencyPropertyback to summary
private CurrencyProperty(String country, String currencyCode, int fraction, int numericCode, String date)

Method Detail

containsInconsistentInstancesback to summary
private static boolean containsInconsistentInstances(List<Currency.CurrencyProperty> list)

Checks if the given list contains multiple inconsistent currency instances

getValidEntryback to summary
private static Optional<Currency.CurrencyProperty> getValidEntry(String ctry, String curData, Pattern pattern)

Check the valid currency data and create/return an Optional instance of CurrencyProperty

Parameters
ctry:String

country representing the currency data

curData:String

currency data of the given ctry

pattern:Pattern

regex pattern for the properties entry

Returns:Optional<Currency.CurrencyProperty>

Optional containing CurrencyProperty instance, If valid; empty otherwise

infoback to summary
private static void info(String message, Throwable t)
isPastCutoverDateback to summary
private static boolean isPastCutoverDate(String s) throws ParseException
parsePropertyback to summary
private static Currency.CurrencyProperty parseProperty(String ctry, String curData, Pattern pattern)
java.util back to summary

private Class Currency.OtherCurrencyEntry

extends Object
Class Inheritance

Field Summary

Modifier and TypeField and Description
private final String
private final int
private final int

Constructor Summary

AccessConstructor and Description
private
OtherCurrencyEntry(String currencyCode, int fraction, int numericCode)

Method Summary

Modifier and TypeMethod and Description
private static Currency.OtherCurrencyEntry
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

currencyCodeback to summary
private final String currencyCode
fractionback to summary
private final int fraction
numericCodeback to summary
private final int numericCode

Constructor Detail

OtherCurrencyEntryback to summary
private OtherCurrencyEntry(String currencyCode, int fraction, int numericCode)

Method Detail

findEntryback to summary
private static Currency.OtherCurrencyEntry findEntry(String code)
java.util back to summary

private Class Currency.SpecialCaseEntry

extends Object
Class Inheritance

Field Summary

Modifier and TypeField and Description
private final long
private final String
private final int
private final int
private final String
private final int
private final int

Constructor Summary

AccessConstructor and Description
private
SpecialCaseEntry(long cutOverTime, String oldCurrency, String newCurrency, int oldCurrencyFraction, int newCurrencyFraction, int oldCurrencyNumericCode, int newCurrencyNumericCode)

private
SpecialCaseEntry(String currencyCode, int fraction, int numericCode)

Method Summary

Modifier and TypeMethod and Description
private static int
private static int[]
private static int
indexOf(String code, int fraction, int numeric)

private static int
toIndex(int tableEntry)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

cutOverTimeback to summary
private final long cutOverTime
newCurrencyback to summary
private final String newCurrency
newCurrencyFractionback to summary
private final int newCurrencyFraction
newCurrencyNumericCodeback to summary
private final int newCurrencyNumericCode
oldCurrencyback to summary
private final String oldCurrency
oldCurrencyFractionback to summary
private final int oldCurrencyFraction
oldCurrencyNumericCodeback to summary
private final int oldCurrencyNumericCode

Constructor Detail

SpecialCaseEntryback to summary
private SpecialCaseEntry(long cutOverTime, String oldCurrency, String newCurrency, int oldCurrencyFraction, int newCurrencyFraction, int oldCurrencyNumericCode, int newCurrencyNumericCode)
SpecialCaseEntryback to summary
private SpecialCaseEntry(String currencyCode, int fraction, int numericCode)

Method Detail

currencyCodeIndexback to summary
private static int currencyCodeIndex(String code)
findEntryback to summary
private static int[] findEntry(String code)
indexOfback to summary
private static int indexOf(String code, int fraction, int numeric)
toIndexback to summary
private static int toIndex(int tableEntry)