RSE Message API

To work with messages, which are defined in an xml message file, you use:

Methods for Parsing the Message File

Once you have defined your message file, you must update your plugin class to load it at startup time. To do this, simply call the static method loadMessageFile in the RSE-supplied SystemBasePlugin class.

After the message file is loaded into memory, you can extract messages from it by calling the static method getMessage from the same SystemBasePlugin class.

Classes for Displaying Messages

The following classes are all defined in the org.eclipse.rse.ui.messages package.

The SystemMessageFile Class

The loadMessageFile method in SystemBasePlugin, returns an instance of SystemMessageFile, representing the parsed message file. It is methods in this which return individual messages.

The SystemMessage Class

The getMessage method in SystemBasePlugin returns an instance of SystemMessage, representing an individual message from the message file.

To do message variable substitution, call the appropriate overload of the makeSubstitution method in the message object, passing as many parameters as there are unique substitution variables in the message.

To get the first level message text, call getLevelOneText on the message object. To get the second level help, call getLevelTwoText.

The SystemMessageDialog Class

To display a message in a dialog, instantiate SystemMessageDialog, passing in a parent shell and the message object, and then call the appropriate open method in the dialog object. Here is what the message dialog looks like, for a message of type Error (the type dictates the error icon):

The ISystemMessageLine Interface

If you are extending the RSE class SystemPromptDialog for dialogs, or AbstractSystemWizardPage for wizard pages or SystemBasePropertyPage for property pages, you can display the message to the user by calling the setErrorMessage method all these classes support. These classes all implement the interface ISystemMessageLine, which also includes the method clearErrorMessage. For non-error messages, use setMessage and clearMessage.

Here is what a system message issued in a SystemPromptDialog dialog looks like:

The user can select the question mark icon on the right to see the full message dialog, and hence access the second level help for the message.

Here is what a system message issued in an AbstractSystemWizardPage looks like:

If the user clicks the mouse on the message or icon, they will see the full message dialog for the message.

Here is what a system message issued in a SystemBasePropertyPage looks like:

Again, if the user clicks the mouse on the message or icon, they will see the full message dialog for the message.

Classes for Displaying Message Exceptions

The following class is defined in the org.eclipse.rse.services.clientserver.messages package.

The SystemMessageDialog Class

Many of the RSE APIs throw org.eclipse.rse.services.clientserver.messages.SystemMessageException, which encapsulates a system message object. To get the encapsulated message, call getSystemMessage(). To display the message in an RSE message dialog box, simply call displayMessage() on the exception object. To get the first-level text, call getMessage(), or getSystemMessage().getLevelOneText()

Message Example

Declaring the Messages

Declare the messages via the Message tag in a message file, such as sampleMessages.xml 

<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE MessageFile SYSTEM "../org.eclipse.rse.ui/messageFile.dtd">
<!-- This is an exammple of a message file used by SystemMessage and SystemMessageDialog -->
<MessageFile Version="1.0">
     <Component Name="Samples Plugin" Abbr="SPP">
          <Subcomponent Name="Dialogs" Abbr="D">
                <!-- Component 'D' for dialog sample messages -->
                <MessageList>
                    <Message ID="1003" Indicator="E">
                          <LevelOne>%1 is not a valid year</LevelOne>		
                          <LevelTwo>The birth year specified is not within the valid range of %2 to %3.</LevelTwo>
                    </Message>
                    <!-- repeat Message elements as needed -->
                </MessageList>
          </Subcomponent>
     </Component>
</MessageFile>

Processing the Message File

In your plugin class, declare a message file static variable, load the message file in the constructor, and supply a static method for retrieving a message from the file. 
import org.eclipse.rse.ui.messages.*; // for message file classes
import org.eclipse.rse.ui.*; // for SystemBasePlugin
...
private static SystemMessageFile messageFile = null;
...
messageFile = SystemBasePlugin.loadMessageFile(descriptor, "sampleMessages.xml"); // in constructor
...

/**
 * Retrieve a message from this plugin's message file
 * @param msgId - the ID of the message to retrieve. This is the concatenation of the
 *   message's component abbreviation, subcomponent abbreviation, and message ID as declared
 *   in the message xml file.
 */
public static SystemMessage getPluginMessage(String msgId)
{
    return SystemBasePlugin.getMessage(messageFile, msgId);
}

Retrieving the Message

SystemMessage errorMessage = SamplesPlugin.getPluginMessage("SPPD1003");
errorMessage.makeSubstitution(input, "1900", "2003");

Displaying the Message

On a Message Line

setErrorMessage(errorMessage);

In a Message Dialog

SystemMessageDialog msgDlg = new SystemMessageDialog(shell, errorMessage);
msgDlg.open(); // to open with details not showing
//msgDlg.openWithDetails(); // to open with details already showing