Java > Open Source Codes > java > util > ResourceBundle


1 /*
2  * @(#)ResourceBundle.java 1.73 05/11/04
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 /*
9  * (C) Copyright Taligent, Inc. 1996, 1997 - All Rights Reserved
10  * (C) Copyright IBM Corp. 1996 - 1999 - All Rights Reserved
11  *
12  * The original version of this source code and documentation
13  * is copyrighted and owned by Taligent, Inc., a wholly-owned
14  * subsidiary of IBM. These materials are provided under terms
15  * of a License Agreement between Taligent and Sun. This technology
16  * is protected by multiple US and International patents.
17  *
18  * This notice and attribution to Taligent may not be removed.
19  * Taligent is a registered trademark of Taligent, Inc.
20  *
21  */
22
23 package java.util;
24
25 import java.io.InputStream ;
26 import java.lang.ref.Reference ;
27 import java.lang.ref.ReferenceQueue ;
28 import java.lang.ref.WeakReference ;
29 import sun.misc.SoftCache;
30
31 /**
32  *
33  * Resource bundles contain locale-specific objects.
34  * When your program needs a locale-specific resource,
35  * a <code>String</code> for example, your program can load it
36  * from the resource bundle that is appropriate for the
37  * current user's locale. In this way, you can write
38  * program code that is largely independent of the user's
39  * locale isolating most, if not all, of the locale-specific
40  * information in resource bundles.
41  *
42  * <p>
43  * This allows you to write programs that can:
44  * <UL type=SQUARE>
45  * <LI> be easily localized, or translated, into different languages
46  * <LI> handle multiple locales at once
47  * <LI> be easily modified later to support even more locales
48  * </UL>
49  *
50  * <P>
51  * Resource bundles belong to families whose members share a common base
52  * name, but whose names also have additional components that identify
53  * their locales. For example, the base name of a family of resource
54  * bundles might be "MyResources". The family should have a default
55  * resource bundle which simply has the same name as its family -
56  * "MyResources" - and will be used as the bundle of last resort if a
57  * specific locale is not supported. The family can then provide as
58  * many locale-specific members as needed, for example a German one
59  * named "MyResources_de".
60  *
61  * <P>
62  * Each resource bundle in a family contains the same items, but the items have
63  * been translated for the locale represented by that resource bundle.
64  * For example, both "MyResources" and "MyResources_de" may have a
65  * <code>String</code> that's used on a button for canceling operations.
66  * In "MyResources" the <code>String</code> may contain "Cancel" and in
67  * "MyResources_de" it may contain "Abbrechen".
68  *
69  * <P>
70  * If there are different resources for different countries, you
71  * can make specializations: for example, "MyResources_de_CH" contains objects for
72  * the German language (de) in Switzerland (CH). If you want to only
73  * modify some of the resources
74  * in the specialization, you can do so.
75  *
76  * <P>
77  * When your program needs a locale-specific object, it loads
78  * the <code>ResourceBundle</code> class using the
79  * {@link #getBundle(java.lang.String, java.util.Locale) getBundle}
80  * method:
81  * <blockquote>
82  * <pre>
83  * ResourceBundle myResources =
84  * ResourceBundle.getBundle("MyResources", currentLocale);
85  * </pre>
86  * </blockquote>
87  *
88  * <P>
89  * Resource bundles contain key/value pairs. The keys uniquely
90  * identify a locale-specific object in the bundle. Here's an
91  * example of a <code>ListResourceBundle</code> that contains
92  * two key/value pairs:
93  * <blockquote>
94  * <pre>
95  * public class MyResources extends ListResourceBundle {
96  * protected Object[][] getContents() {
97  * return new Object[][] = {
98  * // LOCALIZE THIS
99  * {"OkKey", "OK"},
100  * {"CancelKey", "Cancel"},
101  * // END OF MATERIAL TO LOCALIZE
102  * };
103  * }
104  * }
105  * </pre>
106  * </blockquote>
107  * Keys are always <code>String</code>s.
108  * In this example, the keys are "OkKey" and "CancelKey".
109  * In the above example, the values
110  * are also <code>String</code>s--"OK" and "Cancel"--but
111  * they don't have to be. The values can be any type of object.
112  *
113  * <P>
114  * You retrieve an object from resource bundle using the appropriate
115  * getter method. Because "OkKey" and "CancelKey"
116  * are both strings, you would use <code>getString</code> to retrieve them:
117  * <blockquote>
118  * <pre>
119  * button1 = new Button(myResources.getString("OkKey"));
120  * button2 = new Button(myResources.getString("CancelKey"));
121  * </pre>
122  * </blockquote>
123  * The getter methods all require the key as an argument and return
124  * the object if found. If the object is not found, the getter method
125  * throws a <code>MissingResourceException</code>.
126  *
127  * <P>
128  * Besides <code>getString</code>, ResourceBundle also provides
129  * a method for getting string arrays, <code>getStringArray</code>,
130  * as well as a generic <code>getObject</code> method for any other
131  * type of object. When using <code>getObject</code>, you'll
132  * have to cast the result to the appropriate type. For example:
133  * <blockquote>
134  * <pre>
135  * int[] myIntegers = (int[]) myResources.getObject("intList");
136  * </pre>
137  * </blockquote>
138  *
139  * <P>
140  * The Java 2 platform provides two subclasses of <code>ResourceBundle</code>,
141  * <code>ListResourceBundle</code> and <code>PropertyResourceBundle</code>,
142  * that provide a fairly simple way to create resources.
143  * As you saw briefly in a previous example, <code>ListResourceBundle</code>
144  * manages its resource as a List of key/value pairs.
145  * <code>PropertyResourceBundle</code> uses a properties file to manage
146  * its resources.
147  *
148  * <p>
149  * If <code>ListResourceBundle</code> or <code>PropertyResourceBundle</code>
150  * do not suit your needs, you can write your own <code>ResourceBundle</code>
151  * subclass. Your subclasses must override two methods: <code>handleGetObject</code>
152  * and <code>getKeys()</code>.
153  *
154  * <P>
155  * The following is a very simple example of a <code>ResourceBundle</code>
156  * subclass, MyResources, that manages two resources (for a larger number of
157  * resources you would probably use a <code>Hashtable</code>).
158  * Notice that you don't need to supply a value if
159  * a "parent-level" <code>ResourceBundle</code> handles the same
160  * key with the same value (as for the okKey below).
161  * <p><strong>Example:</strong>
162  * <blockquote>
163  * <pre>
164  * // default (English language, United States)
165  * public class MyResources extends ResourceBundle {
166  * public Object handleGetObject(String key) {
167  * if (key.equals("okKey")) return "Ok";
168  * if (key.equals("cancelKey")) return "Cancel";
169  * return null;
170  * }
171  * }
172  *
173  * // German language
174  * public class MyResources_de extends MyResources {
175  * public Object handleGetObject(String key) {
176  * // don't need okKey, since parent level handles it.
177  * if (key.equals("cancelKey")) return "Abbrechen";
178  * return null;
179  * }
180  * }
181  * </pre>
182  * </blockquote>
183  * You do not have to restrict yourself to using a single family of
184  * <code>ResourceBundle</code>s. For example, you could have a set of bundles for
185  * exception messages, <code>ExceptionResources</code>
186  * (<code>ExceptionResources_fr</code>, <code>ExceptionResources_de</code>, ...),
187  * and one for widgets, <code>WidgetResource</code> (<code>WidgetResources_fr</code>,
188  * <code>WidgetResources_de</code>, ...); breaking up the resources however you like.
189  *
190  * @see ListResourceBundle
191  * @see PropertyResourceBundle
192  * @see MissingResourceException
193  * @since JDK1.1
194  */
195 abstract public class ResourceBundle {
196     /**
197      * Static key used for resource lookups. Concurrent
198      * access to this object is controlled by synchronizing cacheList,
199      * not cacheKey. A static object is used to do cache lookups
200      * for performance reasons - the assumption being that synchronization
201      * has a lower overhead than object allocation and subsequent
202      * garbage collection.
203      */
204     private static final ResourceCacheKey cacheKey = new ResourceCacheKey();
205
206     /** initial size of the bundle cache */
207     private static final int INITIAL_CACHE_SIZE = 25;
208
209     /** capacity of cache consumed before it should grow */
210     private static final float CACHE_LOAD_FACTOR = (float)1.0;
211
212     /**
213      * Maximum length of one branch of the resource search path tree.
214      * Used in getBundle.
215      */
216     private static final int MAX_BUNDLES_SEARCHED = 3;
217
218     /**
219      * This Hashtable is used to keep multiple threads from loading the
220      * same bundle concurrently. The table entries are (cacheKey, thread)
221      * where cacheKey is the key for the bundle that is under construction
222      * and thread is the thread that is constructing the bundle.
223      * This list is manipulated in findBundle and putBundleInCache.
224      * Synchronization of this object is done through cacheList, not on
225      * this object.
226      */
227     private static final Hashtable underConstruction = new Hashtable (MAX_BUNDLES_SEARCHED, CACHE_LOAD_FACTOR);
228
229     /** constant indicating that no resource bundle was found */
230     private static final Object NOT_FOUND = new Object ();
231
232     /**
233      * The cache is a map from cache keys (with bundle base name,
234      * locale, and class loader) to either a resource bundle
235      * (if one has been found) or NOT_FOUND (if no bundle has
236      * been found).
237      * The cache is a SoftCache, allowing bundles to be
238      * removed from the cache if they are no longer
239      * needed. This will also allow the cache keys
240      * to be reclaimed along with the ClassLoaders
241      * they reference.
242      * This variable would be better named "cache", but we keep the old
243      * name for compatibility with some workarounds for bug 4212439.
244      */
245     private static SoftCache cacheList = new SoftCache(INITIAL_CACHE_SIZE, CACHE_LOAD_FACTOR);
246
247     /**
248      * Queue for reference objects referring to class loaders.
249      */
250     private static ReferenceQueue referenceQueue = new ReferenceQueue ();
251
252     /**
253      * The parent bundle of this bundle.
254      * The parent bundle is searched by {@link #getObject getObject}
255      * when this bundle does not contain a particular resource.
256      */
257     protected ResourceBundle parent = null;
258
259     /**
260      * The locale for this bundle.
261      */
262     private Locale locale = null;
263
264     /**
265      * Sole constructor. (For invocation by subclass constructors, typically
266      * implicit.)
267      */
268     public ResourceBundle() {
269     }
270
271     /**
272      * Gets a string for the given key from this resource bundle or one of its parents.
273      * Calling this method is equivalent to calling
274      * <blockquote>
275      * <code>(String) {@link #getObject(java.lang.String) getObject}(key)</code>.
276      * </blockquote>
277      *
278      * @param key the key for the desired string
279      * @exception NullPointerException if <code>key</code> is <code>null</code>
280      * @exception MissingResourceException if no object for the given key can be found
281      * @exception ClassCastException if the object found for the given key is not a string
282      * @return the string for the given key
283      */
284     public final String getString(String key) {
285         return (String ) getObject(key);
286     }
287
288     /**
289      * Gets a string array for the given key from this resource bundle or one of its parents.
290      * Calling this method is equivalent to calling
291      * <blockquote>
292      * <code>(String[]) {@link #getObject(java.lang.String) getObject}(key)</code>.
293      * </blockquote>
294      *
295      * @param key the key for the desired string array
296      * @exception NullPointerException if <code>key</code> is <code>null</code>
297      * @exception MissingResourceException if no object for the given key can be found
298      * @exception ClassCastException if the object found for the given key is not a string array
299      * @return the string array for the given key
300      */
301     public final String [] getStringArray(String key) {
302         return (String []) getObject(key);
303     }
304
305     /**
306      * Gets an object for the given key from this resource bundle or one of its parents.
307      * This method first tries to obtain the object from this resource bundle using
308      * {@link #handleGetObject(java.lang.String) handleGetObject}.
309      * If not successful, and the parent resource bundle is not null,
310      * it calls the parent's <code>getObject</code> method.
311      * If still not successful, it throws a MissingResourceException.
312      *
313      * @param key the key for the desired object
314      * @exception NullPointerException if <code>key</code> is <code>null</code>
315      * @exception MissingResourceException if no object for the given key can be found
316      * @return the object for the given key
317      */
318     public final Object getObject(String key) {
319         Object obj = handleGetObject(key);
320         if (obj == null) {
321             if (parent != null) {
322                 obj = parent.getObject(key);
323             }
324             if (obj == null)
325                 throw new MissingResourceException ("Can't find resource for bundle "
326                                                    +this.getClass().getName()
327                                                    +", key "+key,
328                                                    this.getClass().getName(),
329                                                    key);
330         }
331         return obj;
332     }
333
334     /**
335      * Returns the locale of this resource bundle. This method can be used after a
336      * call to getBundle() to determine whether the resource bundle returned really
337      * corresponds to the requested locale or is a fallback.
338      *
339      * @return the locale of this resource bundle
340      */
341     public Locale getLocale() {
342         return locale;
343     }
344
345     /**
346      * Sets the locale for this bundle. This is the locale that this
347      * bundle actually represents and does not depend on how the
348      * bundle was found by getBundle. Ex. if the user was looking
349      * for fr_FR and getBundle found en_US, the bundle's locale would
350      * be en_US, NOT fr_FR
351      * @param baseName the bundle's base name
352      * @param bundleName the complete bundle name including locale
353      * extension.
354      */
355     private void setLocale(String baseName, String bundleName) {
356         if (baseName.length() == bundleName.length()) {
357             locale = new Locale ("", "");
358         } else if (baseName.length() < bundleName.length()) {
359             int pos = baseName.length();
360             String temp = bundleName.substring(pos + 1);
361             pos = temp.indexOf('_');
362             if (pos == -1) {
363                 locale = new Locale (temp, "", "");
364                 return;
365             }
366
367             String language = temp.substring(0, pos);
368             temp = temp.substring(pos + 1);
369             pos = temp.indexOf('_');
370             if (pos == -1) {
371                 locale = new Locale (language, temp, "");
372                 return;
373             }
374
375             String country = temp.substring(0, pos);
376             temp = temp.substring(pos + 1);
377
378             locale = new Locale (language, country, temp);
379         } else {
380             //The base name is longer than the bundle name. Something is very wrong
381 //with the calling code.
382 throw new IllegalArgumentException ();
383         }
384     }
385
386     /*
387      * Automatic determination of the ClassLoader to be used to load
388      * resources on behalf of the client. N.B. The client is getLoader's
389      * caller's caller.
390      */
391     private static ClassLoader getLoader() {
392         Class [] stack = getClassContext();
393         /* Magic number 2 identifies our caller's caller */
394         Class c = stack[2];
395         ClassLoader cl = (c == null) ? null : c.getClassLoader();
396         if (cl == null) {
397             cl = ClassLoader.getSystemClassLoader();
398         }
399         return cl;
400     }
401
402     private static native Class [] getClassContext();
403
404     /**
405      * Sets the parent bundle of this bundle.
406      * The parent bundle is searched by {@link #getObject getObject}
407      * when this bundle does not contain a particular resource.
408      *
409      * @param parent this bundle's parent bundle.
410      */
411     protected void setParent( ResourceBundle parent ) {
412         this.parent = parent;
413     }
414
415      /**
416       * Key used for cached resource bundles. The key checks
417       * the resource name, the class loader, and the default
418       * locale to determine if the resource is a match to the
419       * requested one. The loader may be null, but the
420       * searchName and the default locale must have a non-null value.
421       * Note that the default locale may change over time, and
422       * lookup should always be based on the current default
423       * locale (if at all).
424       */
425     private static final class ResourceCacheKey implements Cloneable {
426         private LoaderReference loaderRef;
427         private String searchName;
428         private Locale defaultLocale;
429         private int hashCodeCache;
430
431         public boolean equals(Object other) {
432             if (this == other) {
433                 return true;
434             }
435             try {
436                 final ResourceCacheKey otherEntry = (ResourceCacheKey)other;
437                 //quick check to see if they are not equal
438 if (hashCodeCache != otherEntry.hashCodeCache) {
439                     return false;
440                 }
441                 //are the names the same?
442 if (!searchName.equals(otherEntry.searchName)) {
443                     return false;
444                 }
445                 // are the default locales the same?
446 if (defaultLocale == null) {
447                     if (otherEntry.defaultLocale != null) {
448                         return false;
449                     }
450                 } else {
451                     if (!defaultLocale.equals(otherEntry.defaultLocale)) {
452                         return false;
453                     }
454                 }
455                 //are refs (both non-null) or (both null)?
456 if (loaderRef == null) {
457                     return otherEntry.loaderRef == null;
458                 } else {
459                     Object loaderRefValue = loaderRef.get();
460                     return (otherEntry.loaderRef != null)
461                             // with a null reference we can no longer find
462 // out which class loader was referenced; so
463 // treat it as unequal
464 && (loaderRefValue != null)
465                             && (loaderRefValue == otherEntry.loaderRef.get());
466                 }
467             } catch (NullPointerException e) {
468                 return false;
469             } catch (ClassCastException e) {
470                 return false;
471             }
472         }
473
474         public int hashCode() {
475             return hashCodeCache;
476         }
477
478         public Object clone() {
479             try {
480                 ResourceCacheKey clone = (ResourceCacheKey) super.clone();
481                 if (loaderRef != null) {
482                     clone.loaderRef = new LoaderReference(loaderRef.get(), referenceQueue, clone);
483                 }
484                 return clone;
485             } catch (CloneNotSupportedException e) {
486                 //this should never happen
487 throw new InternalError ();
488             }
489         }
490
491         public void setKeyValues(ClassLoader loader, String searchName, Locale defaultLocale) {
492             this.searchName = searchName;
493             hashCodeCache = searchName.hashCode();
494             this.defaultLocale = defaultLocale;
495             if (defaultLocale != null) {
496                 hashCodeCache ^= defaultLocale.hashCode();
497             }
498             if (loader == null) {
499                 this.loaderRef = null;
500             } else {
501                 loaderRef = new LoaderReference(loader, referenceQueue, this);
502                 hashCodeCache ^= loader.hashCode();
503             }
504         }
505
506         public void clear() {
507             setKeyValues(null, "", null);
508         }
509     }
510
511     /**
512      * References to class loaders are weak references, so that they can be
513      * garbage collected when nobody else is using them. The ResourceBundle
514      * class has no reason to keep class loaders alive.
515      */
516     private static final class LoaderReference extends WeakReference {
517         private ResourceCacheKey cacheKey;
518         
519         LoaderReference(Object referent, ReferenceQueue q, ResourceCacheKey key) {
520             super(referent, q);
521             cacheKey = key;
522         }
523         
524         ResourceCacheKey getCacheKey() {
525             return cacheKey;
526         }
527     }
528     
529     /**
530      * Gets a resource bundle using the specified base name, the default locale,
531      * and the caller's class loader. Calling this method is equivalent to calling
532      * <blockquote>
533      * <code>getBundle(baseName, Locale.getDefault(), this.getClass().getClassLoader())</code>,
534      * </blockquote>
535      * except that <code>getClassLoader()</code> is run with the security
536      * privileges of <code>ResourceBundle</code>.
537      * See {@link #getBundle(java.lang.String, java.util.Locale, java.lang.ClassLoader) getBundle}
538      * for a complete description of the search and instantiation strategy.
539      *
540      * @param baseName the base name of the resource bundle, a fully qualified class name
541      * @exception java.lang.NullPointerException
542      * if <code>baseName</code> is <code>null</code>
543      * @exception MissingResourceException
544      * if no resource bundle for the specified base name can be found
545      * @return a resource bundle for the given base name and the default locale
546      */
547     public static final ResourceBundle getBundle(String baseName)
548     {
549         return getBundleImpl(baseName, Locale.getDefault(),
550         /* must determine loader here, else we break stack invariant */
551         getLoader());
552     }
553
554     /**
555      * Gets a resource bundle using the specified base name and locale,
556      * and the caller's class loader. Calling this method is equivalent to calling
557      * <blockquote>
558      * <code>getBundle(baseName, locale, this.getClass().getClassLoader())</code>,
559      * </blockquote>
560      * except that <code>getClassLoader()</code> is run with the security
561      * privileges of <code>ResourceBundle</code>.
562      * See {@link #getBundle(java.lang.String, java.util.Locale, java.lang.ClassLoader) getBundle}
563      * for a complete description of the search and instantiation strategy.
564      *
565      * @param baseName the base name of the resource bundle, a fully qualified class name
566      * @param locale the locale for which a resource bundle is desired
567      * @exception java.lang.NullPointerException
568      * if <code>baseName</code> or <code>locale</code> is <code>null</code>
569      * @exception MissingResourceException
570      * if no resource bundle for the specified base name can be found
571      * @return a resource bundle for the given base name and locale
572      */
573     public static final ResourceBundle getBundle(String baseName,
574                                                          Locale locale)
575     {
576         return getBundleImpl(baseName, locale, getLoader());
577     }
578
579     /**
580      * Gets a resource bundle using the specified base name, locale, and class loader.
581      *
582      * <p>
583      * Conceptually, <code>getBundle</code> uses the following strategy for locating and instantiating
584      * resource bundles:
585      * <p>
586      * <code>getBundle</code> uses the base name, the specified locale, and the default
587      * locale (obtained from {@link java.util.Locale#getDefault() Locale.getDefault})
588      * to generate a sequence of <em>candidate bundle names</em>.
589      * If the specified locale's language, country, and variant are all empty
590      * strings, then the base name is the only candidate bundle name.
591      * Otherwise, the following sequence is generated from the attribute
592      * values of the specified locale (language1, country1, and variant1)
593      * and of the default locale (language2, country2, and variant2):
594      * <ul>
595      * <li> baseName + "_" + language1 + "_" + country1 + "_" + variant1
596      * <li> baseName + "_" + language1 + "_" + country1
597      * <li> baseName + "_" + language1
598      * <li> baseName + "_" + language2 + "_" + country2 + "_" + variant2
599      * <li> baseName + "_" + language2 + "_" + country2
600      * <li> baseName + "_" + language2
601      * <li> baseName
602      * </ul>
603      * <p>
604      * Candidate bundle names where the final component is an empty string are omitted.
605      * For example, if country1 is an empty string, the second candidate bundle name is omitted.
606      *
607      * <p>
608      * <code>getBundle</code> then iterates over the candidate bundle names to find the first
609      * one for which it can <em>instantiate</em> an actual resource bundle. For each candidate
610      * bundle name, it attempts to create a resource bundle:
611      * <ul>
612      * <li>
613      * First, it attempts to load a class using the candidate bundle name.
614      * If such a class can be found and loaded using the specified class loader, is assignment
615      * compatible with ResourceBundle, is accessible from ResourceBundle, and can be instantiated,
616      * <code>getBundle</code> creates a new instance of this class and uses it as the <em>result
617      * resource bundle</em>.
618      * <li>
619      * Otherwise, <code>getBundle</code> attempts to locate a property resource file.
620      * It generates a path name from the candidate bundle name by replacing all "." characters
621      * with "/" and appending the string ".properties".
622      * It attempts to find a "resource" with this name using
623      * {@link java.lang.ClassLoader#getResource(java.lang.String) ClassLoader.getResource}.
624      * (Note that a "resource" in the sense of <code>getResource</code> has nothing to do with
625      * the contents of a resource bundle, it is just a container of data, such as a file.)
626      * If it finds a "resource", it attempts to create a new
627      * {@link PropertyResourceBundle} instance from its contents.
628      * If successful, this instance becomes the <em>result resource bundle</em>.
629      * </ul>
630      *
631      * <p>
632      * If no result resource bundle has been found, a <code>MissingResourceException</code>
633      * is thrown.
634      *
635      * <p>
636      * Once a result resource bundle has been found, its parent chain is instantiated.
637      * <code>getBundle</code> iterates over the candidate bundle names that can be
638      * obtained by successively removing variant, country, and language
639      * (each time with the preceding "_") from the bundle name of the result resource bundle.
640      * As above, candidate bundle names where the final component is an empty string are omitted.
641      * With each of the candidate bundle names it attempts to instantiate a resource bundle, as
642      * described above.
643      * Whenever it succeeds, it calls the previously instantiated resource
644      * bundle's {@link #setParent(java.util.ResourceBundle) setParent} method
645      * with the new resource bundle, unless the previously instantiated resource
646      * bundle already has a non-null parent.
647      *
648      * <p>
649      * Implementations of <code>getBundle</code> may cache instantiated resource bundles
650      * and return the same resource bundle instance multiple times. They may also
651      * vary the sequence in which resource bundles are instantiated as long as the
652      * selection of the result resource bundle and its parent chain are compatible with
653      * the description above.
654      *
655      * <p>
656      * The <code>baseName</code> argument should be a fully qualified class name. However, for
657      * compatibility with earlier versions, Sun's Java 2 runtime environments do not verify this,
658      * and so it is possible to access <code>PropertyResourceBundle</code>s by specifying a
659      * path name (using "/") instead of a fully qualified class name (using ".").
660      *
661      * <p>
662      * <strong>Example:</strong> The following class and property files are provided:
663      * MyResources.class, MyResources_fr_CH.properties, MyResources_fr_CH.class,
664      * MyResources_fr.properties, MyResources_en.properties, MyResources_es_ES.class.
665      * The contents of all files are valid (that is, public non-abstract subclasses of ResourceBundle for
666      * the ".class" files, syntactically correct ".properties" files).
667      * The default locale is <code>Locale("en", "GB")</code>.
668      * <p>
669      * Calling <code>getBundle</code> with the shown locale argument values instantiates
670      * resource bundles from the following sources:
671      * <ul>
672      * <li>Locale("fr", "CH"): result MyResources_fr_CH.class, parent MyResources_fr.properties, parent MyResources.class
673      * <li>Locale("fr", "FR"): result MyResources_fr.properties, parent MyResources.class
674      * <li>Locale("de", "DE"): result MyResources_en.properties, parent MyResources.class
675      * <li>Locale("en", "US"): result MyResources_en.properties, parent MyResources.class
676      * <li>Locale("es", "ES"): result MyResources_es_ES.class, parent MyResources.class
677      * </ul>
678      * The file MyResources_fr_CH.properties is never used because it is hidden by
679      * MyResources_fr_CH.class.
680      *
681      * <p>
682      *
683      * @param baseName the base name of the resource bundle, a fully qualified class name
684      * @param locale the locale for which a resource bundle is desired
685      * @param loader the class loader from which to load the resource bundle
686      * @exception java.lang.NullPointerException
687      * if <code>baseName</code>, <code>locale</code>, or <code>loader</code> is <code>null</code>
688      * @exception MissingResourceException
689      * if no resource bundle for the specified base name can be found
690      * @return a resource bundle for the given base name and locale
691      * @since 1.2
692      */
693     public static ResourceBundle getBundle(String baseName, Locale locale,
694                                            ClassLoader loader)
695     {
696         if (loader == null) {
697             throw new NullPointerException ();
698         }
699         return getBundleImpl(baseName, locale, loader);
700     }
701
702     private static ResourceBundle getBundleImpl(String baseName, Locale locale,
703                                            ClassLoader loader)
704     {
705         if (baseName == null) {
706             throw new NullPointerException ();
707         }
708
709         //fast path the case where the bundle is cached
710 String bundleName = baseName;
711         String localeSuffix = locale.toString();
712         if (localeSuffix.length() > 0) {
713             bundleName += "_" + localeSuffix;
714         } else if (locale.getVariant().length() > 0) {
715             //This corrects some strange behavior in Locale where
716 //new Locale("", "", "VARIANT").toString == ""
717 bundleName += "___" + locale.getVariant();
718         }
719         
720         // The default locale may influence the lookup result, and
721 // it may change, so we get it here once.
722 Locale defaultLocale = Locale.getDefault();
723
724         Object lookup = findBundleInCache(loader, bundleName, defaultLocale);
725         if (lookup == NOT_FOUND) {
726             throwMissingResourceException(baseName, locale);
727         } else if (lookup != null) {
728             return (ResourceBundle )lookup;
729         }
730
731         //The bundle was not cached, so start doing lookup at the root
732 //Resources are loaded starting at the root and working toward
733 //the requested bundle.
734
735         //If findBundle returns null, we become responsible for defining
736 //the bundle, and must call putBundleInCache to complete this
737 //task. This is critical because other threads may be waiting
738 //for us to finish.
739
740         Object parent = NOT_FOUND;
741         try {
742             //locate the root bundle and work toward the desired child
743 Object root = findBundle(loader, baseName, defaultLocale, baseName, null);
744             if (root == null) {
745                 putBundleInCache(loader, baseName, defaultLocale, NOT_FOUND);
746                 root = NOT_FOUND;
747             }
748
749             // Search the main branch of the search tree.
750 // We need to keep references to the bundles we find on the main path
751 // so they don't get garbage collected before we get to propagate().
752 final Vector names = calculateBundleNames(baseName, locale);
753             Vector bundlesFound = new Vector (MAX_BUNDLES_SEARCHED);
754         // if we found the root bundle and no other bundle names are needed
755 // we can stop here. We don't need to search or load anything further.
756 boolean foundInMainBranch = (root != NOT_FOUND && names.size() == 0);
757         
758         if (!foundInMainBranch) {
759           parent = root;
760           for (int i = 0; i < names.size(); i++) {
761                 bundleName = (String )names.elementAt(i);
762                 lookup = findBundle(loader, bundleName, defaultLocale, baseName, parent);
763                 bundlesFound.addElement(lookup);
764                 if (lookup != null) {
765                     parent = lookup;
766                     foundInMainBranch = true;
767                 }
768           }
769             }
770             parent = root;
771             if (!foundInMainBranch) {
772                 //we didn't find anything on the main branch, so we do the fallback branch
773 final Vector fallbackNames = calculateBundleNames(baseName, defaultLocale);
774                 for (int i = 0; i < fallbackNames.size(); i++) {
775                     bundleName = (String )fallbackNames.elementAt(i);
776                     if (names.contains(bundleName)) {
777                         //the fallback branch intersects the main branch so we can stop now.
778 break;
779                     }
780                     lookup = findBundle(loader, bundleName, defaultLocale, baseName, parent);
781                     if (lookup != null) {
782                         parent = lookup;
783                     } else {
784                         //propagate the parent to the child. We can do this
785 //here because we are in the default path.
786 putBundleInCache(loader, bundleName, defaultLocale, parent);
787                     }
788                 }
789             }
790             //propagate the inheritance/fallback down through the main branch
791 parent = propagate(loader, names, bundlesFound, defaultLocale, parent);
792         } catch (Exception e) {
793             //We should never get here unless there has been a change
794 //to the code that doesn't catch it's own exceptions.
795 cleanUpConstructionList();
796             throwMissingResourceException(baseName, locale);
797         } catch (Error e) {
798             //The only Error that can currently hit this code is a ThreadDeathError
799 //but errors might be added in the future, so we'll play it safe and
800 //clean up.
801 cleanUpConstructionList();
802             throw e;
803         }
804         if (parent == NOT_FOUND) {
805             throwMissingResourceException(baseName, locale);
806         }
807         return (ResourceBundle )parent;
808     }
809
810     /**
811      * propagate bundles from the root down the specified branch of the search tree.
812      * @param loader the class loader for the bundles
813      * @param names the names of the bundles along search path
814      * @param bundlesFound the bundles corresponding to the names (some may be null)
815      * @param defaultLocale the default locale at the time getBundle was called
816      * @param parent the parent of the first bundle in the path (the root bundle)
817      * @return the value of the last bundle along the path
818      */
819     private static Object propagate(ClassLoader loader, Vector names,
820             Vector bundlesFound, Locale defaultLocale, Object parent) {
821         for (int i = 0; i < names.size(); i++) {
822             final String bundleName = (String )names.elementAt(i);
823             final Object lookup = bundlesFound.elementAt(i);
824             if (lookup == null) {
825                 putBundleInCache(loader, bundleName, defaultLocale, parent);
826             } else {
827                 parent = lookup;
828             }
829         }
830         return parent;
831     }
832
833     /** Throw a MissingResourceException with proper message */
834     private static void throwMissingResourceException(String baseName, Locale locale)
835             throws MissingResourceException {
836         throw new MissingResourceException ("Can't find bundle for base name "
837                                            + baseName + ", locale " + locale,
838                                            baseName + "_" + locale,"");
839     }
840
841     /**
842      * Remove any entries this thread may have in the construction list.
843      * This is done as cleanup in the case where a bundle can't be
844      * constructed.
845      */
846     private static void cleanUpConstructionList() {
847         synchronized (cacheList) {
848             final Collection entries = underConstruction.values();
849             final Thread thisThread = Thread.currentThread();
850             while (entries.remove(thisThread)) {
851             }
852         // Wake up threads that have been waiting for construction
853 // completion. (6329105)
854 cacheList.notifyAll();
855         }
856     }
857
858