Java Doc for MessageCatalog.java in  » 6.0-JDK-Modules » jaxb-xjc » com » sun » xml » dtdparser » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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.

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
version:
   1.1, 00/08/05
See Also:   java.util.Locale
See Also:   java.util.ListResourceBundle
See Also:   java.text.MessageFormat

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.

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 mostpreferable one at the front. For example, "en-ca" then "fr-ca",followed by "zh_CN". The most preferable supported locale, or null.
See Also:   java.util.Locale

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 characterlanguage codes optionally suffixed by country codes. True iff the language of that locale is supported.
See Also:   java.util.Locale