Painfree RCP in 3.1M7

This is an update to the Painfree RCP in 3.1M5 post.  All references have been updated, instructions checked, and new notes made to be current as of 3.1M7.

Getting Started
If you already have a working plugin, you might skip right to "Recipe 2: Creating a .product file" below.  [1]  However, it's useful and easy to first experiment by creating a new plugin that automatically gives you some out-of-the-box RCP framework code, separately from any previously existing plug-ins you might have.  Later, you can integrate your plug-ins when you've moved up a little on the learning curve.

Recipe 1: Creating a plug-in with RCP Framework Code

1. Right click in the Package Explorer and select "New > Project...".
2. Select "Plug-in Project".
3. Press "Next >".
4. Enter your Project name (for this recipe, I'll call it "PainfreeRCPDemo").
5. Press "Next >"
6. Look for the group "Rich Client Application" at the bottom of Plug-in Content wizard panel.
7. Where asks "Would you like to create a rich client application?" choose "Yes".
8. Press "Next >".
9. In the "Templates" wizard page, choose "RCP application with a view".
10. Press "Finish".  If asked to switch to the Plug-in Development Perspective, click "Yes".

This will bring up the Overview page for the "Temp" plug-in, with Manfest.MF file selected.  By selecting RCP application with a view, framework code for your Rich Client App was generated, giving you a convenient starting point for future modifications. 

To begin modifying the generated code, go to the "View.java" class in the PainfreeRCPDemo plug-in's src folder's "painfreercpdemo" package (created by default).  Rewrite the View.createPartControl() with your own SWT or JFace implementation.

Test your plug-in as an RCP application by selecting the PainfreeRCPDemo plug-in and then selecting  "Run as > Eclipse Application". [2]  For the unmodified example we've been working with so far, you should see a little window pop up that looks something like this:

Recipe 2 and 3 explain how to create and configure your rich client application's .product file.  You may continue using the PainfreeRCPDemo example started in Recipe 1 or do this using an existing plug-in [1].

Recipe 2: Creating a .product file

1. Right click on the plugin you want to use as the basis for your RCP application in the Package Explorer.  Select "New > Product Configuration"
2. In the Product Configuration wizard, enter your File name (must end with ".product").  I named mine PainfreeRcpDemo.product.  [3]
3. Press "Finish"

This will bring up the .product "Overview" which you'll recognize as similar to the plugin.xml (or Manifest.MF) Overview.  The next recipe will cover configuring your RCP application. To be brief, I've omitted any discussion on branding.

Recipe 3: Configuring your RCP Application .product

Click on the .product file in the PainfreeRCPDemo plug-in to bring up the Overview page (showing the Overview tab).

Select a "Product ID:" by clicking "New...".  In the "Product Definition" dialog, choose a "Defining Plug-in:" by clicking "Browse..." and choosing the core plug-in for your RCP app.  To continue my example, I selected PainfreeRCPDemo (1.0.0)".

1. Enter a "Product ID:".  I entered "PainfreeRcpDemo_ProductID". 
2. In the "Product Application" section, select the .application configuration that will serve as the entry point for running your RCP app.  If using the running example, select "PainfreeRcpDemo.application."
3. Press "Finish".
4. In the .product Overview page, enter an application name. [4]
5. From the .product Overview page, click on the "product configuration" link to add the plug-ins that will make up your RCP app. This will take you to the "configuration" tab.
6. Click "Add," select your plugin (PainfreeRCPDemo in the example), and press Ok.
7. Repeat until all plug-ins you explicitly want bundled in this rich client application have been added.
8. Save All.

You should notice that your Overview page has been populated with the Product ID, Application, and Product name with "plug-ins" selected by default (note here that you would choose "features" if you were working with features and not plug-ins). 

At this point, you can test your rich client app by clicking the "Launch the product" link in the Overview page's Testing section.  Make sure it runs before cooking the next, final recipe.

Recipe 4: Exporting your RCP Application

Now that you've created a .product file, configured your RCP application, and tested it, you're ready to export this thing.  In case you the flow of things didn't sink all the way in yet, here's one last recipe:

1. Click the "Synchronize" link in the .product Overview page.  To make sure all .product file references to dependent plug-ins are current.
2. Click on the Eclipse product export wizard link to begin exporting your RCP app.
3. In the Export Destination section, enter an "Archive file:" name for your RCP app.  By default, .zip is the file type.
4. Optionally choose a destination directory and then press "Finish." This will zip up everything that is necessary to run your RCP application. [5]

To run the (PainfreeRCPDemo app, just unzip the contents of the zip anywhere you like and click on "eclipse.exe".  Viola!  Branding your app is even easier.  Just click the "Branding" tab on the .product Overview tab and intuitively step through it.  On a final note, distributing RCP apps can be done rather quickly as well.  For info on this, you might want try downloading and dissecting Ed Burnette's example in SourceForge. 

---

---

Thanks To
Luis de La Rosa, Dan Phifer, and several others for their feedback and comments on the first Painfree RCP post.

Additional Information
[1]  Start with Recipe 1 if you've never created a rich client application before.  This will give you some basic familiarity with the available functionality.  Also, it will aid you in converting an existing plug-in into an rich client application by giving you a clean point of reference.

[2]  When I did this, I saved this runtime configuration separately as "PainfreeRCPDemo".  To save a runtime configuration, select Run... and enter your your runtime name (see the Eclipse IDE Help for more info on this).

[3]  Here, you may be tempted to change the defaulted "Use an existing product (value = "org.eclipse.platform.ide") and choose "Create configuration file with basic settings."  While this used to work in Eclipse 3.1M5, it will cause problems later when configuring your 3.1M7's .product file.

Specifically, the necessary plug-ins for running your rich client application will not be automatically discovered.  This will cause an osgi plugin is missing error when trying to launch your rich client application.

[4]  In 3.1M7 there is a bug that keeps the product name from being updated in PainfreeRcpDemo's plugin.xml file correctly when creating a .product using the "Create configuration file with basic settings" option in the New Product Configuration wizard (see [2] for an explanation). 

To fix this, go to the PainfreeRcpDemo plug-in's plugin.xml and find the "product" element.  It is a child of the extension with the "PainfreeRcpDemo_Product_ID" as the value for the "id" attribute:

<extension
         id="PainfreeRcpDemo_Product_ID"
         point="org.eclipse.core.runtime.products">
      <product
            application="PainfreeRcpDemo.application/>

You'll see a red "x" showing an error.  Ad "name="Painfree RCP" to the product element:

      <product
            application="PainfreeRcpDemo.application
            name="Painfree RCP/>

Save.  The red "x" should disappear.

[5]  Because the PainfreeRcpDemo app includes the entire Eclipse IDE workbench, this will take a few seconds (see [3], [4] for explanation)

Comments

[Nick Edgar]

Nice tutorial, Benjamin. There are a couple of places above where you say ".properties file" where you meant ".product file".