com.sun.xml.dtdparser.MessageCatalog Maven / Gradle / Ivy
/*
* Copyright (c) 1998, 2023 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Distribution License v. 1.0, which is available at
* http://www.eclipse.org/org/documents/edl-v10.php.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
package com.sun.xml.dtdparser;
import java.io.IOException;
import java.io.InputStream;
import java.text.FieldPosition;
import java.text.MessageFormat;
import java.util.HashMap;
import java.util.Locale;
import java.util.Map;
import java.util.MissingResourceException;
import java.util.Objects;
import java.util.ResourceBundle;
/**
* 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 pass-down, or else the system
* default locale must be used instead of the one the client needs.
*
* The following guidelines should be used when constructing
* multi-language applications:
*
* - Always use chooseLocale to select the
* locale you pass to your {@code getMessage} call. This lets your
* applications use IETF standard locale names, and avoids needless
* use of system defaults.
*
* - The localized messages for a given package should always go in
* a separate resources sub-package. There are security
* implications; see below.
*
* - 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).
*
* - 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 {@code java.util.ListResourceBundle}.
*
* - 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 java.util.Locale
* @see java.util.ListResourceBundle
* @see java.text.MessageFormat
*/
// leave this as "abstract" -- each package needs its own subclass,
// else it's not always going to be using the right class loader.
public abstract class MessageCatalog {
private String bundleName;
private MessageCatalog() {
}
/**
* 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.
*
* @param packageMember Class whose package has localized messages
*/
protected MessageCatalog(Class packageMember) {
this(packageMember, "Messages");
}
/**
* 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.
*
* @param packageMember Class whose package has localized messages
* @param bundle Name of a group of resource bundles
*/
private MessageCatalog(Class packageMember, String bundle) {
int index;
bundleName = packageMember.getName();
index = bundleName.lastIndexOf('.');
if (index == -1) // "ClassName"
{
bundleName = "";
} else // "some.package.ClassName"
{
bundleName = bundleName.substring(0, index) + ".";
}
bundleName = bundleName + "resources." + bundle;
}
/**
* 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.
*
* @param locale The locale of the message to use. If this is null,
* the default locale will be used.
* @param messageId The ID of the message to use.
* @return The message, localized as described above.
*/
public String getMessage(Locale locale,
String messageId) {
ResourceBundle bundle;
// cope with unsupported locale...
if (locale == null) {
locale = Locale.getDefault();
}
try {
bundle = ResourceBundle.getBundle(bundleName, locale);
} catch (MissingResourceException e) {
bundle = ResourceBundle.getBundle(bundleName, Locale.ENGLISH);
}
return bundle.getString(messageId);
}
/**
* 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.
*
* @param locale The locale of the message to use. If this is null,
* the default locale will be used.
* @param messageId The ID of the message format to use.
* @param 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).
* @return The message, localized as described above.
* @see java.text.MessageFormat
*/
public String getMessage(Locale locale,
String messageId,
Object[] parameters) {
if (parameters == null) {
return getMessage(locale, messageId);
}
// since most messages won't be tested (sigh), be friendly to
// the inevitable developer errors of passing random data types
// to the message formatting code.
for (int i = 0; i < parameters.length; i++) {
if (!(parameters[i] instanceof String)
&& !(parameters[i] instanceof Number)
&& !(parameters[i] instanceof java.util.Date)) {
if (parameters[i] == null) {
parameters[i] = "(null)";
} else {
parameters[i] = parameters[i].toString();
}
}
}
// similarly, cope with unsupported locale...
if (locale == null) {
locale = Locale.getDefault();
}
// get the appropriately localized MessageFormat object
ResourceBundle bundle;
MessageFormat format;
try {
bundle = ResourceBundle.getBundle(bundleName, locale);
} catch (MissingResourceException e) {
bundle = ResourceBundle.getBundle(bundleName, Locale.ENGLISH);
/*String retval;
retval = packagePrefix (messageId);
for (int i = 0; i < parameters.length; i++) {
retval += ' ';
retval += parameters [i];
}
return retval;*/
}
format = new MessageFormat(bundle.getString(messageId));
format.setLocale(locale);
// return the formatted message
StringBuffer result = new StringBuffer();
result = format.format(parameters, result, new FieldPosition(0));
return result.toString();
}
/**
* 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.
*
* @param 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".
* @return The most preferable supported locale, or null.
* @see java.util.Locale
*/
public Locale chooseLocale(String[] languages) {
if ((languages = canonicalize(languages)) != null) {
for (String language : languages) {
if (isLocaleSupported(language)) {
return getLocale(language);
}
}
}
return null;
}
//
// Canonicalizes the RFC 1766 style language strings ("en-in") to
// match standard Java usage ("en_IN"), removing strings that don't
// use two character ISO language and country codes. Avoids all
// memory allocations possible, so that if the strings passed in are
// just lowercase ISO codes (a common case) the input is returned.
//
private String[] canonicalize(String[] languages) {
boolean didClone = false;
int trimCount = 0;
if (languages == null) {
return languages;
}
for (int i = 0; i < languages.length; i++) {
String lang = languages[i];
int len = lang.length();
// no RFC1766 extensions allowed; "zh" and "zh-tw" (etc.) are OK
// as are regular locale names with no variant ("de_CH").
if (!(len == 2 || len == 5)) {
if (!didClone) {
languages = languages.clone();
didClone = true;
}
languages[i] = null;
trimCount++;
continue;
}
// language code ... if already lowercase, we change nothing
if (len == 2) {
lang = lang.toLowerCase(Locale.ENGLISH);
if (!Objects.equals(lang, languages[i])) {
if (!didClone) {
languages = languages.clone();
didClone = true;
}
languages[i] = lang;
}
continue;
}
// language_country ... fixup case, force "_"
char[] buf = new char[5];
buf[0] = Character.toLowerCase(lang.charAt(0));
buf[1] = Character.toLowerCase(lang.charAt(1));
buf[2] = '_';
buf[3] = Character.toUpperCase(lang.charAt(3));
buf[4] = Character.toUpperCase(lang.charAt(4));
if (!didClone) {
languages = languages.clone();
didClone = true;
}
languages[i] = new String(buf);
}
// purge any shadows of deleted RFC1766 extended language codes
if (trimCount != 0) {
String[] temp = new String[languages.length - trimCount];
int i;
for (i = 0, trimCount = 0; i < temp.length; i++) {
while (languages[i + trimCount] == null) {
trimCount++;
}
temp[i] = languages[i + trimCount];
}
languages = temp;
}
return languages;
}
//
// Returns a locale object supporting the specified locale, using
// a small cache to speed up some common languages and reduce the
// needless allocation of memory.
//
private Locale getLocale(String localeName) {
String language, country;
int index;
index = localeName.indexOf('_');
if (index == -1) {
//
// Special case the builtin JDK languages
//
if (localeName.equals("de")) {
return Locale.GERMAN;
}
if (localeName.equals("en")) {
return Locale.ENGLISH;
}
if (localeName.equals("fr")) {
return Locale.FRENCH;
}
if (localeName.equals("it")) {
return Locale.ITALIAN;
}
if (localeName.equals("ja")) {
return Locale.JAPANESE;
}
if (localeName.equals("ko")) {
return Locale.KOREAN;
}
if (localeName.equals("zh")) {
return Locale.CHINESE;
}
language = localeName;
country = "";
} else {
if (localeName.equals("zh_CN")) {
return Locale.SIMPLIFIED_CHINESE;
}
if (localeName.equals("zh_TW")) {
return Locale.TRADITIONAL_CHINESE;
}
//
// JDK also has constants for countries: en_GB, en_US, en_CA,
// fr_FR, fr_CA, de_DE, ja_JP, ko_KR. We don't use those.
//
language = localeName.substring(0, index);
country = localeName.substring(index + 1);
}
return new Locale.Builder().setLanguage(language).setRegion(country).build();
}
//
// cache for isLanguageSupported(), below ... key is a language
// or locale name, value is a Boolean
//
private final Map cache = new HashMap<>(5);
/**
* 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 {@code 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.
*
* @param localeName A standard Java locale name, using two character
* language codes optionally suffixed by country codes.
* @return True iff the language of that locale is supported.
* @see java.util.Locale
*/
public boolean isLocaleSupported(String localeName) {
//
// Use previous results if possible. We expect that the codebase
// is immutable, so we never worry about changing the cache.
//
Boolean value = cache.get(localeName);
if (value != null) {
return value;
}
//
// Try "language_country_variant", then "language_country",
// then finally "language" ... assuming the longest locale name
// is passed. If not, we'll try fewer options.
//
ClassLoader loader = null;
for (; ;) {
String name = bundleName + "_" + localeName;
// look up classes ...
try {
Class.forName(name);
cache.put(localeName, Boolean.TRUE);
return true;
} catch (ClassNotFoundException e) {
}
// ... then property files (only for ISO Latin/1 messages)
InputStream in = null;
if (loader == null) {
loader = getClass().getClassLoader();
}
name = name.replace('.', '/');
name = name + ".properties";
try {
if (loader == null) {
in = ClassLoader.getSystemResourceAsStream(name);
} else {
in = loader.getResourceAsStream(name);
}
if (in != null) {
cache.put(localeName, Boolean.TRUE);
return true;
}
} finally {
if (in != null) {
try {
in.close();
} catch (IOException ioe) {}
}
}
int index = localeName.indexOf('_');
if (index > 0) {
localeName = localeName.substring(0, index);
} else {
break;
}
}
//
// If we got this far, we failed. Remember for later.
//
cache.put(localeName, Boolean.FALSE);
return false;
}
}