<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<meta name="copyright" content="Copyright (c) IBM Corporation and others 2002, 2006. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
<LINK REL="STYLESHEET" HREF="../../../book.css" TYPE="text/css">
<title>RSE Message API</title>
</head>
<body bgcolor="#ffffff">
<h1>RSE Message API</h1>
<p>To work with messages, which are defined in an xml <a href="uiMessageFile.html">message file</a>,
you use:
</p>
<ul>
<li>Static methods in the
<samp><A href="../../../reference/api/org/eclipse/rse/core/SystemBasePlugin.html"org.eclipse.rse.core.SystemBasePlugin</A></samp>
class to load the message file and extract messages from it.
<li>Classes in the
<samp><A href="../../../reference/api/org/eclipse/rse/ui/messages/package-summary.html">org.eclipse.rse.ui.messages</A></samp>
package to do variable substitution, and display the messages to the user.
</ul>
<h2>Methods for Parsing the Message File</h2>
<p>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
<samp><A href="../../../reference/api/org/eclipse/rse/core/SystemBasePlugin.html#loadMessageFile(org.eclipse.core.runtime.IPluginDescriptor, java.lang.String)">loadMessageFile</a></samp>
in the RSE-supplied <samp><a href="../plugin/uiPluginAPI.html">SystemBasePlugin</a></samp> class.
<BR>
<BR>
After the message file is loaded into memory, you can extract messages from it by calling the static method
<samp><A href="../../../reference/api/org/eclipse/rse/core/SystemBasePlugin.html#getMessage(org.eclipse.rse.ui.messages.SystemMessageFile, java.lang.String)">getMessage</a></samp>
from the same <samp><a href="../plugin/uiPluginAPI.html">SystemBasePlugin</a></samp> class.
</p>
<h2>Classes for Displaying Messages</h2>
<p>The following classes are all defined in the <samp><A href="../../../reference/api/org/eclipse/rse/ui/messages/package-summary.html">org.eclipse.rse.ui.messages</a></samp> package. </p>
<h3><A name="SystemMessageFile"></A>The <samp>SystemMessageFile</samp> Class</h3>
<p>The <samp><A href="../../../reference/api/org/eclipse/rse/core/SystemBasePlugin.html#loadMessageFile(org.eclipse.core.runtime.IPluginDescriptor, java.lang.String)">loadMessageFile</a></samp> method in <samp>SystemBasePlugin</samp>, returns an instance of
<samp><A href="../../../reference/api/org/eclipse/rse/services/clientserver/messages/SystemMessageFile.html">SystemMessageFile</a></samp>,
representing the parsed message file. It is methods in this which return individual messages.
<h3><A name="SystemMessage"></A>The <samp>SystemMessage</samp> Class</h3>
The <samp><A href="../../../reference/api/org/eclipse/rse/core/SystemBasePlugin.html#getMessage(org.eclipse.rse.ui.messages.SystemMessageFile, java.lang.String)">getMessage</a></samp> method in <samp>SystemBasePlugin</samp> returns an instance of
<samp><A href="../../../reference/api/org/eclipse/rse/services/clientserver/messages/SystemMessage.html">SystemMessage</a></samp>,
representing an individual message from the message file.
</p>
<p>To do message <i>variable substitution</i>, call the appropriate overload of the <samp>makeSubstitution</samp> method in
the <A href="../../../reference/api/org/eclipse/rse/services/clientserver/messages/SystemMessage.html">message</A> object, passing as many parameters as there are unique substitution variables in the message.
</p>
<p>To get the first level message text, call <samp><A href="../../../reference/api/org/eclipse/rse/services/clientserver/messages/SystemMessage.html#getLevelOneText()">getLevelOneText</a></samp> on the message object. To get
the second level help, call <samp><A href="../../../reference/api/org/eclipse/rse/services/clientserver/messages/SystemMessage.html#getLevelTwoText()">getLevelTwoText</a></samp>.
</p>
<h3><A name="SystemMessageDialog"></A>The <samp>SystemMessageDialog</samp> Class</h3>
<p>To display a message in a dialog, instantiate <samp><A href="../../../reference/api/org/eclipse/rse/ui/messages/SystemMessageDialog.html">SystemMessageDialog</a></samp>, passing
in a parent shell and the message object, and then call the appropriate <samp><A href="../../../reference/api/org/eclipse/rse/ui/messages/SystemMessageDialog.html#open()">open</a></samp> 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):
</p>
<P><IMG border="0" src="msgDialog.gif" width="457" height="190"></P>
<h3><A name="ISystemMessageLine"></A>The <samp>ISystemMessageLine</samp> Interface</h3>
<p>If you are extending the RSE class <samp><A href="../../../reference/api/org/eclipse/rse/ui/dialogs/SystemPromptDialog.html">SystemPromptDialog</a></samp> for dialogs,
or <samp><A href="../../../reference/api/org/eclipse/rse/ui/wizards/AbstractSystemWizardPage.html">AbstractSystemWizardPage</a></samp> for wizard pages
or <samp><A href="../../../reference/api/org/eclipse/rse/ui/propertypages/SystemBasePropertyPage.html">SystemBasePropertyPage</a></samp> for property pages, you can display the message to the
user by calling the <samp><A href="../../../reference/api/org/eclipse/rse/ui/messages/ISystemMessageLine.html#setErrorMessage(org.eclipse.rse.ui.messages.SystemMessage)">setErrorMessage</a></samp> method all these classes support. These classes all implement
the interface <b><samp><A href="../../../reference/api/org/eclipse/rse/ui/messages/ISystemMessageLine.html">ISystemMessageLine</a></samp></b>, which also includes the method <samp>clearErrorMessage</samp>. For non-error
messages, use <samp><A href="../../../reference/api/org/eclipse/rse/ui/messages/ISystemMessageLine.html#setMessage(org.eclipse.rse.ui.messages.SystemMessage)">setMessage</a></samp>
and <samp><A href="../../../reference/api/org/eclipse/rse/ui/messages/ISystemMessageLine.html#clearMessage()">clearMessage</a></samp>.</p>
<p>
Here is what a system message issued in a <samp><A href="../../../reference/api/org/eclipse/rse/ui/dialogs/SystemPromptDialog.html">SystemPromptDialog</a></samp> dialog looks like:</p>
<P><IMG border="0" src="msgLine_dialog.gif" width="264" height="125"></P>
<p>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.
<p>Here is what a system message issued in an <samp><A href="../../../reference/api/org/eclipse/rse/ui/wizards/AbstractSystemWizardPage.html">AbstractSystemWizardPage</a></samp> looks like:</p>
<P><IMG border="0" src="msgLine_wizard.gif" width="439" height="98"></P>
<p>If the user clicks the mouse on the message or icon, they will see the full message dialog for the message.</p>
<p>Here is what a system message issued in a <samp><A href="../../../reference/api/org/eclipse/rse/ui/propertypages/SystemBasePropertyPage.html">SystemBasePropertyPage</a></samp> looks like:</p>
<P><IMG border="0" src="msgLine_properties.gif" width="491" height="75"></P>
<p>Again, if the user clicks the mouse on the message or icon, they will see the full message dialog for the message.</p>
<h2>Classes for Displaying Message Exceptions</h2>
<p>The following class is defined in the <samp><A href="../../../reference/api/org/eclipse/rse/services/clientserver/messages/package-summary.html">org.eclipse.rse.services.clientserver.messages</a></samp> package.
<h3>The <samp>SystemMessageDialog</samp> Class</h3>
<p>Many of the RSE APIs throw <samp><A href="../../../reference/api/org/eclipse/rse/services/clientserver/messages/SystemMessageException.html">org.eclipse.rse.services.clientserver.messages.SystemMessageException</a></samp>, which
encapsulates a system message object. To get the encapsulated message, call <samp><A href="../../../reference/api/org/eclipse/rse/services/clientserver/messages/SystemMessageException.html#getSystemMessage()">getSystemMessage()</a></samp>.
To display the message in an RSE message dialog box, simply call <samp><A href="../../../reference/api/org/eclipse/rse/services/clientserver/messages/SystemMessageException.html#displayMessage()">displayMessage()</a></samp> on the exception object.
To get the first-level text, call <samp>getMessage()</samp>, or <samp>getSystemMessage().getLevelOneText()</samp>
</p>
<h1>Message Example</h1>
<h2>Declaring the Messages</h2>
<p>Declare the messages via the <samp>Message</samp> tag in a <a href="uiMessageFile.html">message file</a>, such as <samp>sampleMessages.xml</samp>
<pre><?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="<B>SPP</B>">
<Subcomponent Name="Dialogs" Abbr="<B>D</B>">
<!-- Component 'D' for dialog sample messages -->
<MessageList>
<Message ID="<B>1003</B>" 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>
<!-- <I>repeat Message elements as needed</I> -->
</MessageList>
</Subcomponent>
</Component>
</MessageFile>
</pre>
<h2>Processing the Message File</h2>
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.
<pre>import org.eclipse.rse.ui.messages.*; // <I>for message file classes</I>
import org.eclipse.rse.core.*; // <I>for SystemBasePlugin</I>
<B>...</B>
private static SystemMessageFile messageFile = null;
<B>...</B>
messageFile = SystemBasePlugin.loadMessageFile(descriptor, "sampleMessages.xml"); // <I>in constructor</I>
<B>...</B>
/**
* <I>Retrieve a message from this plugin's message file</I>
* <I>@param msgId - the ID of the message to retrieve. This is the concatenation of the</I>
* <I>message's component abbreviation, subcomponent abbreviation, and message ID as declared</I>
* <I>in the message xml file.</I>
*/
<A name="getPluginMessage"></A>public static SystemMessage <B>getPluginMessage</B>(String msgId)
{
return SystemBasePlugin.getMessage(messageFile, msgId);
}</pre>
<h2>Retrieving the Message</h2>
<pre>SystemMessage errorMessage = SamplesPlugin.getPluginMessage("SPPD1003");
errorMessage.makeSubstitution(input, "1900", "2003");</pre>
<h2>Displaying the Message</h2>
<h3>On a Message Line</h3>
<pre>setErrorMessage(errorMessage);</pre>
<P><IMG border="0" src="msgSample_msgline.gif" width="227" height="208"></P>
<h3>In a Message Dialog</h3>
<pre>SystemMessageDialog msgDlg = new SystemMessageDialog(shell, errorMessage);</br>msgDlg.open(); // <I>to open with details not showing</I>
//msgDlg.openWithDetails(); // <I>to open with details already showing</I> </pre>
<P><IMG border="0" src="msgSample_msgDlg.gif" width="457" height="190"></P>
<P><BR>
</P>
</body>
</html>