org.apache.crimson.util
Class MessageCatalog

java.lang.Object
  org.apache.crimson.util.MessageCatalog

Direct Known Subclasses:

Parser2.Catalog, XmlDocument.Catalog

public abstract class MessageCatalog

extends Object

This class provides support for multi-language string lookup, as needed to localize messages from applications supporting multiple languages at the same time. One class of such applications is network services, such as HTTP servers, which talk to clients who may not be from the same locale as the server. This class supports a form of negotiation for the language used in presenting a message from some package, where both user (client) preferences and application (server) support are accounted for when choosing locales and formatting messages.

Each package should have a singleton package-private message catalog class. This ensures that the correct class loader will always be used to access message resources, and minimizes use of memory:

    package some.package;
    
    // "foo" might be public
    class foo {
	  ...
        // package private
        static final Catalog messages = new Catalog ();
        static final class Catalog extends MessageCatalog {
            Catalog () { super (Catalog.class); }
	  }
	  ...
    }
 

Messages for a known client could be generated using code something like this:

    String clientLanguages [];
    Locale clientLocale;
    String clientMessage;

    // client languages will probably be provided by client,
    // e.g. by an HTTP/1.1 "Accept-Language" header.
    clientLanguages = new String [] { "en-ca", "fr-ca", "ja", "zh" };
    clientLocale = foo.messages.chooseLocale (clientLanguages);
    clientMessage = foo.messages.getMessage (clientLocale,
        "fileCount",
	  new Object [] { new Integer (numberOfFiles) }
        );
 

At this time, this class does not include functionality permitting messages to be passed around and localized after-the-fact. The consequence of this is that the locale for messages must be passed down through layers which have no normal reason to support such passdown, or else the system default locale must be used instead of the one the client needs.

The following guidelines should be used when constructiong multi-language applications:

1. Always use chooseLocale to select the locale you pass to your getMessage call. This lets your applications use IETF standard locale names, and avoids needless use of system defaults.
2. The localized messages for a given package should always go in a separate resources sub-package. There are security implications; see below.
3. Make sure that a language name is included in each bundle name, so that the developer's locale will not be inadvertently used. That is, don't create defaults like resources/Messages.properties or resources/Messages.class, since ResourceBundle will choose such defaults rather than giving software a chance to choose a more appropriate language for its messages. Your message bundles should have names like Messages_en.properties (for the "en", or English, language) or Messages_ja.class ("ja" indicates the Japanese language).
4. Only use property files for messages in languages which can be limited to the ISO Latin/1 (8859-1) characters supported by the property file format. (This is mostly Western European languages.) Otherwise, subclass ResourceBundle to provide your messages; it is simplest to subclass java.util.ListResourceBundle.
5. Never use another package's message catalog or resource bundles. It should not be possible for a change internal to one package (such as eliminating or improving messages) to break another package.

The "resources" sub-package can be treated separately from the package with which it is associated. That main package may be sealed and possibly signed, preventing other software from adding classes to the package which would be able to access methods and data which are not designed to be publicly accessible. On the other hand, resources such as localized messages are often provided after initial product shipment, without a full release cycle for the product. Such files (text and class files) need to be added to some package. Since they should not be added to the main package, the "resources" subpackage is used without risking the security or integrity of that main package as distributed in its JAR file.

Author:

David Brownell

See Also:

Locale, ListResourceBundle, MessageFormat

Field Summary

private String	bundleName
private Hashtable	cache

Constructor Summary

protected	MessageCatalog(Class packageMember) Create a message catalog for use by classes in the same package as the specified class.
private	MessageCatalog(Class packageMember, String bundle) Create a message catalog for use by classes in the same package as the specified class.

Method Summary

private String[]	canonicalize(String[] languages)
Locale	chooseLocale(String[] languages) Chooses a client locale to use, using the first language specified in the list that is supported by this catalog.
private Locale	getLocale(String localeName)
String	getMessage(Locale locale, String messageId) Get a message localized to the specified locale, using the message ID and package name if no message is available.
String	getMessage(Locale locale, String messageId, Object[] parameters) Format a message localized to the specified locale, using the message ID with its package name if none is available.
boolean	isLocaleSupported(String localeName) Returns true iff the specified locale has explicit language support.
private String	packagePrefix(String messageId)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

bundleName

private String bundleName

cache

private Hashtable cache

Constructor Detail

MessageCatalog

protected MessageCatalog(Class packageMember)

Create a message catalog for use by classes in the same package as the specified class. This uses Messages resource bundles in the resources sub-package of class passed as a parameter.

Parameters:

packageMember - Class whose package has localized messages

MessageCatalog

private MessageCatalog(Class packageMember,
                       String bundle)

Create a message catalog for use by classes in the same package as the specified class. This uses the specified resource bundle name in the resources sub-package of class passed as a parameter; for example, resources.Messages.

Parameters:

packageMember - Class whose package has localized messages

bundle - Name of a group of resource bundles

Method Detail

getMessage

public String getMessage(Locale locale,
                         String messageId)

Get a message localized to the specified locale, using the message ID and package name if no message is available. The locale is normally that of the client of a service, chosen with knowledge that both the client and this server support that locale. There are two error cases: first, when the specified locale is unsupported or null, the default locale is used if possible; second, when no bundle supports that locale, the message ID and package name are used.

Parameters:

locale - The locale of the message to use. If this is null, the default locale will be used.

messageId - The ID of the message to use.

Returns:

The message, localized as described above.

packagePrefix

private String packagePrefix(String messageId)

getMessage

public String getMessage(Locale locale,
                         String messageId,
                         Object[] parameters)

Format a message localized to the specified locale, using the message ID with its package name if none is available. The locale is normally the client of a service, chosen with knowledge that both the client server support that locale. There are two error cases: first, if the specified locale is unsupported or null, the default locale is used if possible; second, when no bundle supports that locale, the message ID and package name are used.

Parameters:

locale - The locale of the message to use. If this is null, the default locale will be used.

messageId - The ID of the message format to use.

parameters - Used when formatting the message. Objects in this list are turned to strings if they are not Strings, Numbers, or Dates (that is, if MessageFormat would treat them as errors).

Returns:

The message, localized as described above.

See Also:

MessageFormat

chooseLocale

public Locale chooseLocale(String[] languages)

Chooses a client locale to use, using the first language specified in the list that is supported by this catalog. If none of the specified languages is supported, a null value is returned. Such a list of languages might be provided in an HTTP/1.1 "Accept-Language" header field, or through some other content negotiation mechanism.

The language specifiers recognized are RFC 1766 style ("fr" for all French, "fr-ca" for Canadian French), although only the strict ISO subset (two letter language and country specifiers) is currently supported. Java-style locale strings ("fr_CA") are also supported.

Parameters:

languages - Array of language specifiers, ordered with the most preferable one at the front. For example, "en-ca" then "fr-ca", followed by "zh_CN".

Returns:

The most preferable supported locale, or null.

See Also:

Locale

canonicalize

private String[] canonicalize(String[] languages)

getLocale

private Locale getLocale(String localeName)

isLocaleSupported

public boolean isLocaleSupported(String localeName)

Returns true iff the specified locale has explicit language support. For example, the traditional Chinese locale "zh_TW" has such support if there are message bundles suffixed with either "zh_TW" or "zh".

This method is used to bypass part of the search path mechanism of the ResourceBundle class, specifically the parts which force use of default locales and bundles. Such bypassing is required in order to enable use of a client's preferred languages. Following the above example, if a client prefers "zh_TW" but can also accept "ja", this method would be used to detect that there are no "zh_TW" resource bundles and hence that "ja" messages should be used. This bypasses the ResourceBundle mechanism which will return messages in some other locale (picking some hard-to-anticipate default) instead of reporting an error and letting the client choose another locale.

Parameters:

localeName - A standard Java locale name, using two character language codes optionally suffixed by country codes.

Returns:

True iff the language of that locale is supported.

See Also:

Locale