| <!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/ui/SystemBasePlugin.html">org.eclipse.rse.ui.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/ui/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/ui/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/ui/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/ui/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.ui.*; // <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> |
