001/* Currency.java -- Representation of a currency
002   Copyright (C) 2003, 2004, 2005  Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package java.util;
040
041import gnu.java.locale.LocaleHelper;
042
043import java.io.IOException;
044import java.io.ObjectStreamException;
045import java.io.Serializable;
046
047import 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 */
063public 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}