com.artima.place.info
Class LocalizableInfo

java.lang.Object
  |
  +--com.artima.place.info.LocalizableInfo

All Implemented Interfaces:

java.lang.Cloneable, Purgable, java.io.Serializable

Direct Known Subclasses:

Description, Icons, Keywords, Name

public abstract class LocalizableInfo

extends java.lang.Object

implements java.lang.Cloneable, java.io.Serializable, Purgable

A bundle of localizable information suitable for delivery across a network.

See Also:

Serialized Form

Constructor Summary

LocalizableInfo(java.util.Locale cachedLocale)
Constructs a new LocalizableInfo with passed cached Locale and no ResourceBundleLoader.

LocalizableInfo(ResourceBundleLoader loader)
Construct a LocalizableInfo with specified ResourceBundleLoader.

LocalizableInfo(ResourceBundleLoader loader, java.util.Locale cachedLocale)
Constructs a new CachableInfo with passed ResourceBundleLoader and cached Locale.

Method Summary

void	clearCachedLocale() Nulls out the reference to the cached Locale contained in this LocalizableInfo, if any.
void	clearResourceBundleLoader() Nulls out the reference to the ResourceBundleLoader contained in this LocalizableInfo, if any.
java.lang.Object	clone() Clones this LocalizableInfo.
static boolean	compareObjectsOrNull(java.lang.Object o1, java.lang.Object o2) Utility method that returns true only if the two passed objects references are both null, or the objects are semantically equal.
boolean	equals(java.lang.Object o) Compares this LocalizableInfo to the passed object for equality.
java.util.Locale	getBestFitLocale() Returns the best-fit locale for the default locale.
java.util.Locale	getBestFitLocale(java.util.Locale desiredLocale) Returns the best-fit locale for the specified locale.
java.util.Locale	getCachedLocale() Gets a reference to the cached Locale contained in this LocalizableInfo, if one exists.
protected ResourceBundleLoader	getResourceBundleLoader() Gives subclasses a reference to the ResourceBundleLoader contained in this LocalizableInfo.
java.util.Set	getSupportedLocales() Returns an unmodifiable set of Locales which are directly supported by this LocalizableInfo.
boolean	hasCachedLocale() Indicates whether or not this LocalizableInfo contains a cached Locale.
int	hashCode() Returns a hash code for this object.
boolean	hasResourceBundleLoader() Indicates whether or not this LocalizableInfo contains a ResourceBundleLoader.
abstract void	purge() Purge away information about undesired locales.
abstract void	purge(java.util.Locale preserveLocale) Purge away information about any locales other than the passed Locale.
protected void	setCachedLocale(java.util.Locale cachedLocale) Validates and sets the cached Locale to the passed Locale.
void	stripResourceBundleLoader(java.util.Set preserveLocales) Replaces the resource bundle with a new one that contains only the locales in the passed set.
protected boolean	useCache(java.util.Locale desiredLocale) Indicates whether or not the cached locale, if any exists, should be used given a desired locale.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LocalizableInfo

public LocalizableInfo(ResourceBundleLoader loader)

Construct a LocalizableInfo with specified ResourceBundleLoader. Because ResourceBundleLoader is immutable, the passed loader may be used as part of the state of this object. The new LocalizableInfo object will start its life with no locales cache.

Parameters:

loader - the ResourceBundleLoader which can load ResourceBundles for this LocalizableInfo.

LocalizableInfo

public LocalizableInfo(java.util.Locale cachedLocale)

Constructs a new LocalizableInfo with passed cached Locale and no ResourceBundleLoader.

Parameters:

cachedLocale - the Locale for which information will be cached by subclasses.

LocalizableInfo

public LocalizableInfo(ResourceBundleLoader loader,
                       java.util.Locale cachedLocale)

Constructs a new CachableInfo with passed ResourceBundleLoader and cached Locale.

Parameters:

loader - the ResourceBundleLoader which can load ResourceBundles for this LocalizableInfo.

cachedLocale - the Locale for which information will be cached by subclasses.

Method Detail

setCachedLocale

protected final void setCachedLocale(java.util.Locale cachedLocale)

Validates and sets the cached Locale to the passed Locale.

Parameters:

cachedLocale - the Locale for which information is cached by subclasses.

getResourceBundleLoader

protected final ResourceBundleLoader getResourceBundleLoader()

Gives subclasses a reference to the ResourceBundleLoader contained in this LocalizableInfo.

Returns:

a reference to the ResourceBundleLoader, or null if this LocalizableInfo contains no ResourceBundleLoader

getCachedLocale

public final java.util.Locale getCachedLocale()

Gets a reference to the cached Locale contained in this LocalizableInfo, if one exists.

Returns:

a reference to the cached Locale, or null if this LocalizableInfo contains no cached Locale

getSupportedLocales

public java.util.Set getSupportedLocales()

Returns an unmodifiable set of Locales which are directly supported by this LocalizableInfo. The returned set will definitely include the empty (or root) Locale.

getBestFitLocale

public java.util.Locale getBestFitLocale()

Returns the best-fit locale for the default locale.

Returns:

the best-fit locale for the default locale.

getBestFitLocale

public java.util.Locale getBestFitLocale(java.util.Locale desiredLocale)

Returns the best-fit locale for the specified locale.

Parameters:

desiredLocale - the locale for which to determine a best-fit.

Returns:

the best-fit locale for the specified locale.

hasResourceBundleLoader

public final boolean hasResourceBundleLoader()

Indicates whether or not this LocalizableInfo contains a ResourceBundleLoader. This LocalizableInfo will contain no ResourceBundleLoader if it was constructed with the constructor that takes only a cached Locale, or if its ResourceBundleLoader was cleared by the clearResourceBundleLoader method.

Returns:

true if this LocalizableInfo contains a ResourceBundleLoader.

clearResourceBundleLoader

public final void clearResourceBundleLoader()

Nulls out the reference to the ResourceBundleLoader contained in this LocalizableInfo, if any. This can be invoked by the purge methods of subclasses that keep a cache of the desired locale and wish to eliminate all record of the full localizable information contained in the ResourceBundleLoader.

If this LocalizableInfo contains no cached Locale, then this method will fail with an IllegalStateException. If no cached locale exists, then clearing the ResourceBundleLoader would eliminate all possibility of getting localized information from this LocalizableInfo. To avoid this exception, invoke this method only if the hasCachedLocale method returns true. In the absence of a cached Locale, the locales supported by the ResourceBundleLoader can be reduced by calling the stripResourceBundleLoader method.

If this LocalizableInfo already contains no ResourceBundleLoader, this method throws no exception and has no effect.

stripResourceBundleLoader

public final void stripResourceBundleLoader(java.util.Set preserveLocales)

Replaces the resource bundle with a new one that contains only the locales in the passed set. If the passed set does not contain the empty Locale, the empty locale from the current ResourceBundleLoader 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 the ResourceBundleLoader, i.e., must be included in the Set returned by the getSupportedLocales method of the ResourceBundleLoader.

Parameters:

preserveLocales - a set of locales to preserve in the ResourceBundleLoader (all others will be removed).

Throws:

NullPointerException - if the ResourceBundleLoader contained in this LocalizableInfo has already been cleared, or if the passed Set reference 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 the ResourceBundleLoader.

hasCachedLocale

public final boolean hasCachedLocale()

Indicates whether or not this LocalizableInfo contains a cached Locale. This LocalizableInfo will contain no cached Locale if it was constructed with the constructor that takes only a ResourceBundleLoader and its cached Locale hasn't been installed via the setCachedLocale method, or if a cached Locale was cleared by the clearCachedLocale method.

Returns:

true if this LocalizableInfo contains a cached Locale.

clearCachedLocale

public final void clearCachedLocale()

Nulls out the reference to the cached Locale contained in this LocalizableInfo, if any.

If this LocalizableInfo contains no ResourceBundleLoader, then this method will fail with an IllegalStateException. If no ResourceBundleLoader exists, then clearing the cached Locale would eliminate all possibility of getting localized information from this LocalizableInfo. To avoid this exception, invoke this method only if the hasResourceBundleLoader method returns true.

If this LocalizableInfo already contains no cached Locale, this method throws no exception and has no effect.

useCache

protected boolean useCache(java.util.Locale desiredLocale)

Indicates whether or not the cached locale, if any exists, should be used given a desired locale. If this method returns false, then the resource or resources should be requested of the resource bundle loader rather than using the currently cached resources, if any.

Parameters:

desiredLocale - the desire locale against which to check for the appropriateness of the cached locale.

Returns:

true if the cached locale is the most appropriate (best-fit) supported locale for the passed desired locale.

purge

public abstract void purge()

Purge away information about undesired locales. Subclasses can decide how best to implement this method. Subclasses that use caches may eliminate the ResourceBundleLoader entirely by invoking clearResourceBundleLoader. Subclasses that do not use a cache may strip away undesired locales from the ResourceBundleLoader via the stripResourceBundleLoader method. Subclasses must assume the desired locale is the default locale.

In short, the contract of this method is: eliminate extraneous information about undesired locales, and keep only the ability to get at the desired locale, which is the current default locale.

Specified by:

purge in interface Purgable

purge

public abstract void purge(java.util.Locale preserveLocale)

Purge away information about any locales other than the passed Locale. Subclasses can decide how best to implement this method. Subclasses that use caches may eliminate the ResourceBundleLoader entirely by invoking clearResourceBundleLoader. Subclasses that do not use a cache may strip away undesired locales from the ResourceBundleLoader via the stripResourceBundleLoader method.

In short, the contract of this method is: eliminate extraneous information about undesired locales, and keep only the ability to get at the desired locale, which is passed as a parameter to this method.

Specified by:

purge in interface Purgable

Parameters:

preserveLocale - a locale to preserve in the ResourceBundleLoader (all others will be removed).

equals

public boolean equals(java.lang.Object o)

Compares this LocalizableInfo to the passed object for equality. To be semantically equal, the passed object must be an instanceof LocalizableInfo, both ResourceBundleLoaders must be either null or semantically equal, and both cached Locales must either be null or semantically equal.

Overrides:

equals in class java.lang.Object

Parameters:

An - object to compare to this LocalizableInfo

Returns:

true if this LocalizableInfo is semantically equal to the passed LocalizableInfo

hashCode

public int hashCode()

Returns a hash code for this object.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Clones this LocalizableInfo. This method merely returns the reference returned by its superclass's clone method. This class's instance variable hold references to two objects, a ResourceBundleLoader and a cached Locale. Because ResourceBundleLoader and Locale objects are immutable, this method need not clone them in the process of cloning the LocalizableInfo. Although this class is not itself immutable, the only state changes it supports involve replacing the ResourceBundleLoader or the cached Locale. Since this method merely returns the result of Object's implementation of clone, its only real effect is to make clone public.

Overrides:

clone in class java.lang.Object

Returns:

a clone of this method

compareObjectsOrNull

public static boolean compareObjectsOrNull(java.lang.Object o1,
                                           java.lang.Object o2)

Utility method that returns true only if the two passed objects references are both null, or the objects are semantically equal.

Parameters:

o1 - an object to compare to o2

o2 - an object to compare to o1

Returns:

true if the passed object references are both null, or if the objects they refer to are semantically equal.