How to understand and use Eclipse Production Configuration

Document options Print this page E-mail this page Document options requiring JavaScript are not displayed Sample code developerWorks comes to you! Export content to your iGoogle page and desktop Rate this page Help us improve this content

Level: Intermediate

Xing Xing Li (lixx@cn.ibm.com), Software Engineer, IBM
Ying Xi Zhao (lois_alert@sohu.com), Software Engineer

08 May 2007

This article provides step-by-step guidelines on how to package and manage a Rich Client Platform (RCP) application as a product with your own branding by using Eclipse's Production Configuration and PDE. Besides common concepts such as splash screen and an icon file's color and size, this article also introduces advanced branding aspects of production configuration: the RCP executable file and its configuration file, progress bar and message, RCP window image, About dialog and welcome page (i.e., introduction). With this article, you can grasp the main skills on encapsulating your RCP application as a distributable product, independent of Eclipse platform.

Before Production Configuration was introduced in Eclipse V3.1, RCP developers confronted the problem of how to effectively and efficiently package, and deliver their RCP projects with the required plug-ins. This problem, in fact, is a consumption issue because it essentially determines the distribution and usability of their software. Thanks to Eclipse V3.1's new Production Configuration feature, you can now wrap their applications with dependencies and branding elements easily. This article details how to leverage Eclipse Product Configuration with a sample RCP application: a game called Frog Across River.

To get the most out of this article, you need an Eclipse development environment and the sample code. If you don't have Eclipse already, download the following:

1. JRE V1.5.0 or later; Eclipse requires the Java Runtime Environment to operate
2. Eclipse Platform or IBM Rational Software Development Platform V7.X
3. The sample code in the Download section

Prerequisite: An RCP application

The prerequisite of Eclipse Product Configuration is an existing RCP application. You will need it as the bootstrap entry of your product. In this section, you will develop a game of Frog Across River as an RCP application using the following instructions. This RCP application is a plug-in project that will extend the org.eclipse.core.runtime.applications extension and play the entry role of your product. Alternately, you can skip through this section by importing the whole project by downloading the attached (see Download) to get a sample RCP application for later scenarios.

Create a sample RCP plug-in

First, we generate a plug-in project following these steps. Launch Eclipse, shift to the plug-in development perspective by selecting Window > Open Perspective > Other... > Plug-in Development.

1. From the Eclipse menu, select File > New > Project... > Plug-in Development > Plug-in Project and click Next.
2. In the Plug-in Project wizard page, input com.example.zyx as project name and click Next.
3. In the Plug-in Content wizard page, accept all default settings and click Yes for the "Would you like to create a rich client application?" option, then click Next.
4. In the Templates wizard page, select Hello RCP template and click Finish. Afterward, you will find a project named com.example.zyx in the workspace.

Import the RCP game source code

Copy all Java source files (.java files) from com.example.zyx.zip to the workspace, replacing the existing ones:

• Application.java
• ApplicationActionBarAdvisor.java
• ApplicationworkbenchAdvisor.java
• ApplicationWorkbenchWindowAdvisor.java
• Perspective.java
• GameView.java

This RCP project will create the Frog Across River game in a GUI view that enables mouse and keyboard input on the menu bar and canvas. Its design architecture is shown in Figure 1.

Among them, Application.java must implement the IPlatformRunnable interface because the plugin.xml file has extended the extension point of org.eclipse.core.runtime.applications. That means you should implement the run() method of IPlatformRunnable, which is responsible for creating the SWT display and starting up a workbench.

                        public class Application implements IPlatformRunnable {
                        public Object run(Object args) throws Exception {
                        ...
                        int returnCode = PlatformUI.createAndRunWorkbench(display,
                        new ApplicationWorkbenchAdvisor());
                        ...
                        }
                        }

ApplicationActionBarAdvisor.java is used to create and display menu bar.

                        public class ApplicationActionBarAdvisor extends ActionBarAdvisor {
                        ...
                        private IWorkbenchAction exitAction;
                        private IAction gameAction;
                        ...
                        protected void fillMenuBar(IMenuManager menuBar) {
                        IMenuManager viewMenu = new MenuManager("&Game","Game");
                        menuBar.add(viewMenu);
                        viewMenu.add(gameAction);
                        viewMenu.add(exitAction);
                        }
                        }
                        

GameView.java is the core of this RCP game. It loads images, renders the display, responds to user actions (mouse and keyboard events), and controls the whole process of the game.

Double-buffer technology is applied to avert screen flicker and flash during animation. Why? When you instruct JVM to display an animation, JVM will clear the screen, show the window, paint the screen, and show it again. That degrades your application's appearance. Double-buffering boosts performance by painting an off-screen image, then dumping it to the display.

                        public class GameView extends ViewPart {
                        ...
                        public void createPartControl(final Composite parent) {
                        ...
                        canvas.addMouseListener(new MouseAdapter() {
                        public void mouseDoubleClick(MouseEvent e) {
                        }
                        });
                        canvas.addKeyListener(new KeyAdapter() {
                        public void keyPressed(KeyEvent e) {
                        ...
                        }
                        canvas.addPaintListener(new PaintListener() {
                        public void paintControl(PaintEvent event) {
                        final Image image = new Image(parent.getDisplay(), canvas.getBounds());
                        final GC gcImage = new GC(image);
                        ...
                        event.gc.drawImage(image, 0, 0);
                        ...
                        }
                        

Copy the code list below into plugin.xml file because your RCP game will show up a view as the GUI to interact with users.

                        <extension point="org.eclipse.ui.views">
                        <category id="com.example.zyx.browser"
                        name="Browser Example"/>
                        <view id="com.example.zyx.GameView"
                        name="Browser"
                        icon="icons/window16x16.gif"
                        class="com.example.zyx.GameView"
                        category="com.example.zyx.browser"/>
                        </extension>
                        

Launch the RCP game in Eclipse

To execute the RCP game application in Eclipse, switch to the Overview tab of plugin.xml and click Launch an Eclipse application. A new Eclipse application launch configuration will be created for you, and you will find the execution result of your RCP game, as shown in Figure 2.

Back to top

Create your product configuration

You will create a Product Configuration file (.product) to wrap up the Frog Across River RCP application as a product. You can locate it in any project or folder.

To generate a Product Configuration file, select File > New > Other > Plug-in Development > Product Configuration, then click Next. When the Product Configuration wizard page appears, select com.example.zyx plug-in project as its parent folder, input myProduct.product as its file name, select "Create a configuration file with basic settings" and click Finish (see Figure 3).

Back to top

Configure

In this section, we introduce how to define and customize the product published with your RCP application after you create your .product file. You need to import some files and folders into your plug-in project from com.example.zyx.zip before you set up the Product Configuration. They are listed in Figure 4.

The following table provides the description of these resources.

Overview tab

First, click the Overview tab (see Figure 5). You will set up the Product Definition here. The product definition consists of Product Name, Product ID, and an Application associate with the Product ID. What's more, it is specified whether the product configuration unit is based on plug-in or feature.

Product Name defines the name of the product, which will be shown in the title bar. Input %productName in the Product Name text field, which will automatically refer to the values in plugin.properties file according to the locale. Product ID defines the product ID and it associates with the Application ID. Click New... to the right of Product ID. When the Product Definition window pops up, choose com.example.zyx as the Defining Plug-in, then select com.example.zyx.application as its associated application, and use product as its product ID. Click Finish to return to the Overview tab. Select plug-ins radio button in the "The product configuration is based on" section.

You can see the product name in the title bar when you launch the product, as shown below.

Configuration tab

Click the Configuration tab. You will define the elements in you product and the configuration file. The "Plug-ins and Fragments section" lists all plug-ins and fragments that will be packaged in your product.

Click Add... to the right of the Plug-ins and Fragments list, then select the com.example.zyx plug-in, and click OK. Click the Add Required Plug-ins button, then all required plug-ins and fragments are added. The "Configuration File" section is used to set up the product runtime information. This file must be named config.ini. You can accept its default setting, which will generate a default config.ini file in configuration folder when the product is exported. The following gives a sample of the file's content.

                        #Product Runtime Configuration File
                        osgi.splashPath=platform:/base/plugins/com.example.zyx
                        eclipse.product=com.example.zyx.product
                        osgi.bundles=org.eclipse.equinox.common@2:start,org.eclipse.update.configurator@3:start,
                        org.eclipse.core.runtime@start
                        osgi.bundles.defaultStartLevel=4
                        

The first line determines the location of splash screen, which will be displayed when product launches. The second line defines the product name.

In the last two lines, StartLevel is used by the product to launch plug-ins after they have been successfully installed and resolved. In other words, StartLevel defines the startup sequence of these core plug-ins. A start level is defined as a non-negative integer. The products will launch plug-ins with Start Level 0. Afterward, it's the turn of all plug-ins with start level 1. This progress won't end until it reaches its designated start level: the defaultStartLevel or the osgi.startLevel. In this sample config.ini file, the defaultStartLevel is 4. The default value for the osgi.startLevel property is 6.

Launcher tab

Click the Launcher tab, where you will set the Program Launcher and Launching Arguments.

Program Launcher is used to specify launcher name and launcher icons, in the form of an .exe file for Windows® to launch your product after you have exported it. Input FrogAcrossRiver in the Launcher Name text field. Click the radio button Use a single ICO file containing 7 images as specified above, then click Browse... and navigate to select the 7Images.ico file in the icons folder. You can generate and use your own icon file or just leverage BMP images by clicking Specify separate BMP images.

An .ico file is a container that includes required image files with different size and color modes for its host application. Windows selects the image it needs to use, based on the user's display settings. If the icon does not contain the appropriate size or color mode, Windows will take the closest size and resolution, and render the icon to suit.

Launching arguments provides the product with the default program arguments and VM arguments. In its way, an .ini file with the same name as the launcher mame will be generated in the root of the exported folder to record these arguments. Input -console in the Program Arguments text field, which will open a console window when your product is launched. After you export the product, go to the exported folder, you can find the .exe and .ini files as shown below.

Splash screen

A splash screen will appear when the product launches. This file must be located in the root folder and be named splash.bmp. Otherwise, the product will not find it at runtime.

Click Browse... on the right of Plug-in test field and select the plug-in project where the splash file resides. Progress bar and Progress message are used to indicate the process status on the splash screen. Add the following value into the plugin_customization.ini file.

org.eclipse.ui/SHOW_PROGRESS_ON_STARTUP=true
                        

Next, add the following property to the product extension section of the plugin.xml file.

<property name="preferenceCustomization" value="plugin_customization.ini">
                        </property>
                        

Then select Add a progress bar. Input 0 and 280 for x-offset and y-offset, and input 455 and 15 for width and height. Then select Add a progress message. Input 7 and 220 for x-offset and y-offset, and input 441 and 20 for width and height. Select your favorite color in Text Color for the progress message. When you launch the product, you can see the splash screen come up, and the progress bar and progress message appear.

Window images

Images for your application window are configured in this section (see Figure 12). These images must be in GIF format. An image with a size of 16x16 appears in the upper-left corner of the window and task bar. A 32x32 image appears in the Alt+Tab application switcher.

With the Browse... button, define the 16x16 and 32x32 images you want from your project's icon folder. Then go to the plugin.xml file to verify your configuration with following declaration:

<property name="windowImages" value="icons/alt_window_16.gif,icons/alt_window_32.gif">
                        </property>
                        

After you launch the product, you will see the images is displayed in Figure 13.

About dialog

The About dialog consists of the about image rendered on the left and the about text briefly introducing your product. You will manage these two items in this section.

Click Browse... to the right of Image text field and select a GIF file from the icon folder.

There are two ways to define the about text. One is to directly input the text in the Text field; the other is to define a key and value pair in the plugin.properties file and refer to the key in the Text field. As you will leverage the second one, just input %productBlurb in the Text field as shown in Figure 14. productBlurb is the key defined in the plugin.properties file, as shown below.

                        pluginName=Frog Across River
                        providerName=Xing Xing Li and Ying Xi Zhao
                        productName=My Product
                        productBlurb=My Product based on Eclipse Platform\n\
                        \n\
                        Version: 1.0.0\n\
                        Build id: M20061124-1422 \n\
                        \n\
                        Welcome to my Product based on Eclipse Product Configuration. \n\
                        A RCP game is encapsulated in it with customized branding elements.\n\
                        \n\
                        This product is developed by Xing Xing Li and Ying Xi Zhao \n\
                        (c) Copyright by authors. All rights reserved\n\
                        

You need to add an action so that the menu item for the About dialog will appear in the menu bar of your product, such as Help > About. Open the ApplicationActionBarAdvisor.java file and remove the comment tags to activate the following code.

                        public class ApplicationActionBarAdvisor extends ActionBarAdvisor {
                        ...
                        private IWorkbenchAction aboutAction;
                        protected void makeActions(final IWorkbenchWindow window) {
                        ...
                        aboutAction = ActionFactory.ABOUT.create(window);
                        register(aboutAction);
                        ...
                        }
                        protected void fillMenuBar(IMenuManager menuBar) {
                        //Help
                        MenuManager helpMenu = new MenuManager("&Help",IWorkbenchActionConstants.M_HELP);
                        menuBar.add(helpMenu);
                        // About > Help
                        helpMenu.add(new Separator());
                        helpMenu.add(aboutAction);
                        ...
                        }
                        }
                        

After you launch your product and select Help > About, the About dialog will appear.

Welcome page

A welcome page is used to introduce the product information, which is especially helpful for new users. You can depict all features, usage, and tips of your product via the welcome page.

To enable a welcome page in your product, you will extend two extensions: org.eclipse.ui.intro and org.eclipse.ui.intro.config. Add the following code into the plugin.xml file.

                        <extension
                        point="org.eclipse.ui.intro">
                        <intro
                        class="org.eclipse.ui.intro.config.CustomizableIntroPart"
                        icon="icons/alt_window_16.gif"
                        id="com.example.zyx.intro">
                        </intro>
                        <introProductBinding
                        introId="com.example.zyx.intro"
                        productId="com.example.zyx.product">
                        </introProductBinding>
                        </extension>
                        <extension
                        point="org.eclipse.ui.intro.config">
                        <config
                        content="introContent.xml"
                        id="com.example.zyx.configId"
                        introId="com.example.zyx.intro">
                        <presentation
                        home-page-id="root">
                        <implementation
                        kind="html"
                        os="win32,linux,macosx">
                        </implementation>
                        </presentation>
                        </config>
                        </extension>
                        

Next, add an action in menu bar by selecting Help > Welcome. Open the ApplicationActionBarAdvisor.java file again and remove the comment tag of the following code.

                        public class ApplicationActionBarAdvisor extends ActionBarAdvisor {
                        ...
                        private IWorkbenchAction introAction;
                        protected void makeActions(final IWorkbenchWindow window) {
                        ...
                        introAction = ActionFactory.INTRO.create(window);
                        register(introAction);
                        }
                        protected void fillMenuBar(IMenuManager menuBar) {
                        ...
                        helpMenu.add(introAction);
                        ...
                        }
                        }
                        

You will see the following welcome page when you launch your product.

Back to top

Publish Your RCP product

Test before publishing

Go back to the Overview tab and find the Testing section. When you have changed the product name, window images, about image and about text, etc., click Synchronize link to reflect your changes to plugin.xml to ensure that the plug-in manifest is up to date. Click Launch the product to test your product before it's exported.

There is an example of how the Synchronize link works. Change the product name from %productName to my product, then click Synchronize. Go to the plugin.xml file and verify whether the product name value ws changed to my product. After that, change it back to %productName and click Synchronize, then click Launch the product, and your product will launch.

Export product

Go to the find Exporting section of the Overview tab, where there is a link to export your product. Click the Eclipse Product export wizard. In the export dialog that pops up, specify MyProduct as the Root directory and C:\export as the destination directory.

After clicking Finish, verify the export result by navigating to the C:\export\MyProduct directory. You will find the FrogAcrossRiver.exe and FrogAcrossRiver.ini files in which your launching arguments are recorded. You will also verify that the icon of the FrogAcrossRiver.exe file is what you desire.

If you have installed JRE, double-click the FrogAcrossRiver.exe to launch your product.

Congratulations! You configured and published your RCP application as a product successfully.

JRE

This tip can help you publish your product on a non-JRE OS: Just find a platform with JRE installed, copy its JRE directory into the root folder of your exported product, as shown below.

Double-click FrogAcrossRiver.exe and it launches your RCP product successfully.

Back to top

Troubleshooting

1. You will be notified if your .ico file doesn't include the required image files in the specified sizes or color depths with the error message: [Program Launcher] The launcher may not get branded correctly, .ico file is missing its image. Similarly, you will get the following warning message if you specified an invalid image in the .product file: [About Dialog] Image: path/ImageName — is not a path to a valid file.
2. If you add -clean in Program Arguments and launch the product from an exported folder, you will not see the splash screen. However, you can see it when launched from the Launch the product link.

Back to top

Summary

Share this... Digg this story Post to del.icio.us

This article has shown how to create and pack your branded Eclipse product by leveraging Eclipse's Product Configuration and PDE. Although you can do this using a script, we have demonstrated a more effective and efficient way to produce the product where you can configure and manage all branding information and elements. Most importantly, this article has shown the possibilities of an RCP world with the aid of the Eclipse Production Configuration feature.

Back to top

Download

	Information about download methods

Resources

• The "Rich Client Tutorial Part 1" introduces basic instructions of RCP development.
  
  
• "PDE Does Plug-ins" gives a background description on how to develop in Eclipse's PDE.
  
  
• Read "How to Build an Eclipse Product" to learn more about Eclipse product primary principles.
  
  
• "Creating product branding" describes some elements (such as icon and splash screen) in product banding.
  
  
• Check out the "Recommended Eclipse reading list."
  
  
• Browse all the Eclipse content on developerWorks.
  
  
• Users new to Eclipse should look at the Eclipse start here.
  
  
• Expand your Eclipse skills by checking out IBM developerWorks' Eclipse project resources.
  
  
• To listen to interesting interviews and discussions for software developers, check out check out developerWorks podcasts.
  
  
• For an introduction to the Eclipse platform, see "Getting started with the Eclipse Platform."
  
  
• Stay current with developerWorks' Technical events and webcasts.
  
  
• Check out upcoming conferences, trade shows, webcasts, and other Events around the world that are of interest to IBM open source developers.
  
  
• Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.
  
  

• Download the latest Eclipse SDK and try its Product Configuration feature with your RCP projects.
  
  
• Check out the latest Eclipse technology downloads at IBM alphaWorks.
  
  
• Download IBM product evaluation versions, and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
  
  
• Innovate your next open source development project with IBM trial software, available for download or on DVD.

• Learn more about RCP from the Eclipse Foundation's Official Eclipse FAQs.
  
  
• The Eclipse Platform newsgroups should be your first stop to discuss questions regarding Eclipse. (Selecting this will launch your default Usenet news reader application and open eclipse.platform.)
  
  
• The Eclipse newsgroups has many resources for people interested in using and extending Eclipse.
  
  
• Participate in developerWorks blogs and get involved in the developerWorks community.