| <!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 | |
| © 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 "IDE-ness" | |
| 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 > New > 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 ></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 ></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 > 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 > 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> |