< prev index next >
src/jdk.xml.bind/share/classes/com/sun/xml/internal/dtdparser/MessageCatalog.java
Print this page
*** 1,7 ****
/*
! * Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
--- 1,7 ----
/*
! * Copyright (c) 1998, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
*** 41,135 ****
* 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/>
! * <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>;
! * <p/>
* // "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/>
! * <P> Messages for a known client could be generated using code
! * something like this: <PRE>
* String clientLanguages [];
* Locale clientLocale;
* String clientMessage;
! * <p/>
* // 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/>
! * <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/>
! * <P> <hr> The following guidelines should be used when constructiong
! * multi-language applications: <OL>
! * <p/>
! * <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.
! * <p/>
! * <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.
! * <p/>
! * <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).
! * <p/>
! * <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>.
! * <p/>
! * <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.
! * <p/>
! * </OL>
! * <p/>
! * <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.
*
* @author David Brownell
* @version 1.1, 00/08/05
* @see java.util.Locale
* @see java.util.ListResourceBundle
--- 41,134 ----
* 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:</p><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:</p><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>
! *
! * <p> The following guidelines should be used when constructiong
! * multi-language applications:</p>
! * <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>
! *
! * <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>
! *
! * <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>
! *
! * <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>
! *
! * <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.</li>
! *</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.</p>
*
* @author David Brownell
* @version 1.1, 00/08/05
* @see java.util.Locale
* @see java.util.ListResourceBundle
*** 279,293 ****
* 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.
! * <p/>
! * <P> 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.
--- 278,292 ----
* 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.
! *
! * <p> 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.</p>
*
* @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.
*** 333,343 ****
continue;
}
// language code ... if already lowercase, we change nothing
if (len == 2) {
! lang = lang.toLowerCase();
if (lang != languages[i]) {
if (!didClone) {
languages = (String[]) languages.clone();
didClone = true;
}
--- 332,342 ----
continue;
}
// language code ... if already lowercase, we change nothing
if (len == 2) {
! lang = lang.toLowerCase(Locale.ENGLISH);
if (lang != languages[i]) {
if (!didClone) {
languages = (String[]) languages.clone();
didClone = true;
}
*** 435,445 ****
/**
* 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".
! * <p/>
* <P> This method is used to bypass part of the search path mechanism
* of the <code>ResourceBundle</code> 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
--- 434,444 ----
/**
* 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".
! *
* <P> This method is used to bypass part of the search path mechanism
* of the <code>ResourceBundle</code> 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
< prev index next >