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 }