Modular Mind

The poll to help select a new name for Eclipse RCP will wrap up on September 6th, so make your voice heard and vote today!

For more information on the purpose of the poll, as well as to see my picks, check out the initial announcement.

Note: You can view the survey results online.

When developing Eclipse RCP applications we execute our code in the IDE using a run configuration. A run configuration is basically a collection of properties that defines how our application should be run, and these properties include:

1. What application or product to launch, specified by id
2. Which bundles to make available at runtime
3. What program (Eclipse-specific) or VM arguments to use

And while run configurations are relatively straightforward, there can be some confusion about how to create and manage them. Hopefully this post will help.

Creating a run configuration

There are three ways to create a run configuration:

1. By hand (yuck!)
2. Clicking the Launch an Eclipse application link on the Overview tab of the Manifest Editor.
3. Clicking the Launch an Eclipse application link on the Overview tab of the Product Configuration Editor.

Let’s ignore creating a run configuration by hand. If you prefer that approach, more power to you! But most of us find it easier to generate run configurations by clicking the editor links mentioned above.

Where some confusion arises is that the two editors in question generate run configurations in different ways. Let’s look at each editor in turn.

Creating a run configuration with the Manifest Editor

It’s possible to generate a run configuration by clicking on the Launch an Eclipse application link in the Testing section of the Manifest Editor. We can also accomplish this by clicking the equivalent toolbar button. Both options are highlighted by the red squares in the image below.

But what really happens when you click the link or button? Behind the scenes, the following logic is performed:

1. The bundle associated with the manifest being edited is searched for an application or product extension. If one is found, that extension will be used when creating the run configuration.
2. The current run configurations are searched, and if an existing configuration exists for the particular application or product id, then that configuration will simply be reused.
3. If no matching run configuration is found, then a new one will be created. The available bundle list is created by traversing the dependency graph for the bundle associated with the manifest being edited. The arguments are taken from the current target platform for the workspace.

And what happens if you launch from a bundle that does not contain an application or product? Then the application will be set to Eclipse itself and a new instance of Eclipse will be launched with your bundles added into the mix.

This can be a source of great confusion for Eclipse RCP developers, and this is one reason that I discourage use of the Manifest Editor to create run configurations. On the other hand, it’s usually obvious if you’ve selected the wrong manifest. Your first tip that something is amiss will be the appearance of the Eclipse splash screen. If you’re not seeing your own splash screen, you’ve probably launched from the wrong manifest.

Creating a run configuration with the Product Configuration Editor

Because it’s very easy to create incorrect run configurations using the Manifest Editor, I usually suggest that developers use the Product Configuration Editor instead. The options look very similar in this editor (unfortunately at times they look too similar), and you can see them highlighted in red below.

But while the options look similar in both editors, there are slight differences in behavior. Specifically, the Product Configuration Editor uses the following logic:

1. First, a new run configuration is always generated. No attempt is made to search existing run configurations for a match, and if one already exists it will be overwritten. This can be particularly important if you’ve made manual changes to your run configurations.
2. The product id will obviously be taken from the product configuration file, as will the available bundles (Dependencies tab) and arguments (Launching tab). Note that arguments associated with your target platform are not used in this case.

What is the best approach?

As you’ve probably surmised, I suggest using the Product Configuration to create run configurations. Here are the two biggest reasons:

• It’s easier to make a mistake with the Manifest Editor by selecting a manifest in the wrong bundle.
• Using the bundle list generated by a product configuration ensures the same bundles will be built into your deployed application. When using the Manifest Editor, it’s very easy to get into a situation where your app works in the IDE, but not after it is built and deployed.

As an aside, it’s possible to generate your run configuration from the Product Configuration Editor and then run it later by clicking the Run button in the main toolbar or selecting it in the Run Configurations dialog. This will obviously not cause your existing configuration to get overwritten.

I choose not to do this because I prefer to treat my product configuration as the only real location for runtime properties. I’ll come back to this issue in a subsequent post, as this discussion has gone a bit long!

The PDE team has given RCP developers some great new features in Eclipse 3.5. It’s now much easier to create and manage target platforms for Eclipse RCP applications. In this post, I’ll outline one simple workflow that should work in most cases.

But first, if you’re interested in what a target platform is or why you might want to create one, check out these previous posts.

• Why create a target platform?
• RCP target platform tips

So now that you understand why we should create a target platform, what’s the best way to do it?

Create a target definition file

Eclipse target platforms can be created and selected directly in the Target Platform preferences page, but a better approach is to define your target platform using a target definition file. A target definition file outlines what should be included in your target platform and where the features and bundles can be located. More importantly, target definition files can be checked in to your version control repository and shared among the members of your team.

So how do we create one? You see here a sample RCP application that was generated with the Hello World template. Let’s add a target definition to this project.

Right-click on the project name and select New > Other. Then choose Plug-in Development > Target Definition in the wizard selection dialog.

The wizard page prompts you to select a file name, and I’m going to choose samplercp.target to match my project name. Remember, it’s a good idea to have a separate target platform for each project you work on.

Define your target platform

Now that we have a target definition file in our project, we can select what to include in our target platform. We do that by identifying one or more locations that may contain features or bundles. Eclipse 3.5 supports four types of locations (directories, installations, features, and software sites).

In this workflow, I’ll be using a software site which means that the features and bundles will be downloaded from a repository and stored locally under my workspace .metadata folder.

For an RCP application, we typically want to set our target platform to the Eclipse RCP SDK which is made up of two features:

• org.eclipse.rcp
• org.eclipse.rcp.source

Let’s add these features to our target platform. Start by clicking Add in the Target Definition Editor (this editor should have opened automatically after you created the target definition file). Then select Software Site on the Add Content dialog and click Next.

The next page of the wizard is where the real work is done. We’re going to specify a repository location where the Eclipse RCP SDK can be retrieved.

• First, select the Galileo repository from the Work with drop-down.
• Next, deselect the Group by Category checkbox. For some reason, the Eclipse RCP SDK does not appear anywhere in the category listing. You would think it would be included under the EclipseRT Target Platform Components category, but no such luck.
• Finally, place a check next to the Eclipse RCP SDK entry in the list and click Finish

As soon as you click finish, Eclipse PDE will start the process of downloading the RCP SDK to your machine. Your target definition file should look like this:

Activate your new target platform

The final step is to activate your target platform by clicking the Set as Target Platform link in the upper-right corner of the Target Definition Editor. Then you’re all set! And make sure to check in your target definition so everyone on your team can share the fruits of your hard work ;-)

What does the term application mean in the context of modular software development (and OSGi in particular). It seems to me that the concept of an application starts to break down. For instance, is an OSGi application just the set of bundles known to the framework?

Well, here’s my take on what a modular application might mean.

Going beyond the steady state

When an OSGi framework fires up, some bundles may be activated, others may not. Some activators may perform logic, others may not. But what arises from this activity? Is this the equivalent of launching an application? It can be, but its more often the case that the framework arrives at a steady state, waiting for an input that triggers some behavior.

This can be confusing when we start using OSGi because this doesn’t look like an application. What we need is an entry point. Just as throwing a rock into a pond causes waves to form, we need to launch a thread of execution that takes us beyond the steady state. So how do we accomplish this?

Eclipse applications

The Eclipse platform provides us with one answer in the form of an Eclipse application. An Eclipse application is defined through the org.eclipse.core.runtime.applications extension point and is represented by an IApplication instance at runtime. And this mechanism can easily be added to Equinox by installing some additional bundles.

This is how, for example, Eclipse RCP applications are launched in the context of an OSGi framework. But it’s interesting to note that one set of bundles may support multiple applications. So a good way to look at an application is that it is merely a specific entry point into the functionality provided by a community of bundles.

The OSGi Application Admin service

We can take the concept of an OSGi application one step further by utilizing the OSGi Application Admin service. This service recognizes the concept of an application in the abstract (specific providers can define what an application means in each case), and allows an application to provide an entry point that will launch a thread of execution.

Equinox, for instance, provides an application descriptor for Eclipse applications. This means that you can use the Application Admin service to start and stop Eclipse applications from the OSGi console. The available console commands are:

• apps – list currently available applications
• activeApps – list currently active applications
• startApp [app id] – start an application
• stopApp [app id] – stop an application

These commands can be used to launch most types of Eclipse applications, including those with an SWT user interface. Unfortunately, they cannot yet be used to launch Eclipse RCP applications because of the way in which singletons are used. This is scheduled to be fixed as part of the e4 work.

Possibilities

I think all of this is pretty exciting because it allows us to reimagine the relationship between applications, modules and running platforms (JVMs and OSGi frameworks). For example, imagine being able to deploy an Eclipse RCP application into a running OSGi-based ESB. The application would allow you to manipulate the ESB in container and it could then be undeployed when no longer needed. All of this could be done without restarting the ESB.

It’s going to be fascinating to see how of all this plays out in the next few years. The possibilities are endless!

It’s Friday afternoon and I’m in a contemplative mood. For some reason, I’ve been thinking about my first manager, who I wasn’t very fond of at the time. I’m sure I was a real pain in his backside as well, being a fresh-out-of-college know-it-all.

One of the things that drove me nuts about him was the way he mangled metaphors and sayings. He liked to tell me “never put the horse before the cart” and stuff like that. But one saying he used will always stick with me. He’d say:

Patrick, software is like a bowl full of jello. And our job is to get our arms around that bowl!

I remember thinking that I’d rather not get my arms around a bowl full of jello. What good would that do? It would still be a bowl full of jello, and I’ve never liked jello anyway. But what also struck me at the time was that this really is what software is like to people who don’t leverage information hiding. Spaghetti is almost too clean a metaphor (at least you can pull out some noodles if you want). Jello really captures the nasty, sticky grossness of badly encapsulated software.

Even though I didn’t like this manager at the time, he did inadvertently start me down the path to software modularity. Hopefully by focusing on modularity, we can stop dealing with bowls of jello and at least work with jello shots :-)

Note: The post below is actually incorrect, which is a good thing in my opinion. It is indeed possible to use the command framework to add the standard Eclipse IDE menu options. Rather than take down the post, which I think is unethical, please read the post and then the note at the end for clarification.

One of the many things that Eclipse RCP provides is a set of standard menu options that are used by the Eclipse IDE itself. These include standard menu options such as Exit, Save, Cut/Copy/Paste, but also workbench specific options such as Reset Perspective and Show Views.

In short, almost all of the menu options you see in the Eclipse IDE are available for use in your RCP applications. And I tell most teams starting out with Eclipse RCP to go through the Eclipse IDE menu and make a list of those options that make sense for their application.

So how can we add these menu options to our applications?

Using actions

Traditionally, Eclipse IDE menu options have been added as actions in the ActionBarAdvisor. The Eclipse actions can be referenced as constants in the ActionFactory class, and adding a menu option looks like this:

IAction saveAction = ActionFactory.SAVE.create(window);
fileMenu.add(saveAction)

Using commands

During the last few years, most Eclipse RCP developers have transitioned from actions to commands. Commands, and their associated handlers and menus, provide a clean separation between UI and non-UI concerns. As part of the transition to commands, Eclipse RCP now provides us with the Eclipse IDE menu options as a set of extensions defined in the org.eclipse.ui bundle.

The commands point to handlers that implement the behavior associated with menu options. We could, if we like, create org.eclipse.ui.menus extensions that refer directly to these commands. This would allow us to define our entire menu using declarative syntax.

Which approach should we use?

So the question is, should we choose the command-based approach? The answer (for Eclipse IDE menu options only) is no. Using the org.eclipse.ui.menus extension point to add Eclipse IDE menu options is problematic in that we lose access to look and feel attributes. Specifically, the ActionFactory constants provide us with the following menu attributes:

• label
• tooltip
• image (enabled and disabled)
• help context

Not only that, but the actions provide us with these values as externalized strings with support for internationalization. So while actions are really the old way of doing things, the ActionFactory/ActionBarAdvisor combo is still the preferred way of utilizing Eclipse IDE menu options.

When should I use commands?

Well you should definitely be using the command-based approach for your own menu options. Also the Eclipse IDE commands are still useful if you want to link your own menu options to them. You may want to reference the standard Eclipse IDE options in view menus, cheat sheets, dialogs, etc.

Finally, you should know that the actions produced by the ActionFactory are actually bridged to commands and handlers behind the scenes. This means that even though you are using actions to define the menu options, you can still provide your own handlers for them.

Clarification: What I missed when writing this post was that the Eclipse IDE commands contain localized text which will show up in your menu if you leave the menu label blank. Also, images will appear in the menu, and these are contributed via the org.eclipse.ui.commandImages extension point.

Thanks to Lars Vogel for the correction!

Clarification #2: Having looked into this further, it appears that some of the standard Eclipse IDE menu options require that the ActionFactory action be created and registered before the commands will work. You don’t actually need to use the actions to create the menu options in the ActionBarAdvisor, though. For more information on this, see this Bugzilla entry.

There aren’t many books available about the Eclipse Rich Client Platform. One reason for this, I think, is that it’s a difficult subject to cover effectively. Eclipse RCP is less a coherent framework than an aggregation of related technologies, and this can make it difficult to describe. As someone who has worked hard to craft clear Eclipse RCP training materials over the last few years, I sympathize with anyone who takes up the challenge.

And taking up this challenge is Vladimir Silva in his book Practical Eclipse Rich Client Platform Projects. I hadn’t heard much about this book, and only found about it when browsing the book table at last year’s EclipseCon. This summer I’ve finally found the time to read it and here is my review.

A good start

The first thing I like about the book is that it’s short. At a mere 335 pages, the book invites you to actually read it, not just treat it as reference material. I have a bias towards shorter technical books in general, as it shows a bit of self-discipline and thoughtfulness. The books produced by Pragmatic Programmers are a great example of this.

I also like the way the book starts, with a focus on OSGi. It’s essential that RCP developers learn from the start that OSGi and modularity are at the heart of the platform. Everything seems to click faster for developers when they understand some OSGi basics.

A strange mix

So far so good, but what is the rest of the book like? The word I’d use is odd. Any shorter technical book has to make tough choices about what to include, but the choices made by this author left me scratching my head a bit.

The first three chapters provide a pretty thin introduction to the structure of an RCP application. Topics covered include the workbench, editors, views, menus, commands, handlers and product branding. But all of these topics are covered extremely briefly and in my opinion do not add a lot to what can be found in the Eclipse help system.

After that, the book gets more interesting, but in an odd way. The author takes us on some deep dives into an eclectic mix of advanced topics (with the exception of a chapter on the help system). These topics include:

• Common Navigator Framework
• 2D graphics with GEF and ZEST
• 3D graphics for RCP with OpenGL
• BIRT
• Automatic updates

These topics are covered in various levels of detail. The chapter on OpenGL, for instance, is as long as all of the RCP chapters combined!

My initial reaction to this content is that if you’re interested in some of these topics, then this book is worth buying. There is very little published content on topics such as CNF and Zest. But in the end, I think these these topics are only tangentially related to Eclipse RCP itself.

Final thoughts

There are so few books on Eclipse RCP that any book at all is a welcome addition. And I applaud the author for covering some topics that have received so little attention in the past.

My overall recommendation is that if you’re looking for a solid introduction to Eclipse RCP, this book is not really for you. My suggestion would be to pick up Eclipse Plug-ins, which covers the core Eclipse RCP APIs much more thoroughly.

On the other hand, if you’re an Eclipse RCP developer interested in one or more of the topics covered in later chapters, definitely have a look.

My personal journey with the Eclipse Rich Client Platform began 6 years ago. I was starting work on a financial analysis application, and was looking for a cross-platform framework to build upon. Eclipse was my IDE, and I began to see some interesting Bugzilla entries that pointed me to what would become Eclipse RCP.

Like many, I was originally attracted to Eclipse RCP because it promised to shorten my development cycle. It gave me a workbench, perspectives, editors, views, wizards and much more. And you know what, it worked! I did develop an application that would have been impossible to create without such a framework.

But while working on that application and in my subsequent work on other projects, I’ve come to appreciate that Eclipse RCP is not a normal framework. Much of its power comes from its support for creating modular user interfaces. The ability to flexibly assemble and package user interfaces has opened up many possibilities for myself and my clients.

And I’m not talking about geeky development-type benefits here. Modularity allows us to create (or assemble) applications that are more targeted to the specific needs of users. In short, modularity makes software more useful. Modularity also allows us to approach software licensing and marketing in ways that were not possible before. In the end, modularity can result in a significant competitive advantage.

And now that I’ve finally come to see modular software development in this way, I’ve decided to make it the focus of my training and consulting practice. I’ve renamed my blog (and my company) Modular Mind. I’ll still be focusing on Eclipse RCP and OSGi training, but in the broader context of modular software development. I can’t wait to see what the next 6 years will bring. If they’re anything like the last 6 years, this is going to be a lot of fun!

Note: As part of my broader focus, I’ll be writing posts which will no longer be aggregated on Planet Eclipse. If you’d be interested in reading these posts, you may want to subscribe to my feed directly.

Most applications require configuration settings. Applications are often deployed in multiple environments (dev, test, prod, etc) and these environments often require different runtime configurations. Also, it’s useful to be able to update an application configuration without a restart. If you find yourself with requirements like these for your Eclipse RCP application, you should really check out the OSGi Configuration Admin service.

Specifically, the Configuration Admin service allows you to:

• Configure the OSGi services that you provide as part of your application.
• Configure OSGi services that others provide. An example of this is the ability to configure the Pax Logging service, which I’ll explore in a second post.
• Configure Spring beans when using Spring DM. Here is a good reference for using Config Admin with Spring DM.

If you’d like to learn more about the Configuration Admin service, check out this post or the OSGi Compendium specification. In this post I’m going to describe how to set up the Configuration Admin service in an RCP application using Pax ConfMan.

What is Pax ConfMan?

The Configuration Admin service doesn’t specify any particular way of storing and accessing properties. Each implementation can do what it likes, and Pax ConfMan has opted for the simplest approach – properties files.

Setting up the target platform

The first step in getting Pax ConfMan working in your RCP application is to add the required bundles to your target platform. Here is the complete list of bundles which need to be added:

• org.eclipse.equinox.cm (download)
• org.eclipse.osgi.services (download)
• org.ops4j.pax.confman.pax-confman-propsloader (download)
• org.ops4j.pax.logging.pax-logging-api (download)
• org.ops4j.pax.logging.pax-logging-service (download)

Also make sure to add these bundles to your product configuration and run configuration so they will be included in builds and at runtime.

Forcing Pax ConfMan to start

If you run your RCP application at this point and examine the running bundles in an OSGi console, you’ll notice that the bundles added above are not started. To make the service available at runtime, we need to force them to start using the Configuration page (new in Galileo) of the Product Configuration Editor.

This page allows us to specify that specific bundles should be automatically started when the application is launched. Note that adding bundles to this page currently wipes out necessary RCP bundle settings. After adding these back in, your config page should look like this:

Now if you run your RCP application, you should see Pax ConfMan logging output to your console. These logs will tell you that the configuration folder cannot be found. So on to the next step!

Adding a configuration folder

Pax ConfMan allows you to configure your OSGi application using standard Java properties files, so we need to create a directory to hold these files. To get started, create a folder called confadmin in one of plug-ins that is part of your RCP application. You can call this folder anything you like, and the ConfMan default is configurations. I think confadmin is a better name in that it distinguishes it from the configuration folder used by the OSGi framework.

Inside the confadmin folder, create two sub-folders called services and factories. These folder names are required.

Finally, you need to tell Pax ConfMan where your folder is located, and this is done using a Java system property called bundles.configuration.location.

When running inside the Eclipse IDE, the simplest way to do this is to add an argument to your run configuration. Mine looks like this:

Now when you run the application you should see ConfMan messages indicating that your configuration folder has been located. Of course we haven’t added any properties files yet, but the wiring is all in place.

How to handle deployment

There are a variety of ways to handle configuration files in a deployed RCP application:

• Place your configuration files in a separate bundle and deploy that bundle as a folder instead of a jar file.
• Add your configuration folder to the install directory by utilizing the root property in the build.properties file for a feature.
• Use an installer script to copy the configuration files into another directory on a users machine.

No matter which option you choose, you’ll need to provide a bundles.configuration.location VM argument that points to the configuration directory.

What’s next?

Well you can now start to configure your own OSGi services using Pax ConfMan. In my next post I’ll show how to use ConfMan to configure Pax Logging in an RCP application.

It’s not every day that an Eclipse Rich Client Platform application is covered in the NY Times. In fact, I can’t remember it ever occurring before.

But yesterday Marketcetera, a developer of RCP-based open-source trading software, was featured in the Bits Blog of the NY Times. Of course there’s no mention of RCP itself, but it’s nice to know that those building tools with this framework are having some success.

Yesterday also marked the 1.0 release of this product, so congratulations to everyone at Marketcetera! I’m sure I speak for everyone in the RCP community when I say we wish you all the best.