<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>

<head>
<title>Rich Client Platform</title>
<link href="../default_style.css" rel="stylesheet">
</head>

<body>

<div align="right"><font face="Times New Roman, Times, serif" size="2">Copyright
&copy; 2003-2006 Ed Burnette.</font>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
	<tbody>
		<tr>
			<td align="left" valign="top" colspan="2" bgcolor="#0080c0"><b><font
				face="Arial,Helvetica"><font color="#ffffff">Eclipse Article</font></font></b></td>
		</tr>
	</tbody>
</table>
</div>
<div align="left">
<h1 title="RCP Tutorial"><img src="../images/Idea.jpg" align="middle"
	width="120" height="86" alt=""></h1>
</div>
<h1 align="center">Rich Client Tutorial Part 1</h1>
<p class="summary">The Rich Client Platform (RCP) is an exciting new way
to build Java applications that can compete with native applications on
any platform. This tutorial is designed to get you started building RCP
applications quickly. It has been updated for Eclipse 3.1.2</p>
<p><b>By Ed Burnette, SAS</b><br>
<font size="-1">July 28, 2004<br>
<font size="-1"><b>Updated for 3.1.2:</b> February 6, 2006</font> </font></p>
<hr width="100%">

<h2>Introduction</h2>
<p>Try this experiment: Show Eclipse to some friends or co-workers who
haven't seen it before and ask them to guess what language it is written
in. Chances are, they'll guess VB, C++, or C#, because those languages
are used most often for high quality client side applications. Then
watch the look on their faces when you tell them it was created in Java,
especially if they are Java programmers.</p>
<p>Because of its unique open source license, you can use the
technologies that went into Eclipse to create your own commercial
quality programs. Before version 3.0, this was possible but difficult,
especially when you wanted to heavily customize the menus, layouts, and
other user interface elements. That was because the &quot;IDE-ness&quot;
of Eclipse was hard-wired into it. Version 3.0 introduced the Rich
Client Platform (RCP), which is basically a refactoring of the
fundamental parts of Eclipse's UI, allowing it to be used for non-IDE
applications. Version 3.1 updated RCP with new capabilities, and, most
importantly, new tooling support to make it easier to create than
before.</p>
<p>If you want to cut to the chase and look at the code for this part
you can find it in the <a href="part1.zip">accompanying zip file</a>.
Otherwise, let's take a look at how to construct an RCP application.</p>

<h2><a name="section_1"></a> Getting started</h2>
<p>RCP applications are based on the familiar Eclipse plug-in
architecture, (if it's not familiar to you, see the references section).
Therefore, you'll need to create a plug-in to be your main program.
Eclipse's Plug-in Development Environment (PDE) provides a number of
wizards and editors that take some of the drudgery out of the process.
PDE is included with the Eclipse SDK download so that is the package you
should be using. Here are the steps you should follow to get started.</p>

<p>First, bring up Eclipse and select <b>File &gt; New &gt; Project</b>,
then expand <b>Plug-in Development</b> and double-click <b>Plug-in
Project</b> to bring up the Plug-in Project wizard. On the subsequent
pages, enter a Project name such as <b>org.eclipse.ui.tutorials.rcp.part1</b>,
indicate you want a Java project, select the version of Eclipse you're
targeting (at least 3.1), and enable the option to Create an OSGi bundle
manifest. Then click <b>Next &gt;</b>.</p>

<p><img src="../images/note.gif" alt="Note: " width="62" height="13">
Beginning in Eclipse 3.1 you will get best results by using the OSGi
bundle manifest. In contrast to previous versions, this is now the
default.</p>

<p>In the next page of the Wizard you can change the Plug-in ID and
other parameters. Of particular importance is the question, "Would you
like to create a rich client application?". Select <b>Yes</b>. The
generated plug-in class is optional but for this example just leave all
the other options at their default values. Click <b>Next &gt;</b> to
continue.</p>

<p><img src="../images/note.gif" alt="Note: " width="62" height="13"> If
you get a dialog asking if Eclipse can switch to the Plug-in Development
Perspective click Remember my decision and select Yes (this is
optional).</p>

<p>Starting with Eclipse 3.1, several templates have been provided to
make creating an RCP application a breeze. We'll use the simplest one
available and see how it works. Make sure the option to Create a plug-in
using one of the templates is enabled, then select the Hello RCP
template. This is RCP's equivalent of "Hello, world". Click <b>Finish</b>
to accept all the defaults and generate the project (see Figure 1).
Eclipse will open the Plug-in Manifest Editor. The Plug-in Manifest
editor puts a friendly face on the various configuration files that
control your RCP application.</p>

<p><img src="images/part1project_cs.png" alt=""></p>
<p><b>Figure 1. The Hello World RCP project was created by a PDE wizard.</b></p>

<h2>Taking it for a spin</h2>
<p>Trying out RCP applications used to be somewhat tedious. You had to
create a custom launch configuration, enter the right application name,
and tweak the plug-ins that were included. Thankfully the PDE keeps
track of all this now. All you have to do is click on the Launch an
Eclipse Application button in the Plug-in Manifest editor's Overview
page. You should see a bare-bones Workbench start up (see Figure 2).</p>

<img src="images/part1_s.png" alt="">
<p><b>Figure 2. By using the templates you can be up and running an RCP
application in minutes. </b></p>

<h2>Making it a product</h2>
<p>In Eclipse terms a product is everything that goes with your
application, including all the other plug-ins it depends on, a command
to run the application (called the native launcher), and any branding
(icons, etc.) that make your application distinctive. Although as we've
just seen you can run a RCP application without defining a product,
having one makes it a whole lot easier to run the application outside of
Eclipse. This is one of the major innovations that Eclipse 3.1 brought
to RCP development.</p>

<p>Some of the more complicated RCP templates already come with a
product defined, but the Hello RCP template does not so we'll have to
make one.</p>
<p>In order to create a product, the easiest way is to add a product
configuration file to the project. Right click on the plug-in project
and select <b>New &gt; Product Configuration</b>. Then enter a file name
for this new configuration file, such as <b>part1.product</b>. Leave the
other options at their default values. Then click Finish. The Product
Configuration editor will open. This editor lets you control exactly
what makes up your product including all its plug-ins and branding
elements.</p>

<p>In the Overview page, select the <b>New...</b> button to create a new
product extension. Type in or browse to the defining plug-in (<b>org.eclipse.ui.tutorials.rcp.part1</b>).
Enter a Product ID such as <b>product</b>, and for the Product
Application select <b>org.eclipse.ui.tutorials.rcp.part1.application</b>.
Click <b>Finish</b> to define the product. Back in the Overview page,
type in a new Product Name, for example <b>RCP Tutorial 1</b>.</p>

<p><img src="../images/note.gif" alt="Note: " width="62" height="13"> In
Eclipse 3.1.0 if you create the product before filling in the Product
Name you may see an error appear in the Problems view. The error will go
away when you Synchronize (see below). This is a known bug that is fixed
in newer versions. Always use the latest available maintenance release
for the version of Eclipse you're targeting!</p>

<p>Now select the Configuration tab and click Add.... Select the plug-in
you just created (<code>org.eclipse.ui.tutorials.rcp.part1</code>) and
then click on Add Required Plug-ins. Then go back to the Overview page
and press <b>Ctrl+S</b> or <b>File &gt; Save</b> to save your work.</p>

<p><img src="../images/tip.gif" alt="Tip: " width="62" height="13"> If
your application needs to reference plug-ins that cannot be determined
until run time (for example the tomcat plug-in), then add them manually
in the Configuration tab.</p>


<p>At this point you should test out the product to make sure it runs
correctly. In the Testing section of the Overview page, click on
Synchronize then click on Launch the product. If all goes well, the
application should start up just like before.</p>

<h2>Plug-ins vs. features</h2>
<p>On the Overview page you may have noticed an option that says the
product configuration is based on either plug-ins or features. The
simplest kind of configuration is one based on plug-ins, so that's what
this tutorial uses. If your product needs automatic update or Java Web
Start support, then eventually you should convert it to use features.
But take my advice and get it working without them first.</p>

<h2>Running it outside of Eclipse</h2>
<p>The whole point of all this is to be able to deploy and run
stand-alone applications without the user having to know anything about
the Java and Eclipse code being used under the covers. For a real
application you may want to provide a self-contained executable
generated by an install program like InstallShield or NSIS. That's
really beyond the scope of this article though, so we'll do something
simpler.</p>

<p>The Eclipse plug-in loader expects things to be in a certain layout
so we'll need to create a simplified version of the Eclipse install
directory. This directory has to contain the native launcher program,
config files, and all the plug-ins required by the product. Thankfully,
we've given the PDE enough information that it can put all this together
for us now.</p>

<p>In the Exporting section of the Product Configuration editor, click
the link to Use the Eclipse Product export wizard. Set the root
directory to something like <b>RcpTutorial1</b>. Then select the option
to deploy into a Directory, and enter a directory path to a temporary
(scratch) area such as <b>C:\Deploy</b>. Check the option to Include
source code if you're building an open source project. Press <b>Finish</b>
to build and export the program.</p>

<p><img src="../images/note.gif" alt="Note: " width="62" height="13">
The compiler options for source and class compatibility in the Eclipse
Product export wizard will override any options you have specified on
your project or global preferences. As part of the Export process, the
plug-in is code is recompiled by an Ant script using these options.</p>

<p>The application is now ready to run outside Eclipse. When you're done
you should have a structure that looks like this in your deployment
directory:</p>
<pre>
    RcpTutorial1
    |    .eclipseproduct
    |    eclipse.exe
    |    startup.jar
    +--- configuration
    |         config.ini
    +--- plugins
              org.eclipse.core.commands_3.1.0.jar
              org.eclipse.core.expressions_3.1.0.jar
              org.eclipse.core.runtime_3.1.2.jar
              org.eclipse.help_3.1.0.jar
              org.eclipse.jface_3.1.1.jar
              org.eclipse.osgi_3.1.2.jar
              org.eclipse.swt.win32.win32.x86_3.1.2.jar
              org.eclipse.swt_3.1.0.jar
              <b>org.eclipse.ui.tutorials.rcp.part1_1.0.0.jar</b>
              org.eclipse.ui.workbench_3.1.2.jar
              org.eclipse.ui_3.1.2.jar
</pre>

<p><img src="../images/note.gif" alt="Note: " width="62" height="13">
Note that all the plug-ins are deployed as jar files. This is the
recommended format starting in Eclipse 3.1. Among other things this
saves disk space in the deployed application.</p>

<p><img src="../images/tip.gif" alt="Tip: " width="62" height="13">
Previous versions of this tutorial recommended using a batch file or
shell script to invoke your RCP program. It turns out this is a bad idea
because you will not be able to fully brand your application later on.
For example, you won't be able to add a splash screen. Besides, the
export wizard does not support the batch file approach so just stick
with the native launcher.</p>

<p>Give it a try! Execute the native launcher (<code>eclipse</code> or <code>eclipse.exe</code>
by default) outside Eclipse and watch the application come up. The name
of the launcher is controlled by branding options in the product
configuration.</p>


<h2>Troubleshooting</h2>
<dl>
	<dd>Error: Launching failed because the org.eclipse.osgi plug-in is not
	included...</dd>
	<dt>You can get this error when testing the product if you've forgotten
	to list the plug-ins that make up the product. In the Product
	Configuration editor, select the Configuration tab, and add all your
	plug-ins plus all the ones they require as instructed above.</dt>
</dl>

<h2>Compatibility and migration</h2>
<p>If you are migrating a plug-in from version 2.1 to version 3.1 there
are number of issues covered in the on-line documentation that you need
to be aware of. If you're making the smaller step from 3.0 to 3.1, the
number of differences is much smaller. See the References section for
more information.</p>

<p><img src="../images/tip.gif" alt="Tip: " width="62" height="13"> One
word of advice: be careful not to duplicate any information in both
plug-in.xml and MANIFEST.MF. Typically this would not occur unless you
are converting an older plug-in that did not use MANIFEST.MF into one
that does, and even then only if you are editing the files by hand
instead of going through the PDE.</p>

<h2>Conclusion</h2>
<p>In part 1 of this tutorial, we looked at what is necessary to create
a bare-bones Rich Client application. The next part will delve into the
classes created by the wizards such as the WorkbenchAdvisor class. All
the sample code for this part may be found in the <a href="part1.zip">accompanying
zip file</a>.</p>

<h2>References</h2>
<a href="../Article-RCP-2/tutorial2.html"> RCP Tutorial Part 2</a>
<br>
<a href="../Article-RCP-3/tutorial3.html"> RCP Tutorial Part 3</a>
<br>
<a href="http://www.eclipse.org/rcp" target="_blank"> Eclipse Rich
Client Platform</a>
<br>
<a
	href="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/org.eclipse.ui.examples.rcp.browser/readme.html"
	target="_blank">RCP Browser example (project
org.eclipse.ui.examples.rcp.browser)</a>
<br>
<a href="../Article-PDE-does-plugins/PDE-intro.html">PDE Does Plug-ins</a>
<br>
<a href="../Article-Internationalization/how2I18n.html">How to
Internationalize your Eclipse Plug-in</a>
<br>
<a href="../Article-Plug-in-architecture/plugin_architecture.html">Notes
on the Eclipse Plug-in Architecture</a>
<br>
<a
	href="http://help.eclipse.org/help31/topic/org.eclipse.platform.doc.isv/porting/eclipse_3_1_porting_guide.html"
	target="_blank"> Plug-in Migration Guide: Migrating to 3.1 from 3.0</a>
<br>
<a
	href="http://help.eclipse.org/help31/topic/org.eclipse.platform.doc.isv/porting/eclipse_3_0_porting_guide.html"
	target="_blank"> Plug-in Migration Guide: Migrating to 3.0 from 2.1</a>
<br>

<p>To discuss or report problems in this article see <a
	href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=104146">bug 104146</a>.</p>

<p><small>IBM is trademark of International Business Machines
Corporation in the United States, other countries, or both.</small></p>
<p><small>Java and all Java-based trademarks and logos are trademarks or
registered trademarks of Sun Microsystems, Inc. in the United States,
other countries, or both.</small></p>
<p><small>Microsoft and Windows are trademarks of Microsoft Corporation
in the United States, other countries, or both.</small></p>
<p><small>Other company, product, and service names may be trademarks or
service marks of others.</small></p>

</body>

</html>