Section 8.1.  Defining the Hyperbola Product - Eclipse Rich Client Platform: Designing, Coding, and Packaging Java Applications

8.1. Defining the Hyperbola Product

Before you can do any branding or packaging of Hyperbola, you must define a product configuration. Product configurations gather together all the information about splash screens, launcher icons, window images, about text, plug-in and feature lists, and so on into one place. Select the org.eclipsercp.hyperbola project and, if you are in the Plug-in Development perspective, use File > New > Product Configuration to start the New Product Configuration wizard as shown in Figure 8-1. Otherwise, use File > New > Other... > Plug-in Development > Product Configuration.

In the wizard, pick a location for the product configuration. The configuration file can go in any project associated with the product, but so far, we only have one project, so there's not much choice. Now, give it a filename such as "hyperbola.product". The configuration filename must end in ".product".

Next, choose a technique for initializing the configuration. The wizard can extract information from an existing product or launch configuration or simply create a basic product. If you have been following along, then you already have a launch configuration called "Hyperbola" or "Eclipse Application." The currently defined configurations are listed in the Use an existing launch configuration drop-down. Enable this option and pick a configuration you have already used and you know works.

When you click Finish, the wizard reads the launch configuration and uses it to build a product definition. In particular, it gets the list of plug-ins and the id of the application extension used in the launch. The new product configuration is opened in an editor, as shown in Figure 8-2.

Figure 8-2. Hyperbola product overview

[View full size image]

As with the plug-in editor, the product configuration editor gathers together information from many different files and presents it all in one place. The configuration information is grouped onto several tabs within the editor. The Overview page in Figure 8-2 shows the Product Definition section at the top.

Here, you specify the Product ID, the Application ID, and the Product Name of the product. In our case, the launch configuration used to initialize the product had only an Application ID, so the Product ID text field is empty. In fact, there are no products defined at alleven the drop-down list is empty. You need a product definition and id to tell Eclipse how to brand your application, so click New... to get the New Product Extension dialog shown in Figure 8-3.

As with applications, product extensions are contributed via extensions. They have an id and identify the application to run when the product is run. Choose the Hyperbola plug-in and type "product" in the Product ID field. The Hyperbola application should already be selected, but it's worth checking. Click Finish to return to the product editor. The new product and application values show up on the Overview page.

Synchronizing the configuration From time to time, you may make changes in the product editor and then try them out only to find they did not take effect. It is likely that the product configuration and its constituent files are not synchronized. As we mentioned at the outset, a product configuration is really an amalgam of information found in various files in the system. For example, the product extension is defined in the product plug-in's plugin.xml file. The application may be found in the same file or somewhere else. The information on the Configuration page may be found in the config.ini file or the product launcher's .ini file. Some of the branding information is stored in the product extension in the defining plug-in. The product editor gives you the ability to explicitly synchronize the product configuration with the files it encompasses. The Testing section on the Overview page has a link that offers to Synchronize this configuration with the product's defining plug-in. You should click on this when you change the configuration. PDE automatically synchronizes the configuration when you use the Launch links in the Testing section of the Overview page to run the product.

You still need to fill in the Product Name, "Hyperbola Chat Client". This is the string that appears in the title bar of the Hyperbola windows. Launch the product using the links in the Testing section of the Overview. Hyperbola should now look something like Figure 8-4.

Notice that the title bar of the window still says "Hyperbola". It should be "Hyperbola Chat Client" as you entered in the product configuration editor. Where's that coming from? Remember all the way back to Chapter 4, "The Hyperbola Application," when you first generated Hyperbola from the template? You entered "Hyperbola" in the template wizard and the string was embedded in the code of ApplicationWorkbenchWindowAdvisor.preWindowOpen():

configurer.setTitle("Hyperbola");

Go back and delete the setTitle() call and then run the application again. Figure 8-5 shows Hyperbola with a properly branded title bar label.

You may not have noticed, but launching the product caused a new launch configuration to be created. Open up the launch configuration dialog (Run > Run...) and take a look at the list. There is "Hyperbola," the one you used as a base for the product configuration, and a new one called "hyperbola.product" (assuming that is the name you used for your product configuration file). This new configuration is used by the product editor to launch your product. Since it is a normal launch configuration, you can run or debug it directly and use keyboard shortcuts such as F11 to debug the last launched configuration.

PDE keeps the launch configuration and product configuration synchronized. If you change the list of plug-ins in the product configuration and save, the launch configuration is updated. This relationship is one-waylaunching from or changing the launch configuration does not trigger any synchronization with the product configuration.