| <!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> |