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.