001 /* Currency.java -- Representation of a currency 002 Copyright (C) 2003, 2004, 2005 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 039 package java.util; 040 041 import gnu.java.locale.LocaleHelper; 042 043 import java.io.IOException; 044 import java.io.ObjectStreamException; 045 import java.io.Serializable; 046 047 import java.util.spi.CurrencyNameProvider; 048 049 /** 050 * Representation of a currency for a particular locale. Each currency 051 * is identified by its ISO 4217 code, and only one instance of this 052 * class exists per currency. As a result, instances are created 053 * via the <code>getInstance()</code> methods rather than by using 054 * a constructor. 055 * 056 * @see java.util.Locale 057 * @author Guilhem Lavaux (guilhem.lavaux@free.fr) 058 * @author Dalibor Topic (robilad@kaffe.org) 059 * @author Bryce McKinlay (mckinlay@redhat.com) 060 * @author Andrew John Hughes (gnu_andrew@member.fsf.org) 061 * @since 1.4 062 */ 063 public final class Currency 064 implements Serializable 065 { 066 /** 067 * For compatability with Sun's JDK 068 */ 069 static final long serialVersionUID = -158308464356906721L; 070 071 /** 072 * The set of properties which map a currency to 073 * the currency information such as the ISO 4217 074 * currency code and the number of decimal points. 075 * 076 * @see #getCurrencyCode() 077 * @serial ignored. 078 */ 079 private static transient Properties properties; 080 081 /** 082 * The ISO 4217 currency code associated with this 083 * particular instance. 084 * 085 * @see #getCurrencyCode() 086 * @serial the ISO 4217 currency code 087 */ 088 private String currencyCode; 089 090 /** 091 * The number of fraction digits associated with this 092 * particular instance. 093 * 094 * @see #getDefaultFractionDigits() 095 * @serial the number of fraction digits 096 */ 097 private transient int fractionDigits; 098 099 /** 100 * A cached map of country codes 101 * instances to international currency code 102 * <code>String</code>s. Seperating this 103 * from the <code>Currency</code> instances 104 * ensures we have a common lookup between 105 * the two <code>getInstance()</code> methods. 106 * 107 * @see #getInstance(java.util.Locale) 108 * @serial ignored. 109 */ 110 private static transient Map countryMap; 111 112 /** 113 * A cache of <code>Currency</code> instances to 114 * ensure the singleton nature of this class. The key 115 * is the international currency code. 116 * 117 * @see #getInstance(java.util.Locale) 118 * @see #getInstance(java.lang.String) 119 * @see #readResolve() 120 * @serial ignored. 121 */ 122 private static transient Map cache; 123 124 /** 125 * Instantiates the cache and reads in the properties. 126 */ 127 static 128 { 129 /* Create a hash map for the locale mappings */ 130 countryMap = new HashMap(); 131 /* Create a hash map for the cache */ 132 cache = new HashMap(); 133 /* Create the properties object */ 134 properties = new Properties(); 135 /* Try and load the properties from our iso4217.properties resource */ 136 try 137 { 138 properties.load(Currency.class.getResourceAsStream("iso4217.properties")); 139 } 140 catch (IOException exception) 141 { 142 throw new InternalError("Failed to load currency resource: " + exception); 143 } 144 } 145 146 /** 147 * Default constructor for deserialization 148 */ 149 private Currency() 150 { 151 } 152 153 /** 154 * Constructor to create a <code>Currency</code> object 155 * for a particular <code>Locale</code>. 156 * All components of the given locale, other than the 157 * country code, are ignored. The results of calling this 158 * method may vary over time, as the currency associated with 159 * a particular country changes. For countries without 160 * a given currency (e.g. Antarctica), the result is null. 161 * 162 * @param loc the locale for the new currency, or null if 163 * there is no country code specified or a currency 164 * for this country. 165 */ 166 private Currency(Locale loc) 167 { 168 String countryCode; 169 String currencyKey; 170 String fractionDigitsKey; 171 int commaPosition; 172 173 /* Retrieve the country code from the locale */ 174 countryCode = loc.getCountry(); 175 /* If there is no country code, return */ 176 if (countryCode.equals("")) 177 { 178 throw new 179 IllegalArgumentException("Invalid (empty) country code for locale:" 180 + loc); 181 } 182 /* Construct the key for the currency */ 183 currencyKey = countryCode + ".currency"; 184 /* Construct the key for the fraction digits */ 185 fractionDigitsKey = countryCode + ".fractionDigits"; 186 /* Retrieve the currency */ 187 currencyCode = properties.getProperty(currencyKey); 188 /* Return if the currency code is null */ 189 if (currencyCode == null) 190 { 191 return; 192 } 193 /* Split off the first currency code (we only use the first for now) */ 194 commaPosition = currencyCode.indexOf(","); 195 if (commaPosition != -1) 196 { 197 currencyCode = currencyCode.substring(0, commaPosition); 198 } 199 /* Retrieve the fraction digits */ 200 fractionDigits = Integer.parseInt(properties.getProperty(fractionDigitsKey)); 201 } 202 203 /** 204 * Constructor for the "XXX" special case. This allows 205 * a Currency to be constructed from an assumed good 206 * currency code. 207 * 208 * @param code the code to use. 209 */ 210 private Currency(String code) 211 { 212 currencyCode = code; 213 fractionDigits = -1; /* Pseudo currency */ 214 } 215 216 /** 217 * Returns the ISO4217 currency code of this currency. 218 * 219 * @return a <code>String</code> containing currency code. 220 */ 221 public String getCurrencyCode() 222 { 223 return currencyCode; 224 } 225 226 /** 227 * Returns the number of digits which occur after the decimal point 228 * for this particular currency. For example, currencies such 229 * as the U.S. dollar, the Euro and the Great British pound have two 230 * digits following the decimal point to indicate the value which exists 231 * in the associated lower-valued coinage (cents in the case of the first 232 * two, pennies in the latter). Some currencies such as the Japanese 233 * Yen have no digits after the decimal point. In the case of pseudo 234 * currencies, such as IMF Special Drawing Rights, -1 is returned. 235 * 236 * @return the number of digits after the decimal separator for this currency. 237 */ 238 public int getDefaultFractionDigits() 239 { 240 return fractionDigits; 241 } 242 243 /** 244 * Builds a new currency instance for this locale. 245 * All components of the given locale, other than the 246 * country code, are ignored. The results of calling this 247 * method may vary over time, as the currency associated with 248 * a particular country changes. For countries without 249 * a given currency (e.g. Antarctica), the result is null. 250 * 251 * @param locale a <code>Locale</code> instance. 252 * @return a new <code>Currency</code> instance. 253 * @throws NullPointerException if the locale or its 254 * country code is null. 255 * @throws IllegalArgumentException if the country of 256 * the given locale is not a supported ISO3166 code. 257 */ 258 public static Currency getInstance(Locale locale) 259 { 260 /** 261 * The new instance must be the only available instance 262 * for the currency it supports. We ensure this happens, 263 * while maintaining a suitable performance level, by 264 * creating the appropriate object on the first call to 265 * this method, and returning the cached instance on 266 * later calls. 267 */ 268 Currency newCurrency; 269 270 String country = locale.getCountry(); 271 if (locale == null || country == null) 272 { 273 throw new 274 NullPointerException("The locale or its country is null."); 275 } 276 277 /* Check that country of locale given is valid. */ 278 if (country.length() != 2) 279 throw new IllegalArgumentException(); 280 281 /* Attempt to get the currency from the cache */ 282 String code = (String) countryMap.get(country); 283 if (code == null) 284 { 285 /* Create the currency for this locale */ 286 newCurrency = new Currency(locale); 287 /* 288 * If the currency code is null, then creation failed 289 * and we return null. 290 */ 291 code = newCurrency.getCurrencyCode(); 292 if (code == null) 293 { 294 return null; 295 } 296 else 297 { 298 /* Cache it */ 299 countryMap.put(country, code); 300 cache.put(code, newCurrency); 301 } 302 } 303 else 304 { 305 newCurrency = (Currency) cache.get(code); 306 } 307 /* Return the instance */ 308 return newCurrency; 309 } 310 311 /** 312 * Builds the currency corresponding to the specified currency code. 313 * 314 * @param currencyCode a string representing a currency code. 315 * @return a new <code>Currency</code> instance. 316 * @throws NullPointerException if currencyCode is null. 317 * @throws IllegalArgumentException if the supplied currency code 318 * is not a supported ISO 4217 code. 319 */ 320 public static Currency getInstance(String currencyCode) 321 { 322 Locale[] allLocales; 323 324 /* 325 * Throw a null pointer exception explicitly if currencyCode is null. 326 * One is not thrown otherwise. It results in an 327 * IllegalArgumentException. 328 */ 329 if (currencyCode == null) 330 { 331 throw new NullPointerException("The supplied currency code is null."); 332 } 333 /* Nasty special case to allow an erroneous currency... blame Sun */ 334 if (currencyCode.equals("XXX")) 335 return new Currency("XXX"); 336 Currency newCurrency = (Currency) cache.get(currencyCode); 337 if (newCurrency == null) 338 { 339 /* Get all locales */ 340 allLocales = Locale.getAvailableLocales(); 341 /* Loop through each locale, looking for the code */ 342 for (int i = 0;i < allLocales.length; i++) 343 { 344 try 345 { 346 Currency testCurrency = getInstance (allLocales[i]); 347 if (testCurrency != null && 348 testCurrency.getCurrencyCode().equals(currencyCode)) 349 { 350 return testCurrency; 351 } 352 } 353 catch (IllegalArgumentException exception) 354 { 355 /* Ignore locales without valid countries */ 356 } 357 } 358 /* 359 * If we get this far, the code is not supported by any of 360 * our locales. 361 */ 362 throw new IllegalArgumentException("The currency code, " + currencyCode + 363 ", is not supported."); 364 } 365 else 366 { 367 return newCurrency; 368 } 369 } 370 371 /** 372 * This method returns the symbol which precedes or follows a 373 * value in this particular currency in the default locale. 374 * In cases where there is no such symbol for the currency, 375 * the ISO 4217 currency code is returned. 376 * 377 * @return the currency symbol, or the ISO 4217 currency code if 378 * one doesn't exist. 379 */ 380 public String getSymbol() 381 { 382 return getSymbol(Locale.getDefault()); 383 } 384 385 /** 386 * <p> 387 * This method returns the symbol which precedes or follows a 388 * value in this particular currency. The returned value is 389 * the symbol used to denote the currency in the specified locale. 390 * </p> 391 * <p> 392 * For example, a supplied locale may specify a different symbol 393 * for the currency, due to conflicts with its own currency. 394 * This would be the case with the American currency, the dollar. 395 * Locales that also use a dollar-based currency (e.g. Canada, Australia) 396 * need to differentiate the American dollar using 'US$' rather than '$'. 397 * So, supplying one of these locales to <code>getSymbol()</code> would 398 * return this value, rather than the standard '$'. 399 * </p> 400 * <p> 401 * In cases where there is no such symbol for a particular currency, 402 * the ISO 4217 currency code is returned. 403 * </p> 404 * 405 * @param locale the locale to express the symbol in. 406 * @return the currency symbol, or the ISO 4217 currency code if 407 * one doesn't exist. 408 * @throws NullPointerException if the locale is null. 409 */ 410 public String getSymbol(Locale locale) 411 { 412 String property = "currenciesSymbol." + currencyCode; 413 try 414 { 415 return ResourceBundle.getBundle("gnu.java.locale.LocaleInformation", 416 locale).getString(property); 417 } 418 catch (MissingResourceException exception) 419 { 420 /* This means runtime support for the locale 421 * is not available, so we check providers. */ 422 } 423 for (CurrencyNameProvider p : 424 ServiceLoader.load(CurrencyNameProvider.class)) 425 { 426 for (Locale loc : p.getAvailableLocales()) 427 { 428 if (loc.equals(locale)) 429 { 430 String localizedString = p.getSymbol(currencyCode, 431 locale); 432 if (localizedString != null) 433 return localizedString; 434 break; 435 } 436 } 437 } 438 if (locale.equals(Locale.ROOT)) // Base case 439 return currencyCode; 440 return getSymbol(LocaleHelper.getFallbackLocale(locale)); 441 } 442 443 /** 444 * Returns the international ISO4217 currency code of this currency. 445 * 446 * @return a <code>String</code> containing the ISO4217 currency code. 447 */ 448 public String toString() 449 { 450 return getCurrencyCode(); 451 } 452 453 /** 454 * Resolves the deserialized object to the singleton instance for its 455 * particular currency. The currency code of the deserialized instance 456 * is used to return the correct instance. 457 * 458 * @return the singleton instance for the currency specified by the 459 * currency code of the deserialized object. This replaces 460 * the deserialized object as the returned object from 461 * deserialization. 462 * @throws ObjectStreamException if a problem occurs with deserializing 463 * the object. 464 */ 465 private Object readResolve() 466 throws ObjectStreamException 467 { 468 return getInstance(currencyCode); 469 } 470 471 }