Section 4.1. Hyperbola Hello World - Eclipse Rich Client Platform: Designing, Coding, and Packaging Java Applications

4.1. Hyperbola Hello World

You are now set up to develop Eclipse RCP applications. Here we show you how to use the built-in wizards and tooling to create a simple skeleton for the Hyperbola chat client developed throughout the book.

The first thing you need is a plug-in project to hold your code. Go to File > New > Project... to start the new project wizard. Choose Plug-in Project and click Next. On this page, enter the project name. Since you are just starting on Hyperbola, enter "org.eclipsercp.hyperbola". Click Next and you should see a page similar to Figure 4-1.

Figure 4-1. Defining the plug-in content

Here, enter the information about the plug-in itselfits id, version, name, etc. Based on the project name, the wizard guesses reasonable initial settings for most fields. The only things to change are:

Uncheck the Plug-in Class option. We won't need a plug-in class for some time. Perhaps never! Typically, you only need a plug-in class if your plug-in needs some sort of initialization the first time it is accessed.
Select the Yes radio button in the Rich Client Application area of the page. This tells the wizard to show the RCP templates on the next page rather than the standard templates.

Note

Notice here that the Classpath field is empty. As of Eclipse 3.1, it is common practice to ship a plug-in as a JAR file. In this case, the plug-in itself is on the classpath, so there is no need to specify a value.

Project names and plug-in ids

Project names such as org.eclipsercp.hyperbola look a little strange at firstthey look a lot like Java package names! In fact, the Eclipse community uses two conventions to manage the plug-in and project namespace. First, we use the reverse domain name convention (i.e., Java package naming) to identify plug-ins. Plug-ins are likely to end up in a pool with plug-ins from other sources, so they need to have globally unique identifiers. Using reverse domain names as plug-in id roots is a convenient, human-readable way of managing that namespace.

Since every plug-in is developed in a project, it is a convenient convention to match project names with the ids of the plug-ins they contain. In our example, both the project and its plug-in are called org.eclipsercp.hyperbola. Of course, you should ensure that you own the rights to the related domain (e.g., eclipsercp.org in this case).

Both of these practices are conventions not rules. We could have called the project Hyperbola and set the plug-in id to org.eclipsercp.hyperbola, but that makes it hard to remember which project is for which plug-in, etc.

Click Next and the wizard moves to the RCP Templates page. There are templates of varying complexity. For this part of the book, pick the Hello RCP template to create what is probably the simplest RCP application possible.

Click Next to advance the wizard to the page shown in Figure 4-2. Here, you identify the Hyperbola application and give it a window title and perspective name, etc. You should only have to change the Application window title.

Figure 4-2. Identifying the contents of the application

That's it. Click Finish to create your first Eclipse RCP application. You may be prompted to change to the Plug-in Development perspective. This is an arrangement of views in the Eclipse development environment that is particularly useful for plug-in development. We suggest that you select Yes here.

When the wizard completes, your workspace contains a single project with the name org.eclipsercp.hyperbola, as shown in Figure 4-3. The project contains an src folder that contains the Java source files generated from the template by the new project wizard.

Figure 4-3. Hello Hyperbola project structure

If you selected Yes to switch to the plug-in development perspective, your new plug-in is opened in a plug-in editor. The editor provides a comprehensive view of the various parts of the plug-in definition captured in different files such as plugin.xml, MANIFEST.MF, and build.properties. The plug-in editor works on all of these at onceyou can edit all aspects of a plug-in in one place. Figure 4-4 shows the first page of the editor.

Figure 4-4. Hyperbola plug-in editor

[View full size image]

Note

If you close the plug-in editor and want it back, just double-click on the plugin.xml or MANIFEST.MF files, or use Open on the context menu for the files.

To take Hyperbola for a spin, use the links in the Testing section of the Overview page. Click on the Launch an Eclipse application link and run Hyperbola. This launches Hyperbola as a separate Eclipse RCP application in its own JVM. As you can see from Figure 4-5, it doesn't do much, but it's a start.

Figure 4-5. Simple Hyperbola shell

While the plug-in editor is open, take a look around. Along the bottom of the editor there are tabs for the different aspects of the plug-in. Go to the Dependencies page and notice that the Hyperbola plug-in depends on two other plug-ins: org.eclipse.core.runtime and org.eclipse.ui. This means that the Hyperbola plug-in can use classes exposed by those plug-ins. It also means that classes in other plug-ins are not available to Hyperbola. This control over class visibility is fundamental to the Eclipse notion of modularity and your ability to build systems from sets of plug-ins using Eclipse.

The Dependencies page also has some useful Dependency Analysis tools to help you navigate the dependencies between plug-ins, find unused dependencies, look for cycles, etc.

What about those other plug-ins?

You may be asking "What about JFace, SWT, and OSGi? I thought those were part of the RCP as well." To find the answer, go to the Dependencies page in the Hyperbola plug-in editor and click on Show the plug-in in the dependency hierarchy in the Dependency Analysis section. You should see the hierarchy shown in Figure 4-6.

Figure 4-6. Hyperbola plug-in dependencies

Notice that some of the plug-ins under the Runtime and UI, for example, org.eclipse.swt, have little arrow decorations beside them. The arrows identify plug-ins that are re-exported by their parents in the treeorg.eclipse.ui in the case of the SWT plug-in. As such, anyone depending on the UI automatically depends on the re-exported SWT. Similarly, the UI re-exports JFace and org.eclipse.ui.workbench and the Runtime re-exports OSGi.

This dependency chaining mechanism is used wherever one plug-in exposes the API of another plug-in as part of its own API. For example, the UI API has classes and methods that name types found in SWT. To ensure that a plug-in requiring the UI gets a coherent dependency chain, the UI re-exports SWT. Note that the UI does not re-export all of its prerequisites, just those it exposes as part of its API.

Take a look at Hyperbola's Extensions page next. When PDE generated the Hyperbola skeleton, it added two extensions: an application and a perspective. If you poke around in here, you can see some of the values entered earlier as well as the names of various classes that were generated by the template.

These extensions are the mechanism for linking classes into the Eclipse infrastructure. For example, Figure 4-7 shows the Hyperbola perspective extension. Notice how it lists the new perspective class (org.eclipsercp.hyperbola. Perspective) and links it into the org.eclipse.ui.perspectives extension point.

Figure 4-7. Hyperbola extensions

[View full size image]

Take a look at the other pages in the editor if you like. If not, there will be plenty of opportunity to use them later. The next section walks through the generated code and highlights its structure. This is followed by a section on running and debugging Eclipse applications. Subsequent chapters build on this base and add more and more function.