messagecatalog.java

来自「java jdk 1.4的源码」· Java 代码 · 共 574 行 · 第 1/2 页

/*
 * $Id: MessageCatalog.java,v 1.1.1.1 2000/11/23 01:53:35 edwingo Exp $
 *
 * The Apache Software License, Version 1.1
 *
 *
 * Copyright (c) 2000 The Apache Software Foundation.  All rights 
 * reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer. 
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. The end-user documentation included with the redistribution,
 *    if any, must include the following acknowledgment:  
 *       "This product includes software developed by the
 *        Apache Software Foundation (http://www.apache.org/)."
 *    Alternately, this acknowledgment may appear in the software itself,
 *    if and wherever such third-party acknowledgments normally appear.
 *
 * 4. The names "Crimson" and "Apache Software Foundation" must
 *    not be used to endorse or promote products derived from this
 *    software without prior written permission. For written 
 *    permission, please contact [e-mail].
 *
 * 5. Products derived from this software may not be called "Apache",
 *    nor may "Apache" appear in their name, without prior written
 *    permission of the Apache Software Foundation.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of the Apache Software Foundation and was
 * originally based on software copyright (c) 1999, Sun Microsystems, Inc., 
 * http://www.sun.com.  For more information on the Apache Software 
 * Foundation, please see <http://www.apache.org/>.
 */

package org.apache.crimson.util;

import java.io.InputStream;
import java.text.FieldPosition;
import java.text.MessageFormat;
import java.util.Hashtable;
import java.util.Locale;
import java.util.MissingResourceException;
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.
 *
 * <P> 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: <PRE>
 *    package <em>some.package</em>;
 *    
 *    // "foo" might be public
 *    class foo {
 *	  ...
 *        // package private
 *        static final Catalog messages = new Catalog ();
 *        static final class Catalog extends MessageCatalog {
 *            Catalog () { super (Catalog.class); }
 *	  }
 *	  ...
 *    }
 * </PRE>
 *
 * <P> Messages for a known client could be generated using code
 * something like this:  <PRE>
 *    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) }
 *        );
 * </PRE>
 *
 * <P> 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.
 *
 * <P> <hr> The following guidelines should be used when constructiong
 * multi-language applications:  <OL>
 *
 *	<LI> Always use <a href=#chooseLocale>chooseLocale</a> to select the
 *	locale you pass to your <code>getMessage</code> call.  This lets your
 *	applications use IETF standard locale names, and avoids needless
 *	use of system defaults.
 *
 *	<LI> The localized messages for a given package should always go in
 *	a separate <em>resources</em> sub-package.  There are security
 *	implications; see below.
 *
 *	<LI> 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 <em>resources/Messages.properties</em>
 *	or <em>resources/Messages.class</em>, 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 <em>Messages_en.properties</em> (for the "en", or
 *	English, language) or <em>Messages_ja.class</em> ("ja" indicates the
 *	Japanese language).
 *
 *	<LI> 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</code>.
 *
 *	<LI> 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.
 *
 *	</OL>
 *	
 * <P> 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.
 *
 * @see java.util.Locale
 * @see java.util.ListResourceBundle
 * @see java.text.MessageFormat
 *
 * @version 1.10
 * @author David Brownell
 */
// leave this as "abstract" -- each package needs its own subclass,
// else it's not always going to be using the right class loader.
abstract public class MessageCatalog {
    private String			bundleName;

    /**
     * Create a message catalog for use by classes in the same package
     * as the specified class.  This uses <em>Messages</em> resource
     * bundles in the <em>resources</em> 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 <em>resources</em> sub-package of class passed
     * as a parameter; for example, <em>resources.Messages</em>.
     *
     * @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);
	    return bundle.getString (messageId);
	} catch (MissingResourceException e) {
	    return packagePrefix (messageId);
	} 
    }

    private String packagePrefix (String messageId)
    {
	String	temp = getClass ().getName ();
	int	index = temp.lastIndexOf ('.');

	if (index == -1)	// "ClassName"
	    temp = "";
	else			// "some.package.ClassName"
	    temp = temp.substring (0, index);
	return temp + '/' + 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.
     *
     * @see java.text.MessageFormat
     *
     * @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.
     */
    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.