Class CmsMessages

  • Direct Known Subclasses:
    CmsMultiMessages, CmsXmlMessages

    public class CmsMessages
    extends java.lang.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
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String KEY_SHORT_SUFFIX
      The suffix of a "short" localized key name.
      static java.lang.String UNKNOWN_KEY_EXTENSION
      Prefix / Suffix for unknown keys.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected CmsMessages()
      Empty constructor for subclassing.
        CmsMessages​(java.lang.String bundleName, java.lang.String language)
      Constructor for the messages with a language string.
        CmsMessages​(java.lang.String bundleName, java.lang.String language, java.lang.String country)
      Constructor for the messages with language and country code strings.
        CmsMessages​(java.lang.String bundleName, java.lang.String language, java.lang.String country, java.lang.String variant)
      Constructor for the messages with language, country code and variant strings.
        CmsMessages​(java.lang.String bundleName, java.util.Locale locale)
      Constructor for the messages with an initialized java.util.Locale.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean equals​(java.lang.Object obj)  
      static java.lang.String formatUnknownKey​(java.lang.String keyName)
      Formats an unknown key.
      protected java.lang.String getBundleName()
      Returns the name of the resource bundle this object was initialized with.
      java.lang.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.
      java.lang.String getDate​(java.util.Date date)
      Returns a formated date String from a Date value, the format being DateFormat.SHORT and the locale based on this instance.
      java.lang.String getDate​(java.util.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.
      java.lang.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.
      java.lang.String getDateTime​(java.util.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.
      java.lang.String getDateTime​(java.util.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.
      java.util.Locale getLocale()
      Returns the locale to use for looking up this messages.
      java.util.ResourceBundle getResourceBundle()
      Returns the resource bundle this message object was initialized with.
      java.lang.String getString​(java.lang.String keyName)
      Directly calls the getString(String) method of the wrapped ResourceBundle.
      int hashCode()  
      boolean isInitialized()
      Checks if the bundle was properly initialized.
      boolean isUncacheable()
      Indicates that users of this CmsMessages instance should not cache message from it.
      static boolean isUnknownKey​(java.lang.String value)
      Returns true if the provided value matches the scheme "??? " + keyName + " ???", that is the value appears to be an unknown key.
      java.lang.String key​(java.lang.String keyName)
      Returns the localized resource string for a given message key.
      java.lang.String key​(java.lang.String keyName, boolean allowNull)
      Returns the localized resource string for a given message key.
      java.lang.String key​(java.lang.String key, java.lang.Object arg0)
      Returns the selected localized message for the initialized resource bundle and locale.
      java.lang.String key​(java.lang.String key, java.lang.Object[] args)
      Returns the selected localized message for the initialized resource bundle and locale.
      java.lang.String key​(java.lang.String key, java.lang.Object[] args, java.util.function.Function<java.lang.String,​java.lang.String> unknownKeyFormatter)
      Returns the selected localized message for the initialized resource bundle and locale.
      java.lang.String key​(java.lang.String key, java.lang.Object arg0, java.lang.Object arg1)
      Returns the selected localized message for the initialized resource bundle and locale.
      java.lang.String key​(java.lang.String key, java.lang.Object arg0, java.lang.Object arg1, java.lang.Object arg2)
      Returns the selected localized message for the initialized resource bundle and locale.
      java.lang.String keyDefault​(java.lang.String keyName, java.lang.String defaultValue)
      Returns the localized resource string for a given message key.
      java.lang.String keyWithParams​(java.lang.String keyName)
      Returns the localized resource string for a given message key, treating all values appended with "|" as replacement parameters.
      java.lang.String keyWithParams​(java.lang.String keyName, java.util.function.Function<java.lang.String,​java.lang.String> unknownKeyFormatter)
      Returns the localized resource string for a given message key, treating all values appended with "|" as replacement parameters.
      protected void setBundleName​(java.lang.String bundleName)
      Sets the bundleName.
      protected void setLocale​(java.util.Locale locale)
      Sets the locale.
      protected void setResourceBundle​(java.util.ResourceBundle resourceBundle)
      Sets the resource bundle.
      java.lang.String toString()  
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • CmsMessages

        public CmsMessages​(java.lang.String bundleName,
                           java.util.Locale locale)
        Constructor for the messages with an initialized java.util.Locale.
        Parameters:
        bundleName - the base ResourceBundle name
        locale - the m_locale to use, eg. "de", "en" etc.
      • CmsMessages

        public CmsMessages​(java.lang.String bundleName,
                           java.lang.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:
        bundleName - the base ResourceBundle name
        language - ISO language indentificator for the m_locale of the bundle
      • CmsMessages

        public CmsMessages​(java.lang.String bundleName,
                           java.lang.String language,
                           java.lang.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:
        bundleName - 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​(java.lang.String bundleName,
                           java.lang.String language,
                           java.lang.String country,
                           java.lang.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:
        bundleName - 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 java.lang.String formatUnknownKey​(java.lang.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​(java.lang.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)
      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object
        See Also:
        Object.equals(java.lang.Object)
      • getDate

        public java.lang.String getDate​(java.util.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 java.lang.String getDate​(java.util.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 java.lang.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 java.lang.String getDateTime​(java.util.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 java.lang.String getDateTime​(java.util.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 java.lang.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 java.util.Locale getLocale()
        Returns the locale to use for looking up this messages.

        Returns:
        the locale to use for looking up this messages
      • getResourceBundle

        public java.util.ResourceBundle getResourceBundle()
        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
      • getString

        public java.lang.String getString​(java.lang.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
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
        See Also:
        Object.hashCode()
      • isInitialized

        public boolean isInitialized()
        Checks if the bundle was properly initialized.
        Returns:
        true if bundle was initialized, false otherwise
      • isUncacheable

        public boolean isUncacheable()
        Indicates that users of this CmsMessages instance should not cache message from it.

        Returns:
        true if messages from this CmsMessages instance should not be cached
      • key

        public java.lang.String key​(java.lang.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 java.lang.String key​(java.lang.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 java.lang.String key​(java.lang.String key,
                                    java.lang.Object arg0)
        Returns the selected localized message for the initialized resource bundle and locale.

        Convenience method for messages with one argument.

        Parameters:
        key - the message key
        arg0 - the message argument
        Returns:
        the selected localized message for the initialized resource bundle and locale
      • key

        public java.lang.String key​(java.lang.String key,
                                    java.lang.Object arg0,
                                    java.lang.Object arg1)
        Returns the selected localized message for the initialized resource bundle and locale.

        Convenience method for messages with two arguments.

        Parameters:
        key - the message key
        arg0 - the first message argument
        arg1 - the second message argument
        Returns:
        the selected localized message for the initialized resource bundle and locale
      • key

        public java.lang.String key​(java.lang.String key,
                                    java.lang.Object arg0,
                                    java.lang.Object arg1,
                                    java.lang.Object arg2)
        Returns the selected localized message for the initialized resource bundle and locale.

        Convenience method for messages with three arguments.

        Parameters:
        key - the message key
        arg0 - the first message argument
        arg1 - the second message argument
        arg2 - the third message argument
        Returns:
        the selected localized message for the initialized resource bundle and locale
      • key

        public java.lang.String key​(java.lang.String key,
                                    java.lang.Object[] args)
        Returns the selected localized message for the initialized resource bundle and locale.

        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:
        key - the message key
        args - the message arguments
        Returns:
        the selected localized message for the initialized resource bundle and locale
      • key

        public java.lang.String key​(java.lang.String key,
                                    java.lang.Object[] args,
                                    java.util.function.Function<java.lang.String,​java.lang.String> unknownKeyFormatter)
        Returns the selected localized message for the initialized resource bundle and locale.

        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 will be the result of passing the key to the unknownKeyFormatter function.

        Parameters:
        key - the message key
        args - the message arguments
        unknownKeyFormatter - the function for formatting unknown keys
        Returns:
        the selected localized message for the initialized resource bundle and locale
      • keyDefault

        public java.lang.String keyDefault​(java.lang.String keyName,
                                           java.lang.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 java.lang.String keyWithParams​(java.lang.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)
      • keyWithParams

        public java.lang.String keyWithParams​(java.lang.String keyName,
                                              java.util.function.Function<java.lang.String,​java.lang.String> unknownKeyFormatter)
        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 function from the unknownKeyFormatter parameter is used to generate the return value.

        Parameters:
        keyName - the key for the desired string, optinally containing parameters appended with a "|"
        unknownKeyFormatter - the function to use to generate the returned result for unknown keys
        Returns:
        the resource string for the given key
        See Also:
        key(String, Object[]), key(String)
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
        See Also:
        Object.toString()
      • getBundleName

        protected java.lang.String getBundleName()
        Returns the name of the resource bundle this object was initialized with.

        Returns:
        the name of the resource bundle this object was initialized with
      • setBundleName

        protected void setBundleName​(java.lang.String bundleName)
        Sets the bundleName.

        Parameters:
        bundleName - the bundleName to set
      • setLocale

        protected void setLocale​(java.util.Locale locale)
        Sets the locale.

        Parameters:
        locale - the locale to set
      • setResourceBundle

        protected void setResourceBundle​(java.util.ResourceBundle resourceBundle)
        Sets the resource bundle.

        Parameters:
        resourceBundle - the resource bundle to set