com.ibm.ras
Class RASMessageCatalog

java.lang.Object
  |
  +--com.ibm.ras.RASMessageCatalog
public class RASMessageCatalog
extends java.lang.Object

RASMessageCatalog formats messages within the RAS system according to the current locale (that is, in the desired language). The text associated with any RAS message is kept in a java.util.ResourceBundle. Each message text is associated with a "key," which is, essentially, a name for the message text. RASMessageCatalog formats the message text using a java.text.MessageFormat object. One way to define the messages is through a PropertyResourceBundle file, backed up by a Properties file. Here is a sample: 

 # {0} is the name of a file.                                            
 # {1} is the detailed message created when the file creation error      
 #     occurred                                                          
                                                                          
 ERR_FILE_WRITER=Unable to create a FileWriter for {0}:  {1}
                                                                          
 # {0} is a text string naming the missing message key.                  
                                                                          
 ERR_MISSING_KEY=Message key {0} was not found in any searched catalog.
                                                                          
 ERR_SOCKET=Unable to connect to the RAS Log Server.
To create a message catalog, pass it the base name of the resource bundle. For example, if your base file was com.ibm.ras.RASMsgs.properties you would code: 
 RASMessageCatalog msgCat = new RASMessageCatalog("com.ibm.ras.RASMsgs");
Use the RASMessageCatalog.getMessage methods to retrieve the message text in the desired locale. Java will look for the proper translation of this file according to the supplied or default locale. For example, it might first search for RASMsgs_en_GB.properties, then RASMsgs_en.properties and, finally RASMsgs.properties.

RASMessageCatalog provides a debug mode, which makes it easy to determine if messages are retrieved from locale-specific resource bundles. When debug mode is enabled through setDebug, messages returned from a RASMessageCatalog are enclosed in square brackets ("[ ]").

By default, debug mode is disabled. In addition to setDebug, the debug mode may be altered by creating a file, RASMessageCatalog/catalog.properties and placing it in the root of any directory in your Java CLASSPATH. For applets, it may also be placed in a JAR or CAB file. To enable debug mode, this properties file must contain the property debug=true. The property debug=false will disable debug mode.

When used as part of the RAS Toolkit, it is not necessary for an application to create a RASMessageCatalog. If national language support is required elsewhere, RASMessageCatalog provides many useful features.

Constructor Summary
RASMessageCatalog(java.util.ResourceBundle bundle)
          Creates a RASMessageCatalog.
RASMessageCatalog(java.util.ResourceBundle bundle, java.util.Locale loc)
          Creates a RASMessageCatalog.
RASMessageCatalog(java.lang.String baseName)
          Creates a RASMessageCatalog using the default locale.
RASMessageCatalog(java.lang.String baseName, java.util.Locale loc)
          Creates a RASMessageCatalog.
 
Method Summary
 char getChar(java.lang.String key)
          Gets the first character of a message.
 java.util.Locale getLocale()
          Gets the locale used by the RASMessageCatalog.
 java.lang.String getMessage(java.lang.String key)
          Gets a message with no inserts from the catalog.
 java.lang.String getMessage(java.lang.String key, java.lang.Object insert1)
          Gets a message with one insert from the catalog.
 java.lang.String getMessage(java.lang.String key, java.lang.Object[] inserts)
          Gets a message with an array of inserts from the catalog.
 java.lang.String getMessage(java.lang.String key, java.lang.Object insert1, java.lang.Object insert2)
          Gets a message with two inserts from the catalog.
 java.lang.String getMsg(java.lang.String key, java.lang.Object[] inserts)
          Gets a message with an array of inserts from the catalog.
 boolean isDebug()
          Determines if the RASMessageCatalog is in debug mode.
 void setDebug(boolean flag)
          Sets the RASMessageCatalog debug mode.
 void setLocale(java.util.Locale loc)
          Sets the locale to be used by the RASMessageCatalog.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

RASMessageCatalog

public RASMessageCatalog(java.lang.String baseName)
                  throws java.util.MissingResourceException
Creates a RASMessageCatalog using the default locale.

Parameters:
baseName - The base name of the ResourceBundle which contains the messages.
Throws:
java.util.MissingResourceException - This exception is thrown if the ResourceBundle cannot be loaded.

RASMessageCatalog

public RASMessageCatalog(java.lang.String baseName,
                         java.util.Locale loc)
                  throws java.util.MissingResourceException
Creates a RASMessageCatalog.

Parameters:
baseName - The base name of the ResourceBundle which contains the messages.
loc - The locale with which the messages should be displayed.
Throws:
java.util.MissingResourceException - This exception is thrown if the ResourceBundle cannot be loaded.

RASMessageCatalog

public RASMessageCatalog(java.util.ResourceBundle bundle)
Creates a RASMessageCatalog.

Parameters:
bundle - The ResourceBundle which contains the messages.

RASMessageCatalog

public RASMessageCatalog(java.util.ResourceBundle bundle,
                         java.util.Locale loc)
Creates a RASMessageCatalog.

Note: Use of this constructor may cause unexpected behavior if the locale of the ResourceBundle is not the same as the locale parameter.

Parameters:
bundle - The ResourceBundle which contains the messages.
loc - The locale with which the messages should be displayed.
Method Detail

getLocale

public java.util.Locale getLocale()
Gets the locale used by the RASMessageCatalog.

Returns:
The message catalog locale. If a locale has not been set, the default Locale.getDefault is returned.

setLocale

public void setLocale(java.util.Locale loc)
Sets the locale to be used by the RASMessageCatalog.

Note: Use of this method may cause unexpected behavior if the RASMessageCatalog was created with one of the constructors that takes a ResourceBundle as a parameter. In this case, the RASMessageCatalog cannot recreate the ResourceBundle in the new locale.

Parameters:
loc - The new locale. If this locale is null, the current locale is not changed.

isDebug

public boolean isDebug()
Determines if the RASMessageCatalog is in debug mode. In debug mode, messages retrieved via getMessage or getMsg are enclosed in brackets, "[This is a test]," for example. This makes it easy to identify those messages which do not come from locale-specific message bundles.

By default, debug mode is disabled.

Returns:
true if debug mode is enabled, or false otherwise.

setDebug

public void setDebug(boolean flag)
Sets the RASMessageCatalog debug mode. In debug mode, messages retrieved via getMessage or getMsg are enclosed in brackets, "[This is a test]," for example. This makes it easy to identify those messages which do not come from locale-specific message bundles.

By default, debug mode is disabled.

Parameters:
flag - true to enable debug mode, or false otherwise.

getMessage

public java.lang.String getMessage(java.lang.String key)
                            throws java.util.MissingResourceException
Gets a message with no inserts from the catalog.

Parameters:
key - The key name of this message.
Returns:
The formatted message from the catalog.
Throws:
java.util.MissingResourceException - This exception is thrown if a message with the given key cannot be found in the message catalog.

getMessage

public java.lang.String getMessage(java.lang.String key,
                                   java.lang.Object insert1)
                            throws java.util.MissingResourceException
Gets a message with one insert from the catalog.

Parameters:
key - The key name of this message.
insert1 - An element to be inserted into the message.
Returns:
The formatted message from the catalog.
Throws:
java.util.MissingResourceException - This exception is thrown if a message with the given key cannot be found in the message catalog.

getMessage

public java.lang.String getMessage(java.lang.String key,
                                   java.lang.Object insert1,
                                   java.lang.Object insert2)
                            throws java.util.MissingResourceException
Gets a message with two inserts from the catalog.

Parameters:
key - The key name of this message.
insert1 - An element to be inserted into the message.
insert2 - An element to be inserted into the message.
Returns:
The formatted message from the catalog.
Throws:
java.util.MissingResourceException - This exception is thrown if a message with the given key cannot be found in the message catalog.

getMessage

public java.lang.String getMessage(java.lang.String key,
                                   java.lang.Object[] inserts)
                            throws java.util.MissingResourceException
Gets a message with an array of inserts from the catalog.

Parameters:
key - The key name of this message.
inserts - An array of elements to be inserted into the message.
Returns:
The formatted message from the catalog.
Throws:
java.util.MissingResourceException - This exception is thrown if a message with the given key cannot be found in the message catalog.

getMsg

public java.lang.String getMsg(java.lang.String key,
                               java.lang.Object[] inserts)
Gets a message with an array of inserts from the catalog. This convenience method returns an error message if the requested key was not found in this catalog. No exception is thrown.

Parameters:
key - The key name of this message.
inserts - An array of elements to be inserted into the message.
Returns:
The formatted message from the catalog.

getChar

public char getChar(java.lang.String key)
Gets the first character of a message. This method is used to retrieve a character to be used as a mnemonic in a Swing user interface. (This is the underlined character which activates a button, for example, when you press Alt-character.)

Typically, one would define two strings in a message file. For example: 

 CANCEL=Cancel
 CANCEL_MNEMONIC=a
The first string is the label to go on a button. The second is the mnemonic character. The method getMessage("CANCEL") will return the button label, while getChar("CANCEL_MNEMONIC") will return the mnemonic character.

Parameters:
key - The key name of the message.
Returns:
The mnemonic character.
Throws:
java.util.MissingResourceException - This exception is thrown if a message with the given key cannot be found in the message catalog.

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.