/*
* This library is part of OpenCms -
* the Open Source Content Management System
*
* Copyright (c) Alkacon Software GmbH (http://www.alkacon.com)
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* For further information about Alkacon Software GmbH, please see the
* company website: http://www.alkacon.com
*
* For further information about OpenCms, please see the
* project website: http://www.opencms.org
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
package org.opencms.i18n;
import org.opencms.main.CmsLog;
import org.opencms.util.CmsDateUtil;
import org.opencms.util.CmsStringUtil;
import java.text.DateFormat;
import java.text.MessageFormat;
import java.util.Date;
import java.util.Locale;
import java.util.MissingResourceException;
import java.util.ResourceBundle;
import org.apache.commons.logging.Log;
/**
* Reads localized resource Strings from a <code>java.util.ResourceBundle</code>
* and provides convenience methods to access the Strings from a template.<p>
*
* This class is frequently used from JSP templates. Because of that, throwing of
* exceptions related to the access of the resource bundle are suppressed
* so that a template always execute. The class provides an {@link #isInitialized()} method
* that can be checked to see if the instance was properly initialized.<p>
*
* @since 6.0.0
*/
public class CmsMessages {
/** The suffix of a "short" localized key name. */
public static final String KEY_SHORT_SUFFIX = ".short";
/** Prefix / Suffix for unknown keys. */
public static final String UNKNOWN_KEY_EXTENSION = "???";
/** The log object for this class. */
private static final Log LOG = CmsLog.getLog(CmsMessages.class);
/** The resource bundle base name this object was initialized with. */
private String m_bundleName;
/** The locale to use for looking up the messages from the bundle. */
private Locale m_locale;
/** The resource bundle this message object was initialized with. */
private ResourceBundle m_resourceBundle;
/**
* Constructor for the messages with an initialized <code>java.util.Locale</code>.
*
* @param bundleName the base ResourceBundle name
* @param locale the m_locale to use, eg. "de", "en" etc.
*/
public CmsMessages(String bundleName, Locale locale) {
try {
m_locale = locale;
m_bundleName = bundleName;
m_resourceBundle = CmsResourceBundleLoader.getBundle(bundleName, m_locale);
} catch (MissingResourceException e) {
m_resourceBundle = null;
} catch (Exception e) {
m_resourceBundle = null;
LOG.error(Messages.get().getBundle().key(Messages.ERR_CREATING_MESSAGES_2, bundleName, m_locale), e);
}
}
/**
* Constructor for the messages with a language string.<p>
*
* The <code>language</code> is a 2 letter language ISO code, e.g. <code>"EN"</code>.<p>
*
* The Locale for the messages will be created like this:<br>
* <code>new Locale(language, "", "")</code>.<p>
*
* @param bundleName the base ResourceBundle name
* @param language ISO language indentificator for the m_locale of the bundle
*/
public CmsMessages(String bundleName, String language) {
this(bundleName, language, "", "");
}
/**
* Constructor for the messages with language and country code strings.<p>
*
* The <code>language</code> is a 2 letter language ISO code, e.g. <code>"EN"</code>.
* The <code>country</code> is a 2 letter country ISO code, e.g. <code>"us"</code>.<p>
*
* The Locale for the messages will be created like this:<br>
* <code>new Locale(language, country, "")</code>.
*
* @param bundleName the base ResourceBundle name
* @param language ISO language indentificator for the m_locale of the bundle
* @param country ISO 2 letter country code for the m_locale of the bundle
*/
public CmsMessages(String bundleName, String language, String country) {
this(bundleName, language, country, "");
}
/**
* Constructor for the messages with language, country code and variant strings.<p>
*
* The <code>language</code> is a 2 letter language ISO code, e.g. <code>"EN"</code>.
* The <code>country</code> is a 2 letter country ISO code, e.g. <code>"us"</code>.
* The <code>variant</code> is a vendor or browser-specific code, e.g. <code>"POSIX"</code>.<p>
*
* The Locale for the messages will be created like this:<br>
* <code>new Locale(language, country, variant)</code>.
*
* @param bundleName the base ResourceBundle name
* @param language language indentificator for the m_locale of the bundle
* @param country 2 letter country code for the m_locale of the bundle
* @param variant a vendor or browser-specific variant code
*/
public CmsMessages(String bundleName, String language, String country, String variant) {
this(bundleName, new Locale(language, country, variant));
}
/**
* Empty constructor for subclassing.<p>
*/
protected CmsMessages() {
// empty constructor for subclassing
}
/**
* Formats an unknown key.<p>
*
* @param keyName the key to format
* @return the formatted unknown key
*
* @see #isUnknownKey(String)
*/
public static String formatUnknownKey(String keyName) {
StringBuffer buf = new StringBuffer(64);
buf.append(UNKNOWN_KEY_EXTENSION);
buf.append(" ");
buf.append(keyName);
buf.append(" ");
buf.append(UNKNOWN_KEY_EXTENSION);
return buf.toString();
}
/**
* Returns <code>true</code> if the provided value matches the scheme
* <code>"??? " + keyName + " ???"</code>, that is the value appears to be an unknown key.<p>
*
* Also returns <code>true</code> if the given value is <code>null</code>.<p>
*
* @param value the value to check
* @return true if the value is matches the scheme for unknown keys
*
* @see #formatUnknownKey(String)
*/
public static boolean isUnknownKey(String value) {
return (value == null) || (value.startsWith(UNKNOWN_KEY_EXTENSION));
}
/**
* @see java.lang.Object#equals(java.lang.Object)
*/
@Override
public boolean equals(Object obj) {
if (obj == this) {
return true;
}
if (obj instanceof CmsMultiMessages) {
return false;
}
if (obj instanceof CmsMessages) {
CmsMessages other = (CmsMessages)obj;
return other.getBundleName().equals(m_bundleName) && other.getLocale().equals(m_locale);
}
return false;
}
/**
* Returns a formated date String from a Date value,
* the format being {@link DateFormat#SHORT} and the locale
* based on this instance.<p>
*
* @param date the Date object to format as String
* @return the formatted date
*/
public String getDate(Date date) {
return CmsDateUtil.getDate(date, DateFormat.SHORT, m_locale);
}
/**
* Returns a formated date String from a Date value,
* the formatting based on the provided option and the locale
* based on this instance.<p>
*
* @param date the Date object to format as String
* @param format the format to use, see {@link CmsMessages} for possible values
* @return the formatted date
*/
public String getDate(Date date, int format) {
return CmsDateUtil.getDate(date, format, m_locale);
}
/**
* Returns a formated date String from a timestamp value,
* the format being {@link DateFormat#SHORT} and the locale
* based on this instance.<p>
*
* @param time the time value to format as date
* @return the formatted date
*/
public String getDate(long time) {
return CmsDateUtil.getDate(new Date(time), DateFormat.SHORT, m_locale);
}
/**
* Returns a formated date and time String from a Date value,
* the format being {@link DateFormat#SHORT} and the locale
* based on this instance.<p>
*
* @param date the Date object to format as String
* @return the formatted date and time
*/
public String getDateTime(Date date) {
return CmsDateUtil.getDateTime(date, DateFormat.SHORT, m_locale);
}
/**
* Returns a formated date and time String from a Date value,
* the formatting based on the provided option and the locale
* based on this instance.<p>
*
* @param date the Date object to format as String
* @param format the format to use, see {@link CmsMessages} for possible values
* @return the formatted date and time
*/
public String getDateTime(Date date, int format) {
return CmsDateUtil.getDateTime(date, format, m_locale);
}
/**
* Returns a formated date and time String from a timestamp value,
* the format being {@link DateFormat#SHORT} and the locale
* based on this instance.<p>
*
* @param time the time value to format as date
* @return the formatted date and time
*/
public String getDateTime(long time) {
return CmsDateUtil.getDateTime(new Date(time), DateFormat.SHORT, m_locale);
}
/**
* Returns the locale to use for looking up this messages.<p>
*
* @return the locale to use for looking up this messages
*/
public Locale getLocale() {
return m_locale;
}
/**
* Returns the resource bundle this message object was initialized with.<p>
*
* @return the resource bundle this message object was initialized with or null if initialization was not successful
*/
public ResourceBundle getResourceBundle() {
return m_resourceBundle;
}
/**
* Directly calls the getString(String) method of the wrapped ResourceBundle.<p>
*
* If you use this this class on a template, you should consider using
* the {@link #key(String)} method to get the value from the ResourceBundle because it
* handles the exception for you in a convenient way.
*
* @param keyName the key
* @return the resource string for the given key
*
* @throws CmsMessageException in case the key is not found or the bundle is not initialized
*/
public String getString(String keyName) throws CmsMessageException {
if (m_resourceBundle != null) {
try {
return m_resourceBundle.getString(keyName);
} catch (MissingResourceException e) {
throw new CmsMessageException(Messages.get().container(
Messages.ERR_CANT_FIND_RESOURCE_FOR_BUNDLE_2,
keyName,
m_bundleName));
}
} else {
throw new CmsMessageException(Messages.get().container(
Messages.ERR_MESSAGE_BUNDLE_NOT_INITIALIZED_1,
m_bundleName));
}
}
/**
* @see java.lang.Object#hashCode()
*/
@Override
public int hashCode() {
return m_locale.hashCode() + (m_bundleName == null ? 0 : m_bundleName.hashCode());
}
/**
* Checks if the bundle was properly initialized.
*
* @return <code>true</code> if bundle was initialized, <code>false</code> otherwise
*/
public boolean isInitialized() {
return (m_resourceBundle != null);
}
/**
* Returns the localized resource string for a given message key.<p>
*
* If the key was not found in the bundle, the return value is
* <code>"??? " + keyName + " ???"</code>. This will also be returned
* if the bundle was not properly initialized first.
*
* @param keyName the key for the desired string
* @return the resource string for the given key
*/
public String key(String keyName) {
return key(keyName, false);
}
/**
* Returns the localized resource string for a given message key.<p>
*
* If the key was not found in the bundle, the return value
* depends on the setting of the allowNull parameter. If set to false,
* the return value is always a String in the format
* <code>"??? " + keyName + " ???"</code>.
* If set to true, null is returned if the key is not found.
* This will also be returned
* if the bundle was not properly initialized first.
*
* @param keyName the key for the desired string
* @param allowNull if true, 'null' is an allowed return value
* @return the resource string for the given key
*/
public String key(String keyName, boolean allowNull) {
try {
if (m_resourceBundle != null) {
return m_resourceBundle.getString(keyName);
}
} catch (MissingResourceException e) {
// not found, return warning
if (allowNull) {
return null;
}
}
return formatUnknownKey(keyName);
}
/**
* Returns the selected localized message for the initialized resource bundle and locale.<p>
*
* Convenience method for messages with one argument.<p>
*
* @param key the message key
* @param arg0 the message argument
*
* @return the selected localized message for the initialized resource bundle and locale
*/
public String key(String key, Object arg0) {
return key(key, new Object[] {arg0});
}
/**
* Returns the selected localized message for the initialized resource bundle and locale.<p>
*
* Convenience method for messages with two arguments.<p>
*
* @param key the message key
* @param arg0 the first message argument
* @param arg1 the second message argument
*
* @return the selected localized message for the initialized resource bundle and locale
*/
public String key(String key, Object arg0, Object arg1) {
return key(key, new Object[] {arg0, arg1});
}
/**
* Returns the selected localized message for the initialized resource bundle and locale.<p>
*
* Convenience method for messages with three arguments.<p>
*
* @param key the message key
* @param arg0 the first message argument
* @param arg1 the second message argument
* @param arg2 the third message argument
*
* @return the selected localized message for the initialized resource bundle and locale
*/
public String key(String key, Object arg0, Object arg1, Object arg2) {
return key(key, new Object[] {arg0, arg1, arg2});
}
/**
* Returns the selected localized message for the initialized resource bundle and locale.<p>
*
* If the key was found in the bundle, it will be formatted using
* a <code>{@link MessageFormat}</code> using the provided parameters.<p>
*
* If the key was not found in the bundle, the return value is
* <code>"??? " + keyName + " ???"</code>. This will also be returned
* if the bundle was not properly initialized first.
*
* @param key the message key
* @param args the message arguments
*
* @return the selected localized message for the initialized resource bundle and locale
*/
public String key(String key, Object[] args) {
if ((args == null) || (args.length == 0)) {
// no parameters available, use simple key method
return key(key);
}
String result = key(key, true);
if (result == null) {
// key was not found
result = formatUnknownKey(key);
} else {
// key was found in the bundle - create and apply the formatter
MessageFormat formatter = new MessageFormat(result, m_locale);
result = formatter.format(args);
}
// return the result
return result;
}
/**
* Returns the localized resource string for a given message key.<p>
*
* If the key was not found in the bundle, the provided default value
* is returned.<p>
*
* @param keyName the key for the desired string
* @param defaultValue the default value in case the key does not exist in the bundle
* @return the resource string for the given key it it exists, or the given default if not
*/
public String keyDefault(String keyName, String defaultValue) {
String result = key(keyName, true);
return (result == null) ? defaultValue : result;
}
/**
* Returns the localized resource string for a given message key,
* treating all values appended with "|" as replacement parameters.<p>
*
* If the key was found in the bundle, it will be formatted using
* a <code>{@link MessageFormat}</code> using the provided parameters.
* The parameters have to be appended to the key separated by a "|".
* For example, the keyName <code>error.message|First|Second</code>
* would use the key <code>error.message</code> with the parameters
* <code>First</code> and <code>Second</code>. This would be the same as calling
* <code>{@link CmsMessages#key(String, Object[])}</code>.<p>
*
* If no parameters are appended with "|", this is the same as calling
* <code>{@link CmsMessages#key(String)}</code>.<p>
*
* If the key was not found in the bundle, the return value is
* <code>"??? " + keyName + " ???"</code>. This will also be returned
* if the bundle was not properly initialized first.
*
* @param keyName the key for the desired string, optinally containing parameters appended with a "|"
* @return the resource string for the given key
*
* @see #key(String, Object[])
* @see #key(String)
*/
public String keyWithParams(String keyName) {
if (keyName.indexOf('|') == -1) {
// no separator found, key has no parameters
return key(keyName, false);
} else {
// this key contains parameters
String[] values = CmsStringUtil.splitAsArray(keyName, '|');
String cutKeyName = values[0];
String[] params = new String[values.length - 1];
System.arraycopy(values, 1, params, 0, params.length);
return key(cutKeyName, params);
}
}
/**
* @see java.lang.Object#toString()
*/
@Override
public String toString() {
StringBuffer result = new StringBuffer();
result.append('[');
result.append(this.getClass().getName());
result.append(", baseName: ");
result.append(m_bundleName);
result.append(", locale: ");
result.append(getLocale());
result.append(']');
return result.toString();
}
/**
* Returns the name of the resource bundle this object was initialized with.<p>
*
* @return the name of the resource bundle this object was initialized with
*/
protected String getBundleName() {
return m_bundleName;
}
/**
* Sets the bundleName.<p>
*
* @param bundleName the bundleName to set
*/
protected void setBundleName(String bundleName) {
m_bundleName = bundleName;
}
/**
* Sets the locale.<p>
*
* @param locale the locale to set
*/
protected void setLocale(Locale locale) {
m_locale = locale;
}
/**
* Sets the resource bundle.<p>
*
* @param resourceBundle the resource bundle to set
*/
protected void setResourceBundle(ResourceBundle resourceBundle) {
m_resourceBundle = resourceBundle;
}
}