cdt/rse/doc/org.eclipse.rse.doc.isv/guide/api/messages/uiMessageAPI.html

<!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>&lt;?xml version=&quot;1.0&quot; encoding='UTF-8'?&gt;
&lt;!DOCTYPE MessageFile SYSTEM &quot;../org.eclipse.rse.ui/messageFile.dtd&quot;&gt;
&lt;!-- This is an exammple of a message file used by SystemMessage and SystemMessageDialog --&gt;
&lt;MessageFile Version=&quot;1.0&quot;&gt;
     &lt;Component Name=&quot;Samples Plugin&quot; Abbr=&quot;<B>SPP</B>&quot;&gt;
          &lt;Subcomponent Name=&quot;Dialogs&quot; Abbr=&quot;<B>D</B>&quot;&gt;
                &lt;!-- Component 'D' for dialog sample messages --&gt;
                &lt;MessageList&gt;
                    &lt;Message ID=&quot;<B>1003</B>&quot; Indicator=&quot;E&quot;&gt;
                          &lt;LevelOne&gt;%1 is not a valid year&lt;/LevelOne&gt;		
                          &lt;LevelTwo&gt;The birth year specified is not within the valid range of %2 to %3.&lt;/LevelTwo&gt;
                    &lt;/Message&gt;
                    &lt;!-- <I>repeat Message elements as needed</I> --&gt;
                &lt;/MessageList&gt;
          &lt;/Subcomponent&gt;
     &lt;/Component&gt;
&lt;/MessageFile&gt;
</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, &quot;sampleMessages.xml&quot;); // <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, &quot;1900&quot;, &quot;2003&quot;);</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>
Bug 149331: Update with latest documentation 2006-07-19 10:36:13 +00:00			`<!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`
Fix links into ../reference/api/org/eclipse/.. 2006-07-20 13:15:28 +00:00			`<samp><A href="../../../reference/api/org/eclipse/rse/core/SystemBasePlugin.html"org.eclipse.rse.core.SystemBasePlugin</A></samp>`
Bug 149331: Update with latest documentation 2006-07-19 10:36:13 +00:00			`class to load the message file and extract messages from it.`
			`<li>Classes in the`
Fix links into ../reference/api/org/eclipse/.. 2006-07-20 13:15:28 +00:00			`<samp><A href="../../../reference/api/org/eclipse/rse/ui/messages/package-summary.html">org.eclipse.rse.ui.messages</A></samp>`
Bug 149331: Update with latest documentation 2006-07-19 10:36:13 +00:00			`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`
Fix links into ../reference/api/org/eclipse/.. 2006-07-20 13:15:28 +00:00			`<samp><A href="../../../reference/api/org/eclipse/rse/core/SystemBasePlugin.html#loadMessageFile(org.eclipse.core.runtime.IPluginDescriptor, java.lang.String)">loadMessageFile</a></samp>`
Bug 149331: Update with latest documentation 2006-07-19 10:36:13 +00:00			`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`
Fix links into ../reference/api/org/eclipse/.. 2006-07-20 13:15:28 +00:00			`<samp><A href="../../../reference/api/org/eclipse/rse/core/SystemBasePlugin.html#getMessage(org.eclipse.rse.ui.messages.SystemMessageFile, java.lang.String)">getMessage</a></samp>`
Bug 149331: Update with latest documentation 2006-07-19 10:36:13 +00:00			`from the same <samp><a href="../plugin/uiPluginAPI.html">SystemBasePlugin</a></samp> class.`
			`</p>`

			`<h2>Classes for Displaying Messages</h2>`
Fix links into ../reference/api/org/eclipse/.. 2006-07-20 13:15:28 +00:00			`<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>`
Bug 149331: Update with latest documentation 2006-07-19 10:36:13 +00:00
			`<h3><A name="SystemMessageFile"></A>The <samp>SystemMessageFile</samp> Class</h3>`
Fix links into ../reference/api/org/eclipse/.. 2006-07-20 13:15:28 +00:00			`<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`
bug 149339 - updating some documentation to remove etools references and fix other dead links. 2006-08-02 02:35:23 +00:00			`<samp><A href="../../../reference/api/org/eclipse/rse/services/clientserver/messages/SystemMessageFile.html">SystemMessageFile</a></samp>,`
Bug 149331: Update with latest documentation 2006-07-19 10:36:13 +00:00			`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>`
Fix links into ../reference/api/org/eclipse/.. 2006-07-20 13:15:28 +00:00			`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`
bug 149339 - updating some documentation to remove etools references and fix other dead links. 2006-08-02 02:35:23 +00:00			`<samp><A href="../../../reference/api/org/eclipse/rse/services/clientserver/messages/SystemMessage.html">SystemMessage</a></samp>,`
Bug 149331: Update with latest documentation 2006-07-19 10:36:13 +00:00			`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`
bug 149339 - updating some documentation to remove etools references and fix other dead links. 2006-08-02 02:35:23 +00:00			`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.`
Bug 149331: Update with latest documentation 2006-07-19 10:36:13 +00:00			`</p>`
bug 149339 - updating some documentation to remove etools references and fix other dead links. 2006-08-02 02:35:23 +00:00			`<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>.`
Bug 149331: Update with latest documentation 2006-07-19 10:36:13 +00:00			`</p>`

			`<h3><A name="SystemMessageDialog"></A>The <samp>SystemMessageDialog</samp> Class</h3>`
Fix links into ../reference/api/org/eclipse/.. 2006-07-20 13:15:28 +00:00			`<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`
Bug 149331: Update with latest documentation 2006-07-19 10:36:13 +00:00			`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>`
Fix links into ../reference/api/org/eclipse/.. 2006-07-20 13:15:28 +00:00			`<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>`
Bug 149331: Update with latest documentation 2006-07-19 10:36:13 +00:00			`<p>`
Fix links into ../reference/api/org/eclipse/.. 2006-07-20 13:15:28 +00:00			`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>`
Bug 149331: Update with latest documentation 2006-07-19 10:36:13 +00:00			`<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.`
Fix links into ../reference/api/org/eclipse/.. 2006-07-20 13:15:28 +00:00			`<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>`
Bug 149331: Update with latest documentation 2006-07-19 10:36:13 +00:00			`<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>`

Fix links into ../reference/api/org/eclipse/.. 2006-07-20 13:15:28 +00:00			`<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>`
Bug 149331: Update with latest documentation 2006-07-19 10:36:13 +00:00			`<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>`
Fix links into ../reference/api/org/eclipse/.. 2006-07-20 13:15:28 +00:00			`<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.`
Bug 149331: Update with latest documentation 2006-07-19 10:36:13 +00:00
			`<h3>The <samp>SystemMessageDialog</samp> Class</h3>`
Fix links into ../reference/api/org/eclipse/.. 2006-07-20 13:15:28 +00:00			`<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.`
Bug 149331: Update with latest documentation 2006-07-19 10:36:13 +00:00			`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>`