com.artima.place.info
Class ResourceBundleLoader

java.lang.Object
  |
  +--com.artima.place.info.ResourceBundleLoader
All Implemented Interfaces:
java.io.Serializable

public class ResourceBundleLoader
extends java.lang.Object
implements java.io.Serializable

A class that takes care of loading resources from a codebase that is selected based on best-fit locale. The best-fit locale is selected using an algorithm similar to that used by ResourceBundle.getBundle().

This class is not cloneable because it is immutable.

See Also:
Serialized Form

Constructor Summary
ResourceBundleLoader(java.lang.String baseName, java.util.Map localesMap)
          Constructs a ResourceBundleLoader with passed base name and locales map.
 
Method Summary
 boolean equals(java.lang.Object o)
          Compares passed ResourceBundleLoader to this ResourceBundleLoader for equality.
 java.util.Locale getBestFitLocale()
          Returns the actual locale for which this ResourceBundleLoader can return a resource bundle that best fits the default locale.
 java.util.Locale getBestFitLocale(java.util.Locale desiredLocale)
          Returns the actual locale for which this ResourceBundleLoader can return a resource bundle that best fits the passed locale.
 java.lang.ClassLoader getCodebaseClassLoader()
          Returns a ClassLoader for the codebase that best fits the default Locale.
 java.lang.ClassLoader getCodebaseClassLoader(java.util.Locale locale)
          Returns a ClassLoader for the codebase that best fits the passed Locale.
 java.util.ResourceBundle getResourceBundle()
          Returns a best-fit ResourceBundle for the default Locale.
 java.util.ResourceBundle getResourceBundle(java.util.Locale locale)
          Returns a best-fit ResourceBundle for the passed desired Locale.
 java.util.Set getSupportedLocales()
          Returns an unmodifiable set of locales which are directly supported by this ResourceBundleLoader.
 int hashCode()
          Computes the hash code for this ResourceBundleLoader.
 ResourceBundleLoader strip(java.util.Set preserveLocales)
          Returns a ResourceBundleLoader that supports only the locales in the passed set.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ResourceBundleLoader

public ResourceBundleLoader(java.lang.String baseName,
                            java.util.Map localesMap)
Constructs a ResourceBundleLoader with passed base name and locales map. The locales map contains Locale keys mapped to codebase URLStrings. The Locale keys represent locales for which ResourceBundles exist at the corresponding codebase URL. The set of locales in this map are a cache of the information embedded in the class names (or property file names) of the resources. For example, if class files MyResources_de_CH.class, MyResources_de.class, and MyResources.class are sitting in a JAR file at http://www.artima.com/myderes.jar, then Locale keys for ("de", "CH"), ("de", ""), and ("", "") would exist in this map all of whose coresponding URLString values would be "http://www.artima.com/myderes.jar".

The passed map is not used as part of the state of this object. The locales map may also contain as values arrays of URLString, so long as the length of the array is not zero and no elements of the array is null.

Parameters:
baseName - the base name of the ResourceBundles that can be loaded by this ResourceBundleLoader
localesMap - a mapping of Locales to codebase URL Strings
Throws:
NullPointerException - if either of passed baseName or localesMap is null, or if any value contained in the localesMap is null
java.lang.IllegalArgumentException - if any keys contained in passed localesMap are not Locales, if any values are not either URLStrings or URLString[]s, if the length of any URLString[] array is zero, or if any URLString[] array contains null elements, if the localesMap does not contain the empty Locale, or if the basename contains any white space.
Method Detail

getBestFitLocale

public java.util.Locale getBestFitLocale(java.util.Locale desiredLocale)
Returns the actual locale for which this ResourceBundleLoader can return a resource bundle that best fits the passed locale.
Parameters:
desiredLocale - the locale for which to get a best-fit supported locale.
Returns:
the best-fit locale for the specified locale.
Throws:
NullPointerException - if the desiredLocale parameter is null

getBestFitLocale

public java.util.Locale getBestFitLocale()
Returns the actual locale for which this ResourceBundleLoader can return a resource bundle that best fits the default locale.
Returns:
the best-fit locale for the default locale.

getSupportedLocales

public java.util.Set getSupportedLocales()
Returns an unmodifiable set of locales which are directly supported by this ResourceBundleLoader. Need to define whether or not this means also listing the dudes that don't have all, such as the root, or _en if also have _en_US. Probably want to send back all.
Returns:
the set of locales supported by this ResourceBundleLoader.

getResourceBundle

public java.util.ResourceBundle getResourceBundle()
                                           throws java.util.MissingResourceException
Returns a best-fit ResourceBundle for the default Locale.
Returns:
a best-fit ResourceBundle for the default Locale.
Throws:
java.util.MissingResourceException - if a codebase URL is found to be unusable. (Because URLString enforces well-formedness of all URLs used by this method, this exception probably indicates the protocol was unknown.), or if a ResourceBundle is not found at the expected codebase

getResourceBundle

public java.util.ResourceBundle getResourceBundle(java.util.Locale locale)
                                           throws java.util.MissingResourceException
Returns a best-fit ResourceBundle for the passed desired Locale.
Parameters:
locale - the desired locale
Returns:
a best-fit ResourceBundle for the passed desired Locale.
Throws:
java.util.MissingResourceException - if a codebase URL is found to be unusable (Because URLString enforces well-formedness of all URLs used by this method, this exception probably indicates the protocol was unknown.), or if a ResourceBundle is not found at the expected codebase
NullPointerException - if the passed locale parameter is null

getCodebaseClassLoader

public java.lang.ClassLoader getCodebaseClassLoader()
                                             throws java.net.MalformedURLException
Returns a ClassLoader for the codebase that best fits the default Locale. The returned ClassLoader represents the codebase from which the ResourceBundle returned by getResourceBundle() is loaded. If a resource loaded from a ResourceBundle indicates the name of a file loadable from its codebase, that file can be loaded via the getResource, getResourceAsStream, or getResources methods of the returned ClassLoader.
Returns:
a ClassLoader for the codebase that best fits the default Locale.
Throws:
java.net.MalformedURLException - if a codebase URL is found to be unusable. (Because URLString enforces well-formedness of all URLs used by this method, this exception probably indicates the protocol was unknown.), or if a ResourceBundle is not found at the expected codebase

getCodebaseClassLoader

public java.lang.ClassLoader getCodebaseClassLoader(java.util.Locale locale)
                                             throws java.net.MalformedURLException
Returns a ClassLoader for the codebase that best fits the passed Locale. The returned ClassLoader represents the codebase from which the ResourceBundle returned by getResourceBundle(Locale) is loaded. If a resource loaded from a ResourceBundle indicates the name of a file loadable from its codebase, that file can be loaded via the getResource, getResourceAsStream, or getResources methods of the returned ClassLoader.
Parameters:
locale - the desired locale
Returns:
a ClassLoader for the codebase that best fits the passed desired Locale.
Throws:
java.net.MalformedURLException - if a codebase URL is found to be unusable (Because URLString enforces well-formedness of all URLs used by this method, this exception probably indicates the protocol was unknown.), or if a ResourceBundle is not found at the expected codebase
NullPointerException - if the passed locale parameter is null

equals

public boolean equals(java.lang.Object o)
Compares passed ResourceBundleLoader to this ResourceBundleLoader for equality. Two ResourceBundleLoader objects are semantically equal if they have the equivalent base names and locales maps.
Overrides:
equals in class java.lang.Object
Parameters:
An - object to compare to this ResourceBundleLoader
Returns:
true if this ResourceBundleLoader is semantically equal to the passed ResourceBundleLoader

strip

public ResourceBundleLoader strip(java.util.Set preserveLocales)
Returns a ResourceBundleLoader that supports only the locales in the passed set. If the passed set does not contain the empty Locale, the empty locale will be included in the stripped ResourceBundleLoader anyway. If the length of the passed set is zero, only the empty Locale will be contained in the stripped ResourceBundleLoader. All Locales contained in the passed Set must be directly supported by this ResourceBundleLoader, i.e., must be included in the Set returned by the getSupportedLocales method of this ResourceBundleLoader. This method may iterate over the passed Set, so the client is responsible for ensuring that the passed Set is not modified while this method is executing.
Parameters:
preserveLocales - the set of locales to preserve
Throws:
NullPointerException - if the passed Set reference is null, or if any element in the passed Set is null
java.lang.IllegalArgumentException - if any of the elements contained in the passed Set are not Locales, or if any of the Locales contained in the passed Set are not directly supported by this ResourceBundleLoader.

hashCode

public int hashCode()
Computes the hash code for this ResourceBundleLoader.
Overrides:
hashCode in class java.lang.Object
Returns:
a hashcode value for this ResourceBundleLoader