Java tutorial
/* * $Id: MessageResources.java 471754 2006-11-06 14:55:09Z husted $ * * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, * software distributed under the License is distributed on an * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY * KIND, either express or implied. See the License for the * specific language governing permissions and limitations * under the License. */ package org.apache.struts.util; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; import java.io.Serializable; import java.text.MessageFormat; import java.util.HashMap; import java.util.Locale; /** * General purpose abstract class that describes an API for retrieving * Locale-sensitive messages from underlying resource locations of an * unspecified design, and optionally utilizing the <code>MessageFormat</code> * class to produce internationalized messages with parametric replacement. * <p> Calls to <code>getMessage()</code> variants without a * <code>Locale</code> argument are presumed to be requesting a message string * in the default <code>Locale</code> for this JVM. <p> Calls to * <code>getMessage()</code> with an unknown key, or an unknown * <code>Locale</code> will return <code>null</code> if the * <code>returnNull</code> property is set to <code>true</code>. Otherwise, a * suitable error message will be returned instead. <p> <strong>IMPLEMENTATION * NOTE</strong> - Classes that extend this class must be Serializable so that * instances may be used in distributable application server environments. * * @version $Rev: 471754 $ $Date: 2005-08-29 23:57:50 -0400 (Mon, 29 Aug 2005) * $ */ public abstract class MessageResources implements Serializable { // ------------------------------------------------------------- Properties /** * Commons Logging instance. */ protected static Log log = LogFactory.getLog(MessageResources.class); // --------------------------------------------------------- Static Methods /** * The default MessageResourcesFactory used to create MessageResources * instances. */ protected static MessageResourcesFactory defaultFactory = null; /** * The configuration parameter used to initialize this MessageResources. */ protected String config = null; /** * The default Locale for our environment. */ protected Locale defaultLocale = Locale.getDefault(); /** * The <code>MessageResourcesFactory</code> that created this instance. */ protected MessageResourcesFactory factory = null; /** * The set of previously created MessageFormat objects, keyed by the key * computed in <code>messageKey()</code>. */ protected HashMap formats = new HashMap(); /** * Indicate is a <code>null</code> is returned instead of an error message * string when an unknown Locale or key is requested. */ protected boolean returnNull = false; /** * Indicates whether 'escape processing' should be performed on the error * message string. */ private boolean escape = true; // ----------------------------------------------------------- Constructors /** * Construct a new MessageResources according to the specified * parameters. * * @param factory The MessageResourcesFactory that created us * @param config The configuration parameter for this MessageResources */ public MessageResources(MessageResourcesFactory factory, String config) { this(factory, config, false); } /** * Construct a new MessageResources according to the specified * parameters. * * @param factory The MessageResourcesFactory that created us * @param config The configuration parameter for this * MessageResources * @param returnNull The returnNull property we should initialize with */ public MessageResources(MessageResourcesFactory factory, String config, boolean returnNull) { super(); this.factory = factory; this.config = config; this.returnNull = returnNull; } /** * The configuration parameter used to initialize this MessageResources. * * @return parameter used to initialize this MessageResources */ public String getConfig() { return (this.config); } /** * The <code>MessageResourcesFactory</code> that created this instance. * * @return <code>MessageResourcesFactory</code> that created instance */ public MessageResourcesFactory getFactory() { return (this.factory); } /** * Indicates that a <code>null</code> is returned instead of an error * message string if an unknown Locale or key is requested. * * @return true if null is returned if unknown key or locale is requested */ public boolean getReturnNull() { return (this.returnNull); } /** * Indicates that a <code>null</code> is returned instead of an error * message string if an unknown Locale or key is requested. * * @param returnNull true Indicates that a <code>null</code> is returned * if an unknown Locale or key is requested. */ public void setReturnNull(boolean returnNull) { this.returnNull = returnNull; } /** * Indicates whether 'escape processing' should be performed on the error * message string. * * @since Struts 1.2.8 */ public boolean isEscape() { return escape; } /** * Set whether 'escape processing' should be performed on the error * message string. * * @since Struts 1.2.8 */ public void setEscape(boolean escape) { this.escape = escape; } // --------------------------------------------------------- Public Methods /** * Returns a text message for the specified key, for the default Locale. * * @param key The message key to look up */ public String getMessage(String key) { return this.getMessage((Locale) null, key, null); } /** * Returns a text message after parametric replacement of the specified * parameter placeholders. * * @param key The message key to look up * @param args An array of replacement parameters for placeholders */ public String getMessage(String key, Object[] args) { return this.getMessage((Locale) null, key, args); } /** * Returns a text message after parametric replacement of the specified * parameter placeholders. * * @param key The message key to look up * @param arg0 The replacement for placeholder {0} in the message */ public String getMessage(String key, Object arg0) { return this.getMessage((Locale) null, key, arg0); } /** * Returns a text message after parametric replacement of the specified * parameter placeholders. * * @param key The message key to look up * @param arg0 The replacement for placeholder {0} in the message * @param arg1 The replacement for placeholder {1} in the message */ public String getMessage(String key, Object arg0, Object arg1) { return this.getMessage((Locale) null, key, arg0, arg1); } /** * Returns a text message after parametric replacement of the specified * parameter placeholders. * * @param key The message key to look up * @param arg0 The replacement for placeholder {0} in the message * @param arg1 The replacement for placeholder {1} in the message * @param arg2 The replacement for placeholder {2} in the message */ public String getMessage(String key, Object arg0, Object arg1, Object arg2) { return this.getMessage((Locale) null, key, arg0, arg1, arg2); } /** * Returns a text message after parametric replacement of the specified * parameter placeholders. * * @param key The message key to look up * @param arg0 The replacement for placeholder {0} in the message * @param arg1 The replacement for placeholder {1} in the message * @param arg2 The replacement for placeholder {2} in the message * @param arg3 The replacement for placeholder {3} in the message */ public String getMessage(String key, Object arg0, Object arg1, Object arg2, Object arg3) { return this.getMessage((Locale) null, key, arg0, arg1, arg2, arg3); } /** * Returns a text message for the specified key, for the default Locale. A * null string result will be returned by this method if no relevant * message resource is found for this key or Locale, if the * <code>returnNull</code> property is set. Otherwise, an appropriate * error message will be returned. <p> This method must be implemented by * a concrete subclass. * * @param locale The requested message Locale, or <code>null</code> for * the system default Locale * @param key The message key to look up */ public abstract String getMessage(Locale locale, String key); /** * Returns a text message after parametric replacement of the specified * parameter placeholders. A null string result will be returned by this * method if no resource bundle has been configured. * * @param locale The requested message Locale, or <code>null</code> for * the system default Locale * @param key The message key to look up * @param args An array of replacement parameters for placeholders */ public String getMessage(Locale locale, String key, Object[] args) { // Cache MessageFormat instances as they are accessed if (locale == null) { locale = defaultLocale; } MessageFormat format = null; String formatKey = messageKey(locale, key); synchronized (formats) { format = (MessageFormat) formats.get(formatKey); if (format == null) { String formatString = getMessage(locale, key); if (formatString == null) { return returnNull ? null : ("???" + formatKey + "???"); } format = new MessageFormat(escape(formatString)); format.setLocale(locale); formats.put(formatKey, format); } } return format.format(args); } /** * Returns a text message after parametric replacement of the specified * parameter placeholders. A null string result will never be returned by * this method. * * @param locale The requested message Locale, or <code>null</code> for * the system default Locale * @param key The message key to look up * @param arg0 The replacement for placeholder {0} in the message */ public String getMessage(Locale locale, String key, Object arg0) { return this.getMessage(locale, key, new Object[] { arg0 }); } /** * Returns a text message after parametric replacement of the specified * parameter placeholders. A null string result will never be returned by * this method. * * @param locale The requested message Locale, or <code>null</code> for * the system default Locale * @param key The message key to look up * @param arg0 The replacement for placeholder {0} in the message * @param arg1 The replacement for placeholder {1} in the message */ public String getMessage(Locale locale, String key, Object arg0, Object arg1) { return this.getMessage(locale, key, new Object[] { arg0, arg1 }); } /** * Returns a text message after parametric replacement of the specified * parameter placeholders. A null string result will never be returned by * this method. * * @param locale The requested message Locale, or <code>null</code> for * the system default Locale * @param key The message key to look up * @param arg0 The replacement for placeholder {0} in the message * @param arg1 The replacement for placeholder {1} in the message * @param arg2 The replacement for placeholder {2} in the message */ public String getMessage(Locale locale, String key, Object arg0, Object arg1, Object arg2) { return this.getMessage(locale, key, new Object[] { arg0, arg1, arg2 }); } /** * Returns a text message after parametric replacement of the specified * parameter placeholders. A null string result will never be returned by * this method. * * @param locale The requested message Locale, or <code>null</code> for * the system default Locale * @param key The message key to look up * @param arg0 The replacement for placeholder {0} in the message * @param arg1 The replacement for placeholder {1} in the message * @param arg2 The replacement for placeholder {2} in the message * @param arg3 The replacement for placeholder {3} in the message */ public String getMessage(Locale locale, String key, Object arg0, Object arg1, Object arg2, Object arg3) { return this.getMessage(locale, key, new Object[] { arg0, arg1, arg2, arg3 }); } /** * Return <code>true</code> if there is a defined message for the * specified key in the system default locale. * * @param key The message key to look up */ public boolean isPresent(String key) { return this.isPresent(null, key); } /** * Return <code>true</code> if there is a defined message for the * specified key in the specified Locale. * * @param locale The requested message Locale, or <code>null</code> for * the system default Locale * @param key The message key to look up */ public boolean isPresent(Locale locale, String key) { String message = getMessage(locale, key); if (message == null) { return false; } else if (message.startsWith("???") && message.endsWith("???")) { return false; // FIXME - Only valid for default implementation } else { return true; } } // ------------------------------------------------------ Protected Methods /** * Escape any single quote characters that are included in the specified * message string. * * @param string The string to be escaped */ protected String escape(String string) { if (!isEscape()) { return string; } if ((string == null) || (string.indexOf('\'') < 0)) { return string; } int n = string.length(); StringBuffer sb = new StringBuffer(n); for (int i = 0; i < n; i++) { char ch = string.charAt(i); if (ch == '\'') { sb.append('\''); } sb.append(ch); } return sb.toString(); } /** * Compute and return a key to be used in caching information by a Locale. * <strong>NOTE</strong> - The locale key for the default Locale in our * environment is a zero length String. * * @param locale The locale for which a key is desired */ protected String localeKey(Locale locale) { return (locale == null) ? "" : locale.toString(); } /** * Compute and return a key to be used in caching information by Locale * and message key. * * @param locale The Locale for which this format key is calculated * @param key The message key for which this format key is calculated */ protected String messageKey(Locale locale, String key) { return (localeKey(locale) + "." + key); } /** * Compute and return a key to be used in caching information by locale * key and message key. * * @param localeKey The locale key for which this cache key is calculated * @param key The message key for which this cache key is * calculated */ protected String messageKey(String localeKey, String key) { return (localeKey + "." + key); } /** * Create and return an instance of <code>MessageResources</code> for the * created by the default <code>MessageResourcesFactory</code>. * * @param config Configuration parameter for this message bundle. */ public synchronized static MessageResources getMessageResources(String config) { if (defaultFactory == null) { defaultFactory = MessageResourcesFactory.createFactory(); } return defaultFactory.createResources(config); } /** * Log a message to the Writer that has been configured for our use. * * @param message The message to be logged */ public void log(String message) { log.debug(message); } /** * Log a message and exception to the Writer that has been configured for * our use. * * @param message The message to be logged * @param throwable The exception to be logged */ public void log(String message, Throwable throwable) { log.debug(message, throwable); } }