org.opencms.i18n
Class CmsMessages

java.lang.Object
  org.opencms.i18n.CmsMessages

Direct Known Subclasses:

CmsMultiMessages

public class CmsMessages
extends Object

Reads localized resource Strings from a java.util.ResourceBundle and provides convenience methods to access the Strings from a template.

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 isInitialized() method that can be checked to see if the instance was properly initialized.

Since:

6.0.0

Version:

$Revision: 1.22 $

Author:

Alexander Kandzior

Field Summary

static String	KEY_SHORT_SUFFIX The suffix of a "short" localized key name.
protected String	m_baseName The resource bundle base name this object was initialized with.
protected Locale	m_locale The locale to use for looking up the messages from the bundle.
protected ResourceBundle	m_resourceBundle The resource bundle this message object was initialized with.
static String	UNKNOWN_KEY_EXTENSION Prefix / Suffix for unknown keys.

Constructor Summary

protected	CmsMessages() Empty constructor for subclassing.
	CmsMessages(String baseName, Locale locale) Constructor for the messages with an initialized java.util.Locale.
	CmsMessages(String baseName, String language) Constructor for the messages with a language string.
	CmsMessages(String baseName, String language, String country) Constructor for the messages with language and country code strings.
	CmsMessages(String baseName, String language, String country, String variant) Constructor for the messages with language, country code and variant strings.

Method Summary

static String	formatUnknownKey(String keyName) Formats an unknown key.
ResourceBundle	getBundle() Returns the resource bundle this message object was initialized with.
String	getDate(Date date) Returns a formated date String from a Date value, the format being DateFormat.SHORT and the locale based on this instance.
String	getDate(Date date, int format) Returns a formated date String from a Date value, the formatting based on the provided option and the locale based on this instance.
String	getDate(long time) Returns a formated date String from a timestamp value, the format being DateFormat.SHORT and the locale based on this instance.
String	getDateTime(Date date) Returns a formated date and time String from a Date value, the format being DateFormat.SHORT and the locale based on this instance.
String	getDateTime(Date date, int format) 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.
String	getDateTime(long time) Returns a formated date and time String from a timestamp value, the format being DateFormat.SHORT and the locale based on this instance.
Locale	getLocale() Returns the locale to use for looking up this messages.
String	getString(String keyName) Directly calls the getString(String) method of the wrapped ResourceBundle.
boolean	isInitialized() Checks if the bundle was properly initialized.
static boolean	isUnknownKey(String value) Returns true if the provided value matches the scheme "??? " + keyName + " ???", that is the value appears to be an unknown key.
String	key(String keyName) Returns the localized resource string for a given message key.
String	key(String keyName, boolean allowNull) Returns the localized resource string for a given message key.
String	key(String keyName, Object[] params) Returns the localized resource string for a given message key, with the provided replacement parameters.
String	key(String keyName, String defaultValue) Returns the localized resource string for a given message key.
String	keyWithParams(String keyName) Returns the localized resource string for a given message key, treating all values appended with "|" as replacement parameters.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

KEY_SHORT_SUFFIX

public static final String KEY_SHORT_SUFFIX

The suffix of a "short" localized key name.

See Also:

Constant Field Values

UNKNOWN_KEY_EXTENSION

public static final String UNKNOWN_KEY_EXTENSION

Prefix / Suffix for unknown keys.

See Also:

Constant Field Values

m_baseName

protected String m_baseName

The resource bundle base name this object was initialized with.

m_locale

protected Locale m_locale

The locale to use for looking up the messages from the bundle.

m_resourceBundle

protected ResourceBundle m_resourceBundle

The resource bundle this message object was initialized with.

Constructor Detail

CmsMessages

public CmsMessages(String baseName,
                   Locale locale)

Constructor for the messages with an initialized java.util.Locale.

Parameters:

baseName - the base ResourceBundle name

locale - the m_locale to use, eg. "de", "en" etc.

CmsMessages

public CmsMessages(String baseName,
                   String language)

Constructor for the messages with a language string.

The language is a 2 letter language ISO code, e.g. "EN".

The Locale for the messages will be created like this:
new Locale(language, "", "").

Parameters:

baseName - the base ResourceBundle name

language - ISO language indentificator for the m_locale of the bundle

CmsMessages

public CmsMessages(String baseName,
                   String language,
                   String country)

Constructor for the messages with language and country code strings.

The language is a 2 letter language ISO code, e.g. "EN". The country is a 2 letter country ISO code, e.g. "us".

The Locale for the messages will be created like this:
new Locale(language, country, "").

Parameters:

baseName - the base ResourceBundle name

language - ISO language indentificator for the m_locale of the bundle

country - ISO 2 letter country code for the m_locale of the bundle

CmsMessages

public CmsMessages(String baseName,
                   String language,
                   String country,
                   String variant)

Constructor for the messages with language, country code and variant strings.

The language is a 2 letter language ISO code, e.g. "EN". The country is a 2 letter country ISO code, e.g. "us". The variant is a vendor or browser-specific code, e.g. "POSIX".

The Locale for the messages will be created like this:
new Locale(language, country, variant).

Parameters:

baseName - the base ResourceBundle name

language - language indentificator for the m_locale of the bundle

country - 2 letter country code for the m_locale of the bundle

variant - a vendor or browser-specific variant code

CmsMessages

protected CmsMessages()

Empty constructor for subclassing.

Method Detail

formatUnknownKey

public static String formatUnknownKey(String keyName)

Formats an unknown key.

Parameters:

keyName - the key to format

Returns:

the formatted unknown key

See Also:

isUnknownKey(String)

isUnknownKey

public static boolean isUnknownKey(String value)

Returns true if the provided value matches the scheme "??? " + keyName + " ???", that is the value appears to be an unknown key.

Also returns true if the given value is null.

Parameters:

value - the value to check

Returns:

true if the value is matches the scheme for unknown keys

See Also:

formatUnknownKey(String)

getBundle

public ResourceBundle getBundle()

Returns the resource bundle this message object was initialized with.

Returns:

the resource bundle this message object was initialized with or null if initialization was not successful

getDate

public String getDate(Date date)

Returns a formated date String from a Date value, the format being DateFormat.SHORT and the locale based on this instance.

Parameters:

date - the Date object to format as String

Returns:

the formatted date

getDate

public String getDate(Date date,
                      int format)

Returns a formated date String from a Date value, the formatting based on the provided option and the locale based on this instance.

Parameters:

date - the Date object to format as String

format - the format to use, see CmsMessages for possible values

Returns:

the formatted date

getDate

public String getDate(long time)

Returns a formated date String from a timestamp value, the format being DateFormat.SHORT and the locale based on this instance.

Parameters:

time - the time value to format as date

Returns:

the formatted date

getDateTime

public String getDateTime(Date date)

Returns a formated date and time String from a Date value, the format being DateFormat.SHORT and the locale based on this instance.

Parameters:

date - the Date object to format as String

Returns:

the formatted date and time

getDateTime

public String getDateTime(Date date,
                          int format)

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.

Parameters:

date - the Date object to format as String

format - the format to use, see CmsMessages for possible values

Returns:

the formatted date and time

getDateTime

public String getDateTime(long time)

Returns a formated date and time String from a timestamp value, the format being DateFormat.SHORT and the locale based on this instance.

Parameters:

time - the time value to format as date

Returns:

the formatted date and time

getLocale

public Locale getLocale()

Returns the locale to use for looking up this messages.

Returns:

the locale to use for looking up this messages

getString

public String getString(String keyName)
                 throws CmsMessageException

Directly calls the getString(String) method of the wrapped ResourceBundle.

If you use this this class on a template, you should consider using the key(String) method to get the value from the ResourceBundle because it handles the exception for you in a convenient way.

Parameters:

keyName - the key

Returns:

the resource string for the given key

Throws:

CmsMessageException - in case the key is not found or the bundle is not initialized

isInitialized

public boolean isInitialized()

Checks if the bundle was properly initialized.

Returns:

true if bundle was initialized, false otherwise

key

public String key(String keyName)

Returns the localized resource string for a given message key.

If the key was not found in the bundle, the return value is "??? " + keyName + " ???". This will also be returned if the bundle was not properly initialized first.

Parameters:

keyName - the key for the desired string

Returns:

the resource string for the given key

key

public String key(String keyName,
                  boolean allowNull)

Returns the localized resource string for a given message key.

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 "??? " + keyName + " ???". 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.

Parameters:

keyName - the key for the desired string

allowNull - if true, 'null' is an allowed return value

Returns:

the resource string for the given key

key

public String key(String keyName,
                  Object[] params)

Returns the localized resource string for a given message key, with the provided replacement parameters.

If the key was found in the bundle, it will be formatted using a MessageFormat using the provided parameters.

If the key was not found in the bundle, the return value is "??? " + keyName + " ???". This will also be returned if the bundle was not properly initialized first.

Parameters:

keyName - the key for the desired string

params - the parameters to use for formatting

Returns:

the resource string for the given key

key

public String key(String keyName,
                  String defaultValue)

Returns the localized resource string for a given message key.

If the key was not found in the bundle, the provided default value is returned.

Parameters:

keyName - the key for the desired string

defaultValue - the default value in case the key does not exist in the bundle

Returns:

the resource string for the given key it it exists, or the given default if not

keyWithParams

public String keyWithParams(String keyName)

Returns the localized resource string for a given message key, treating all values appended with "|" as replacement parameters.

If the key was found in the bundle, it will be formatted using a MessageFormat using the provided parameters. The parameters have to be appended to the key separated by a "|". For example, the keyName error.message|First|Second would use the key error.message with the parameters First and Second. This would be the same as calling key(String, Object[]).

If no parameters are appended with "|", this is the same as calling key(String).

If the key was not found in the bundle, the return value is "??? " + keyName + " ???". This will also be returned if the bundle was not properly initialized first.

Parameters:

keyName - the key for the desired string, optinally containing parameters appended with a "|"

Returns:

the resource string for the given key

See Also:

key(String, Object[]), key(String)

toString

public String toString()

Overrides:

toString in class Object

See Also:

Object.toString()