What’s the problem?

By default, product configurations are hard-wired to specific feature versions. And if you decide to upgrade to a new version of the org.eclipse.rcp feature, for example, then your product configuration will break. You won’t be able to create valid run configurations based on your product and your builds will fail as well.

Luckily, we now get feedback in the Product Configuration Editor informing us that something is amiss.

So what can we do about this? Well one approach is to re-wire your product to the new version of the feature. You can do this by deleting and re-adding the feature, or you can also click the Properties button and modify the feature version manually. But this is a brittle approach, as you need to remember to update your configuration every time a feature version changes.

A better way

It’s now possible to decouple products from feature versions by replacing the feature version numbers with 0.0.0. In the future, a blank feature version will also be interpreted as 0.0.0 but as of Eclipse 3.5.1 the number must be added.

Also, there is a currently a defect in the Product Configuration Editor that results in a feature version entry of 0.0.0 being ignored. Of course, this won’t matter once blank versions are interpreted correctly, but for now it’s a problem. The solution is to open the product configuration file in a text or XML editor and change it manually.

The good news is that you only need to do this once. Your product will now accept the feature versions you supply in your target platform without complaint. Of course if you want to maintain the wiring between products and feature versions, by all means do that. But it’s nice to know we can decouple these pieces if we wish.

Because of this, I’ve decided to write a set of posts discussing some of the CNF tips that I’ve found valuable over the years. And I think the best place to start is knowing when to use it. The Common Navigator Framework is complicated because it is trying to solve a complicated problem. It will only make your life easier if you’re using it for the purpose it’s designed for. So what is that purpose?

Modularity and extensibility

Well first, CNF was not created to make the development of navigators easier. If you have fairly normal navigator requirements in your application, CNF is probably not for you and you’ll save yourself a lot of headaches by omitting it.

Instead, CNF is designed to create navigators that support modularity and extensibility. With CNF, various OSGi bundles in your RCP application can contribute navigator content at runtime.

CNF allows your bundles to declaratively contribute content to a navigator, and this is not a simple exercise. As users of CNF, we need to wire together navigators and their content in sophisticated parent/child relationships, and then overlay on top of this structure a set of actions, filters, drag/drop handlers, etc.

Does it have to be so hard?

Some of you might be thinking modularity is supposed to help us to simplify our applications. Why does this stuff have to be so darned hard? Well this is true to a point. Modularity allows us to take information hiding to an entirely new level and to the extent that we can hide complexity, our applications become simpler.

But when dealing with modular UIs in particular, the difficultly arises when we work with the joints or pivot-points between modules. In these specific cases, there is always complexity because we have to define in detail how our modules relate to each other.

So the next time you’re struggling with a complex CNF extension point, ask yourself whether you really need this functionality. If you do, then embrace CNF for what it is: a complex solution to a complex problem.

The good news is that choosing a technical trainer is like choosing any other service provider. A little due diligence up front can greatly increase your chances of having a good experience. Being a trainer myself, I was curious to see if there were any good articles I could recommend to guide potential clients through this process. Unfortunately my searches led me to sites for either personal trainers or dog trainers. Definitely not what I was looking for!

So here are my thoughts on choosing a technical trainer. I should say up front that I have an ulterior motive in writing this article. I want to see the quality of technical training improve, and the best way for that to happen is to demand more of trainers. If we all exercise more due diligence in selecting technical trainers, training providers will be forced to improve their offerings.

Creating the short-list

The first step in a trainer search is obviously to create a list of potential candidates. Most likely this will involve an internet search that will result in a short-list of trainers. So what should you be looking for when browsing websites at this stage of the process?

• Does the site have a professional look and feel? This is kind of a no-brainer in any search, but its especially important for trainers. At its core, training is about organizing and communicating information. If a trainer’s website is confusing, hard to navigate, or just plain ugly, it’s likely that the training materials will be as well.
• Does the site reflect a core competency in the area in which you need training? If a trainer provides courses in everything from C++ to Microsoft Word, you might want to look somewhere else. Oftentimes these one-stop-shops are really just brokers who will try to find an actual trainer once you’ve indicated some interest. It may take a bit more effort to make a direct connection with a trainer, but you’ll probably have a better experience if you do.
• Does the site contain articles or blog posts relevant to the training area? Many do not and I wouldn’t exclude a trainer for that reason. But if articles do exist, they can be a good window into the trainer’s mind. If articles do exist, examine them for clarity and thoughtful presentation. This can be especially useful when you’re considering hiring a “guru” to do training. While it’s always tempting to hire an acknowledged expert in the field, some gurus make good trainers and some do not.

Getting to know the trainers – asking the right questions

Once you have a short list of trainers at hand, it’s time to get to know each of them. What should you be looking for? Well, the value of the training you receive will depend on the quality of the trainer and the training materials. You should try to find out as much as possible about both.

First, the trainer. You may have noticed that I’ve been consistently referring to trainers as opposed to training providers. It’s important to understand that even if you’re talking to a large training provider, what you are really selecting is a specific trainer. Ask up front who the trainer will be, and if that does not go over well you may want to look elsewhere.

If on the other hand you are presented with a specific trainer, ask if you can interview this person. If you have a technical expert available, you may want to have them sit in on the interview to assess the trainer’s knowledge. In any case, though, you should be looking for communication skills. Does the trainer speak simply and clearly? Is he or she eager to explain things in a way you can understand? Would you want to listen to this person talk for days at a time?

And the training materials? These are critical to the success of the training course, and you should ask for samples that you can evaluate – some slides and a few pages of the manual and labs if relevant. Examine these samples for clarity and visual interest. Are they filled with text that the trainer will probably read verbatim or do they present visually interesting explanations? Text-heavy slides can lead very quickly to student fatigue and make the training less effective. Are the text and images presented in a professional manner and would they be easy to look at when projected? Again, would you want to look at these slides for a few days straight?

You’ll obviously receive other information about the training course, such as pricing and availability. But one thing you should always request is a list of recent references. This is such an important topic, I’ve saved if for last.

Calling the references

References should be an important part of your selection process. When you are provided with a list of references, call them. Please, please call them. There is no better way to get an accurate picture of what a trainer is really like.

I’ve found that many people do not call references either because they don’t want to impose or they think the process does not provide good information. If you feel this way, I urge you to reconsider. Most clients are happy to talk and the process can be extremely valuable if you approach it correctly.

The first suggestion I’d make is to talk to people who were actually in the course. Many references you receive will be for a manager who arranged the training, and that’s fine. These references can provide great high-level information about the course, students reactions, and the success of subsequent projects. But it’s a good idea to ask for a few student references as well. There’s no substitute for talking to someone who was in the room.

Second, make sure that the references you’re talking to were taught by the specific instructor that will be teaching your students. Talking to references who had other trainers is of little value.

Finally, go beyond the “were you happy with the trainer” questions. A good approach to references is to get them talking about their experiences in very concrete ways. The best way to go about this is to ask specific questions. Here are some examples:

• Do you think the course materials were well designed and easy to follow?
• Were there students in the course who felt things were moving too fast or too slow?
• Did the trainer make any changes to the course to better meet your needs?
• Were there labs? If so, were they helpful and did most of the students finish them successfully? One thing to look for here is if the trainer fell back to doing the labs on behalf of the students, while everyone simply looked on.
• Was the trainer able to go beyond the material to talk about advanced topics?
• If the trainer did not have the answer to a question, did he or she promptly follow up with the answer?
• Has the trainer been responsive to follow up questions after the course completed?

It’s all about the students

In the end, the quality of a training course can only be measured by the effect it has on students’ life and work. When selecting a technical trainer, it’s important to always think about the needs of the students and to do whatever it takes to make sure they will benefit from the training.

Expect more from your technical trainers and I think you’ll be pleasantly surprised with the results.

What are launch arguments?

Launch arguments are arguments that are added to the command line when you execute your application. These arguments come in two flavors:

• Program arguments – Arguments that are Eclipse-specific. For example, the -clean argument will clear the configuration area on startup.
• VM arguments – Arguments that make sense to the Java VM. For example, the -Xmx argument allows you to set the maximum heap size for the VM.

Both of these argument types can be set on the Arguments tab in the Run Configurations dialog.

Launch arguments and the target platform

We oftentimes want to apply the same launch arguments to all of our run configurations, and one way to handle that is to specify them on your target platform. On the Target Platform preference page there is a section where you can add whatever arguments you wish.

The arguments associated with a target platform will be added to run configurations generated from the Manifest Editor. They will not be added to configurations generated by the Product Configuration Editor. Also, because the Manifest Editor link does not regenerate a configuration each time, you will need to explicitly delete a configuration if you want to recreate it using new target platform arguments.

Launch arguments and products

A second way to manage arguments is to add them using the Launching tab of the Product Configuration Editor.

When you add arguments in this way, two things will happen:

1. The arguments will be added to your run configurations if you launch using the link in the Product Configuration Editor. Because this link regenerates the run configuration each time, consistent use of the link guarantees that your configuration is in synch with your product definition.
2. The arguments will also be added to your deployed application in the form of an INI file. This is a nice feature, but it means that you need to be careful when adding arguments that are only useful during development. For example, you may want to use -clean to clear the configuration area when you’re developing, but you probably do not want to ship this argument to your customers.

Launch arguments best practices

My approach is to add arguments using the Product Configuration Editor and to always launch my applications using the link in that editor. This guarantees that my run configurations are always in synch with my product definition. I also take care to not add arguments that would be detrimental to a deployed application. Some, such as -consoleLog, I consider harmless in a deployed app and I just leave those in.

If for some reason I absolutely have to add an argument that should not be deployed, I usually clean it out of the INI file during the build process. It’s pretty rare for me to have to do this, though.

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!

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 ;-)

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.

Fortunately, with Java Media Components things seem to be moving in the right direction. JMC is an API that allows you to play media files using the video functionality of the underlying operating system (there is work being done to provide cross-platform codecs along with the API, but it’s unclear how extensive this will be). JMC is distributed as part of the JavaFX platform, but it can function independently inside of a regular Swing application.

Using this recent article as a guide, I managed to create an Eclipse plug-in that contributes a very rudimentary video player view to Eclipse or any other RCP application. If you’d like to try it yourself, click here for the source code (exported project). Note that the current code only works on Windows.

Above you can see a Flash video of Wipeout playing inside of my Eclipse IDE. Wipeout is my 5-year old daughter’s favorite show (if people are falling down, she’s laughing), so after 20 years as a software developer I’ve finally written some code she’d be interested in!

One thing to note is that JMC relies on the codecs installed on your machine. There have been some complaints that JMC is not finding or utilizing the codecs most people have installed, and hopefully this situation will improve. If you find that you’re getting MediaUnsupportedException errors when opening files, you may want to install a codec pack. The CCCP pack seems to work for most people.

You might think that this view would appear on its own when requested through the UI, and in my opinion this is the way things should be (this has been discussed in past Bugzilla entries). For instance, your users may see a job running in the status bar of your RCP application, like this:

When the user clicks on the conveyor belt icon, they would expect to see a detailed progress view allowing them to cancel the job, like this:

So how do you get this working? The answer is not what you might think. Normally, you would add a view by finding the view class and creating a new view extension. But for the Progress View, things are a bit different. The ProgressView class itself is internal and is not intended to be referenced directly. It is exposed, however, through an extension factory. The XML to create the view extension looks like this:

   <extension
         point="org.eclipse.ui.views">
      <view
            name="Progress View"
            icon="icons/pview.gif"
            category="org.eclipse.ui"
            class="org.eclipse.ui.ExtensionFactory:progressView"
            id="org.eclipse.ui.views.ProgressView">
      </view>
   </extension>

The last piece we need to make this work is the view icon, which can be found in the org.eclipse.ui.ide plug-in (not part of the RCP SDK). The actual file in this plug-in is icons/full/eview16/pview.gif. You’ll need to copy this icon into your own plug-in and reference it in the view extension.

So while not extremely straightforward, it’s not that difficult either. Interestingly, there are a variety of other things you can add to your application through the same extension factory mechanism. If you’d like to find out more, check out the constants in the ExtensionFactory class.

But it’s almost always better to do things declaratively through extension points, the main reason being that doing so allows you leverage the power of RCP as a modular user interface framework. To illustrate this, let’s look at our options for laying out perspectives.

Programmatic Layout = Centralized / Hard Coded

Here is the simplest code needed to add a view to a perspective programmatically. To do so, we implement the IPerspectiveFactory interface and add a view using its string id.

public class MyPerspectiveFactory implements IPerspectiveFactory {

	public void createInitialLayout(IPageLayout layout) {
		layout.addView(MyView.ID, IPageLayout.BOTTOM, 0.5f, layout.getEditorArea());
	}

}

The problem here is that we’ve coupled our perspective to the view being added. This view may exist in the same plug-in as the perspective, but often it does not. If the view is in a different plug-in, we have to declare a dependency on that plug-in just to add the view. It’s possible to reduce the coupling somewhat by replacing MyView.ID with the actual string id itself, but hidden dependencies based on string equivalency are arguably even more smelly.

In the end, a programmatic perspective layout results in a hard-coded and centralized architecture looking like this.

Declarative Layout = Decentralized / Modular

The declarative approach based on extension points resolves these issues. To layout a perspective declaratively we extend the org.eclipse.ui.perspectiveExtensions extension point.

   <extension
         point="org.eclipse.ui.perspectiveExtensions">
      <perspectiveExtension
            targetID="com.mycompany.myperspective">
         <view
               id="com.mycompany.myview"
               minimized="false"
               ratio="0.5"
               relationship="left"
               relative="org.eclipse.ui.editorss">
         </view>
      </perspectiveExtension>
   </extension>

Using this approach, each plug-in adds the views that it knows about, resulting in a decentralized architecture where the plug-ins containing the views are now in control.

Note that we have not eliminated all coupling, as the perspective extensions still need to refer to the perspective by its string id, but this is not as bad as it sounds. Perspectives are much more static than views – you typically define them and make few changes afterwards. Views, on the other hand are often moved from one plug-in to another or have their purpose (and potentially their id) redefined. Decentralizing control allows you to make these kinds of changes without breaking the perspective layout.

Conclusion

Adding UI elements declaratively is definitely the way to go. It gives you much more flexibility (e.g. you can add views to perspectives you didn’t create) and also allows you to leverage the modular nature of the framework.

Sure, there will always be cases where a declarative approach cannot be taken, particularly when some part of an API is not yet surfaced in the related extension point. But in the absence of such a need, I urge RCP developers to always turn first to the extension point mechanisms and fall back to programmatic approaches as a last resort. As your application evolves over time, you’ll really come to enjoy the flexibility and increased reusability that a declarative approach makes possible.