Visit eclipse.org for more Eclipse RCP fun!

Eclipse Rich Client Platform

Designing, Coding, and Packaging Java Applications

How to run the samples for Chapter 23

Chapter 23 details a refactoring of Hyperbola to accomodate many different execution environments; from handhelds and kiosks to standalone desktop applications to integrated platform facility. Correspondingly, the sample code for this chapter is quite diverse. This document guides you through the different samples, what they do and how to run them. Deep dives into the code would have added several more chapters to the book and, while potentially useful, we felt that the code could speak for itself. Readers are encouraged to pick apart the code and understand what it is doing as well as looking at the coding patterns to see how they apply to their situation.

Overview

As outlined in the book text, there are several product configurations in Chapter 23. Each consists of a product feature, a product plug-in and a set of framework plug-ins. Here we focus mainly on the product feature and plug-in. The feature identifies the plug-ins necessary for the configuration of Hyperbola and contains the product configuration file (.product file). The product plug-in includes the product extension contribution as well as any advisor and application implementations and high-level branding.

In addition to the complete product definitions, there are some features that simply add funtion to Hyperbola. For example, multi-user chat capabilities and XMPP stream debugging.

The Workbench Configuration

Product Feature org.eclipsercp.hyperbola.feature.workbench
Product Plug-in org.eclipsercp.hyperbola.product.workbench
Product File org.eclipsercp.hyperbola.feature.workbench/workbench.product

This configuration is the canonical standalone RCP application configuration. It uses the Eclipse UI Workbench including its editor, view and perspective concepts to make Hyperbola into an extensible chat platform. To run this configuration, open workbench.product and on the Overview page click Launch the product.

You can export a completely standalone and branded workbench-based Hyperbola by selecting Eclipse Product export wizard link which is also found on the Overview page. As seen in Chapter 9, this creates an output archive or directory depending on how you direct the wizard. Notice that the output Hyperbola has integrated Intro content as well as Update support.

The JFace Configuration

Product Feature org.eclipsercp.hyperbola.feature.jface
Product Plug-in org.eclipsercp.hyperbola.product.jface
Product File org.eclipsercp.hyperbola.feature.jface/jface.product

The JFace configuration is functionally very similar to the Workbench configuration but is implemented just using JFace and SWT elements. As outlined in the book, most of the Hyperbola UI elements are in fact implemented directly on top of JFace. The workbench configuration integrates these with the UI Workbench by wrappering and contributes the JFace objects via the extension registry. The advantage of this configuration is primarily in size. Since it requires only JFace and does not have Intro and Update support, the total footprint of Hyperbola on disk only about 4.5MB! Since it is written based on the J2ME Foundation class libraries, an entire Hyperbola install including JRE is about 11MB.

As with the Workbench configuration, the JFace configuration can be run and exported from the product editor's Overview page.

The IDE Configuration

Product Feature org.eclipsercp.hyperbola.feature.ide
Product Plug-in org.eclipsercp.hyperbola.product.ide

The IDE configuration is intended to be integrated into an existing Eclipse IDE based system. As such, it merely makes contributions to an existing structure and does not define an application or product configuration.

To run this configuration use the Update Manager to install the IDE configuration feature from the eclipsercp.org update site (http://eclipsercp.org/updates) or a local copy of that site (e.g., download and unzip http://eclipsercp.org/book/RCP-book-CD.zip). Once the IDE configuration is added, you can chat directly from your development environment using the actions in the newly added Hyperbola menu.

Adding XMPP Debugging

Feature org.eclipsercp.hyperbola.feature.debug

As you surely know by now, Hyperbola is bases on the Smack XMPP messaging library. Smack includes a debugger that exposes the XMPP packet traffic to users so they can see what is going on. The Debug feature allows you to add these capabilities to an existing Hyperbola Workbench configuration via the Update Manager and an update site.

  1. Export the Workbench configuration as described above.
  2. Run it and use the Help > Add Extensions... menu to look for new function on the Hyperbola Update site. Note that the site used is controlled by the hyperbola.homebase system property set in Hyperbola/configuration/config.ini. You can change the value there before launching Hyperbola or set it on the command line using "-vmargs -Dhypberbola.homebase=<your location>". For example, you might use the location of the update site that came with the CD that you downloaded from http://eclipsercp.org.
  3. Once at the update site, select Hyperbola Site > Hyperbola Function > Hyperbola Debug Support and follow through all the steps in the wizard. At the end you can either Apply changes now or restart.
  4. After the debug support is installed, connect to an XMPP account (e.g., reader@eclipsercp.org) and then use the Tools > Show XMPP Debug menu entry to open the XMPP debug window. Sending and receiving messages should cause packets to appear in the debugger. Notice that the debugger is actually written with Swing but displayed in and managed by Eclipse.

Adding Multi-User Chat Capabilities

Feature org.eclipsercp.hyperbola.feature.muc
Plug-in org.eclipsercp.hyperbola.muc

Multi-User Chat (MUC) support is an optional add-on to Hyperbola. You can either install it explicitly or exercise the dynamic function install capabilities of Eclipse and Hyperbola. Let's do both.

  1. Install and start Jive Messenger as described at the end of Chapter 11. You can skip this if you already have two accounts on an XMPP-based server.
  2. You will need two copies of Hyperbola, one with MUC support (to originate the conference) and one without (to have MUC support dynamically installed). So export the Workbench configuration as described above to a directory called Without. Then copy the whole directory structure to With.
  3. Run With. Notice that it does not have MUC support. Add it using the steps outlined above for getting the Debug function but get Hyperbola MUC Support feature instead.
  4. In With, login as "user1" and set the server to "localhost" (if you are not using a local Jive Messenger, fill in the appropriate username and server address). Note that Hyperbola automatically attempts to create an account if one does not already exist so there is no need to create one manually.
  5. Start Without and login as "user2"
  6. In Without (user2), add user1 as a contact using Contacts > Add Contact....
  7. Now for the fun stuff. In With select user2 in the contacts list and right click to get the context menu. Choose Invite to Conference...
  8. In the resultant dialog, click New Chat... to create a new conference room. There pick a name for the conference (e.g., test@conference.localhost) and ensure that you have a nickname filled in. You don't have to enter a password.
  9. Click OK and then OK to open the conference and invite user1.
  10. After a short delay, Without should have MUC support installed and the two should be connected in the conference room you declared. That short delay was Without going to the hyperbola.homebase update site, getting the MUC support, installing it and then using it to process the incoming invitation.

The Kiosk Configuration

Product Feature org.eclipsercp.book.feature.kiosk
Product Plug-in org.eclipsercp.book.product.kiosk
Product File org.eclipsercp.book.feature.kiosk/kiosk.product

The Kiosk configuration is not really a configuration of Hyperbola but rather a configuration of Eclipse RCP that behaves like an extensible kiosk that happens to have Hyperbola as one of its available facilities. To use the Kiosk configuration, open the product file and use the Launch the product link on the Overview page.

This starts up the EclipseRCP Book kiosk. The kiosk consists of a single window with all trim and decoration removed, maximized to full screen and moved to the bottom of the window stack. Note that the native code to really lock down the desktop is beyond the scope of this book. This example is intended to be sufficient to demonstrate the concept.

The Kiosk presents several links down the left side. Clicking on the Hyperbola link, for example, opens Hyperbola. This is the regular Hyperbola Workbench configuration adapted (using an additional plug-in) to open in the kiosk. That is, the original code is used unmodified. The kiosk itself is extensible. Other applications can be added and exposed down the left side by contributing extensions to the kiosk's "windows" extension point.

The PocketPC Configuration

Product Feature org.eclipsercp.hyperbola.feature.pocketpc
Product Plug-in org.eclipsercp.hyperbola.product.pocketpc

The PocketPC configuration is a proof of concept demonstration of running Hyperbola on a handheld device. This is essentially the JFace configuration with a few modifications. To run this configuration you have to export it and then put it on the device with a suitable JRE (at least J2ME Foundation 1.0).

To be a fully integrated PocketPC applicaiton that looks and feels native requires some deeper UI changes than are presented here. For example, various interactions done using wizards or dialog boxes on the desktop should be structured differently on the PocketPC. In any event, this example at least demonstrates that much of the Hyperbola function can be directly reused in quite different environments.