rich client platform part1.mht

Rich Client Tutorial

               *.jar,\
               part1.jar,\
               plugin.properties
source.part1.jar =3D src/
</PRE>
<P>Finally, you need to create a plugin.properties file (listing 6) for =
any=20
natural language strings at the plug-in registry level (i.e., things the =

run-time has to know about your plug-in before even loading it). You =
could=20
hard-code these into your plug-in manifest but it's best to get into the =
i18n=20
habit from the start. </P>
<P><B>Listing 6. plugin.properties </B></P><PRE>pluginName =3D =
RcpTutorial1 Plug-in
providerName =3D Eclipse.org
perspectiveName =3D RcpTutorial1
</PRE>
<H2>Taking it for a spin</H2>
<P>To test and debug this plug-in, select Run &gt; Debug..., select =
Run-time=20
Workbench, then click New to create a new configuration. In the =
Arguments tab,=20
select <CODE>org.eclipse.ui.tutorials.rcp.part1.RcpApplication</CODE> =
for the=20
name of the application to run. This comes from the id specified on the=20
<CODE>org.eclipse.core.runtime.applications</CODE> extension point (in =
this=20
example, <CODE>RcpApplication</CODE>), prepended with the plug-in id=20
(<CODE>org.eclipse.ui.tutorials.rcp.part1</CODE>). </P>
<P>Now switch over to the Plug-ins tab. Select the option to Choose =
plug-ins and=20
fragments to launch from the list. We want the smallest possible set of =
plug-ins=20
involved in your program so click on Deselect All, scroll down and place =
a=20
checkmark next to your plug-in=20
(<CODE>org.eclipse.ui.tutorials.rcp.part1</CODE>), and click Add =
Required=20
Plug-ins. Then click on Debug and you should see a bare-bones Workbench =
start up=20
(see figure 1). Your window will probably be bigger than this; we'll see =
in part=20
2 of the tutorial how to control that. </P>
<P><B>Figure 1. World's simplest RCP application. </B></P><IMG=20
src=3D"http://eclipse.org/articles/Article-RCP-1/images/spin.png">=20
<P>If you don't see this, you should be able to find an error message in =
the=20
run-time workbench's log file. This file is in different places for =
different=20
releases but as of this writing can be found in=20
<CODE>./configuration/nnnnn.log</CODE> where <I>nnnnn</I> is a long =
random=20
number. Simply bring it up in a text editor and look for the most recent =
errors.=20
You may find it useful to delete the log files before running the =
program so you=20
won't get confused by older messages.</P>
<P><IMG height=3D13 alt=3D"Tip: "=20
src=3D"http://eclipse.org/articles/Article-RCP-1/images/tip.gif" =
width=3D62> Specify=20
the <CODE>-consoleLog</CODE> option in the Arguments tab under Program =
Arguments=20
(in the launch configuration) to have all error messages sent to the =
Console.=20
This is easier than searching around for the log file. </P>
<H2>Running it outside of Eclipse</H2>
<P>The whole point of all this is to be able to run stand-alone =
applications=20
without the user having to know anything about the Java and Eclipse code =
being=20
used under the covers. For a real application you will probably want to =
provide=20
a self-contained executable generated by an install program like =
InstallShield.=20
That's really beyond the scope of this article though, so we'll do =
something=20
simpler.</P>
<P>We need to create a simplified version of the Eclipse install =
directory=20
because the Eclipse plug-in loader expects things to be in a certain =
layout.=20
Here are the steps to get started:</P>
<OL>
  <LI>Right click on the plug-in project and select Export.=20
  <LI>Select Deployable plug-ins and fragments and then press Next.=20
  <LI>Select the plug-in(s) that should be included. For this example =
that would=20
  be org.eclipse.ui.tutorials.rcp.part1.=20
  <LI>Select the option to deploy as a directory structure, and for the=20
  directory enter a name ending with RcpTutorial1 (for example, =
C:\RcpTutorial1=20
  on Windows).=20
  <LI>If you want to provide source code for your application, select =
the=20
  Include source code option.=20
  <LI>Press Finish to export the plug-in. Eclipse will perform a full =
build in=20
  the background and populate the directory for you. </LI></OL>
<P>To complete the RcpTutorial1 directory, copy the startup.jar file =
from the=20
Eclipse install directory into the top level, and copy all the =
org.eclipse=20
plug-ins that are required into the plugins directory. </P>
<P>Which plug-ins are required, you ask? Earlier, when you created a =
launch=20
configuration to debug the RCP application you clicked on the Add =
Required=20
Plug-ins button. Simply open the launch configuration again to see the =
list.=20
Copy all the plug-ins that are checked off there. In addition, you need =
to copy=20
the <CODE>org.eclipse.update.configurator</CODE> plug-in if you want =
automatic=20
discovery of plug-ins at runtime (which we do). </P>
<P><IMG height=3D13 alt=3D"Note: "=20
src=3D"http://eclipse.org/articles/Article-RCP-1/images/note.gif" =
width=3D62>=20
Unfortunately, as of this writing there is no automatic way to do this =
so you=20
need to do the copies by hand. This process is error prone and a =
never-ending=20
source of frustration to RCP developers. See the troubleshooting section =
for=20
some helpful advice. Hopefully a future version of Eclipse will provide =
better=20
support for this. </P>
<P>When you're done you should have a structure that looks like =
this:</P><PRE>    RcpTutorial1
    |    startup.jar
    +--- plugins
         +--- org.eclipse.core.expressions_3.0.0
         +--- org.eclipse.core.runtime_3.0.0
         +--- org.eclipse.help_3.0.0
         +--- org.eclipse.jface_3.0.0
         +--- org.eclipse.osgi_3.0.0
         +--- org.eclipse.swt.win32_3.0.0
         +--- org.eclipse.swt_3.0.0
         +--- org.eclipse.ui.tutorials.rcp.part1_0.0.0
         +--- org.eclipse.ui.workbench_3.0.0
         +--- org.eclipse.ui_3.0.0
         +--- org.eclipse.update.configurator_3.0.0
</PRE>
<P>That's all you need to run an RCP application, but it would be =
difficult for=20
anyone to use it without some kind of launching program. Eclipse uses=20
eclipse.exe, but for this example we'll just use a batch file. On =
Windows,=20
create a command file called rcptutorial1.cmd and place it in the top =
level=20
RcpTutorial1 directory. </P><PRE>   echo on
   setlocal
   cd %~dp0
   start javaw -cp startup.jar org.eclipse.core.launcher.Main
      -application org.eclipse.ui.tutorials.rcp.part1.RcpApplication %*
   endlocal
</PRE>
<P>The start command should be all on one line. As before, the =
-application=20
option refers back to the id specified on the=20
<CODE>org.eclipse.core.runtime.applications extension point.</CODE></P>
<P><IMG height=3D13 alt=3D"Tip: "=20
src=3D"http://eclipse.org/articles/Article-RCP-1/images/tip.gif" =
width=3D62> Specify=20
the <CODE>-clean</CODE> option on the command line to cause the core =
runtime to=20
discard its caches and re-read all the plug-in manifests. Normally, =
Eclipse=20
caches manifest information to speed startup, but if you are adding and =
removing=20
plug-ins or changing configuration options the cache may get out of =
sync. Remove=20
<CODE>-clean</CODE> for best performance in production applications. =
</P>
<P><IMG height=3D13 alt=3D"Note: "=20
src=3D"http://eclipse.org/articles/Article-RCP-1/images/note.gif" =
width=3D62> The=20
Linux shell version is similar, but for some reason you have to add a =
few extra=20
options to identify the operating and window system. I can't verify this =
because=20
I don't have a Linux system but this command line is reported to work: =
</P><PRE>   java -cp startup.jar org.eclipse.core.launcher.Main
      -application org.eclipse.ui.tutorials.rcp.part1.RcpApplication
      -os linux -ws gtk -arch x86 -nl en_US $*
</PRE>
<P><IMG height=3D13 alt=3D"Note: "=20
src=3D"http://eclipse.org/articles/Article-RCP-1/images/note.gif" =
width=3D62> To run=20
it under Mac OS, you must use the java_swt executable that comes with =
the=20
Eclipse SDK instead of the regular java executable that comes with the =
Java SDK.=20
</P>
<P>You can get as fancy as you want in this script file. Here's a =
variant that I=20
like to use when debugging because it will display any error messages =
from the=20
Eclipse loader in a separate window. This is for Windows; the Linux =
version=20
would be similar.</P><PRE>   echo on
   setlocal
   cd %~dp0
   java -cp startup.jar org.eclipse.core.launcher.Main
      -application org.eclipse.ui.tutorials.rcp.part1.RcpApplication
      -consoleLog %* || pause
   endlocal
</PRE>
<P>The java command should be all on one line.</P>
<P>To eliminate the startup window on Windows, you can use a shortcut =
instead of=20
a script file. Right click inside the RcpTutorial1 folder, select New =
&gt;=20
Shortcut and enter this as the location of the item (on one =
line):</P><PRE>    %windir%\system32\javaw.exe -cp startup.jar =
org.eclipse.core.launcher.Main
        -application org.eclipse.ui.tutorials.rcp.part1.RcpApplication
</PRE>
<P>Enter a descriptive name on the next page and then press Finish. Then =
try=20
double-clicking on your new shortcut to try it out. You may want to edit =
the=20
shortcut (right click on it and select Properties) to change the default =
working=20
directory. All these files can be found in the <A=20
href=3D"http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.ui.tutorials=
.rcp.part1">example=20
project</A>. </P>
<P><IMG height=3D13 alt=3D"Note: "=20
src=3D"http://eclipse.org/articles/Article-RCP-1/images/note.gif" =
width=3D62> For=20
fully branding a program with a splash screen, custom icons, and so =
forth you'll=20
need to set up some configuration files and use the eclipse.exe =
launcher. See=20
the online help under Platform Plug-in Developer Guide &gt; Programmer's =
Guide=20
&gt; Packaging and delivering Eclipse based products for more =
information. </P>
<H2>Troubleshooting</H2>
<P>After I wrote this tutorial I started getting mail from people who =
couldn't=20
run it for one reason or another. This section will collect the errors =
that=20
they've seen and the solutions. Remember to use the =
<CODE>-consoleLog</CODE>=20
command line option to see extra diagnostics in the console window where =
you=20
invoked your RCP application, and <CODE>-clean</CODE> to purge the core=20
runtime's cache of any stale information when changing plug-ins and=20
configurations. </P>
<DL>
  <DT><B>Launching failed because the following plug-ins are neither in =
the=20
  workspace nor selected on the Target Platform preference page: ...</B> =

  <DD>This one is a sanity check performed by PDE. It's pretty self =
explanitory=20
  so just look at the list provided, go to the Plug-ins tab of your =
launch=20
  configuration, and put a checkmark next to all of the plug-ins listed =
in the=20
  error.=20
  <DT><B>!MESSAGE Unable to locate application extension:=20
  org.eclipse.ui.tutorials.rcp.part1.RcpApplication</B>=20
  <DD>First, check to make sure that the plug-in containing your =
application is=20
  included in your launch configuration. Next, check the spelling, and =
remember=20
  that the application name is the plug-in id followed by a period and =
the id=20
  you specified on the =
<CODE>org.eclipse.core.runtime.applications</CODE>=20
  extension. This message might also be printed if all the required =
plug-ins are=20
  not available at run-time. Check the log for additional error messages =
that=20
  may identify the specific plug-ins that are missing.=20
  <DT><B>!MESSAGE Bundle =
update@/c:/RcpTutorial1/plugins/org.eclipse.ui_3.0.0/=20
  [13] was not resolved.</B>=20
  <DD>This one is a little tougher. It usually means that some =
prerequisite of=20
  the plug-in listed was not there. Usually the log will contain =
additional=20
  messages that will tell you which plug-ins were missing. You can also =
find out=20
  exactly what's going on by re-running the program with the=20
  <CODE>-console</CODE> command line option. This will allow you to =
enter OSGi=20
  console commands to diagnose the problem. After the error occurs =
again, go to=20
  the console window and enter the <CODE>ss</CODE> command. You'll see =
one or=20
  more plug-ins (bundles) which were installed but not resolved. Pick =
one of=20
  them (in the above message it would be number 13), and enter the =
<CODE>diag=20
  <I>nnn</I></CODE> command, where <I>nnn</I> is the bundle number. For =
example,=20
  "<B>diag 13</B>". This will tell you what the missing bundle is. Note =
that you=20