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
