Pax Logging to the rescue

I’m happy to say that RCP developers now have another choice - Pax Logging. There are a few great things about this library:

• Installation is easy. I’ll describe this in a bit.
• Configuration files can be placed in regular folders, either inside of an application bundle or anywhere on a users machine.
• Many logging APIs are supported, including Log4J, Commons Logging, JDK Logging, SLF4J and more. This means that legacy and third-party code can run as-is no matter what logging API they use.

Logging configuration with Pax ConfMan

Because Pax Logging requires the OSGi Configuration Admin service to work, your first step is to install this service in the form of Pax ConfMan. In my last blog post I provided detailed instructions on how to do this.

Adding configuration settings

The good news is that once you install Pax ConfMan, you’re almost done! Pax ConfMan requires the Pax Logging bundles in order to work, so we only have a few minor steps left.

The first is to add a logging configuration file. When using the OSGi Configuration Admin service, services are identified using a persistent identifier, or PID. Developers can choose the PIDs for their own services, and an implementation of the Config Admin uses these PIDs to inject properties into services.

Pax ConfMan does this by requiring that a properties file be named based on the PID of the service it is going to configure. For example, the Pax Logging PID is org.ops4j.pax.logging and so the properties file for this service will be called org.ops4j.pax.logging.properties.

If you created the folder structure suggested in the Pax ConfMan setup, simply create a file called org.ops4j.pax.logging.properties in the confadmin/services directory. You can now place whatever logging configuration you like into this file. For instance, here’s what I have for my simple test project:

log4j.rootLogger=DEBUG, A1

log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n

log4j.logger.com.rcpquickstart.logtest=DEBUG


Forcing Pax Logging to start

Just as we did with Pax ConfMan, its necessary to force Pax Logging to start up when our application is launched. To do this, we simply need add the org.ops4j.pax.logging.pax-logging-service bundle to the Configuration page of the Product Configuration Editor and set it’s Auto-Start property to true. If you’ve followed the instructions for installing Pax ConfMan, your complete list should look like this:

Fire it up

That’s all there is to it. Start up your RCP application and you should see log messages appear in your console.

Happy logging!

I’ve taken that list and pared it down a bit (the Ant plug-ins are not necessary), and created a simple working example of an RCP app with integrated help. The example wraps the Eclipse help system in a feature called org.eclipse.help, which you can reuse in your own applications. There is some talk about making the help system an official feature in Eclipse 3.4, but for now the included feature should get you what you need. You’ll of course need to add the required plug-ins to your target platform, and if you’re curious, this is the final list:  

To get started, just download the example projects and import them into your workspace.

In my opinion, the best way to work with PDE Build is to get a very simple build running in your environment. Then make small, incremental additions, verifying the integrity of the process after each change. So the immediate problem for a team becomes: How do I get that first build running?

To help with this, I’ve put together a simple feature-based RCP product build. Just download and import the sample projects. If you follow the instructions in the included readme.txt file, you should have a build running fairly quickly. Before you know it, you’ll be seeing that always elusive BUILD SUCCESSFUL message flash across your screen!

Note: If you want to run this sample build using Eclipse 3.2, you’ll need to work around a PDE Build defect. For instructions on how to do this, check out the “Problems parsing feature file in a product build” section on the PDE Build wiki page.

Update – October 6, 2009: The sample projects have now been updated to work with Eclipse 3.5.1

There are quite a few steps, but it’s not as bad as it looks. So let’s get started!

• Before creating a navigator, it’s first necessary to have something to place it in. If you don’t have an existing RCP application to work with, create a new one using the “Hello RCP” template. Also, if you have a custom target platform, you’ll need to add the org.eclipse.ui.navigator plug-in to that target. Finally, you’ll need to add the navigator plug-in as a dependency in the appropriate manifest.

• Now that the preparations are out of the way, we can create the navigator itself. Because CNF navigators are also regular views, the first step is to create an org.eclipse.ui.views extension. Enter in an appropriate id and name, and then enter a new class name in the class field. Note that this is where we diverge from standard CNF usage. Normally we would simply enter the org.eclipse.ui.navigator.CommonNavigator class in this field. To learn why we are not, check out my previous post on the subject.

• Click on the class field label to launch the New Java Class wizard. Change the superclass to org.eclipse.ui.navigator.CommonNavigator and click Finish. We now have our main navigator class, and we’ll return to it a little later. You can now also add your view to a perspective either programmatically or through a perspective extension. At this point, you should be able to run your application and see an empty navigator appear.

• Now for some content. Create a NavigatorRoot class that will serve as the root node in your navigator. Note that this element will not appear in the navigator, the children of the root node will be the first to appear. The class representing the navigator root must be an IAdaptable, and the simplest way to accomplish this is to have your NavigatorRoot extend the PlatformObject class. Also create another simple bean called ParentBean that has a name attribute. Finally, add a getParentBeans method to your NavigatorRoot class and have that method return a set of populated ParentBean instances.

• The navigator root can now be added to the navigator class we created above. In that class, override the getInitialInput method and simply return a new instance of NavigatorRoot. Note that in a real-world implementation, the navigator root would probably be a singleton or returned by a factory class. Also note that these few lines of code are all that are required in the navigator subclass. While subclassing the CNF navigator is not ideal, this approach is far from risky.

• The next step is to declare an org.eclipse.ui.navigator.navigatorContent extension. This extension point is used to define many navigator elements, including content (of course), filters and actions. It’s important to understand that this extension point defines content in a navigator independent way. You will later need to bind this content to a specific navigator to get the content to appear. So create this extension and add a navigatorContent element below it. Choose an appropriate id and name, and then enter class names for the contentProvider and labelProvider fields.

• Click on the contentProvider and labelProvider field labels to create the required providers. The content provider should take in a NavigatorRoot as input and return an array of ParentBean instances as children. The label provider should simply return the name of the ParentBean as the display text.

• We now need to specify what will cause our content to appear. The simplest way to do this is to specify what type of parent element should trigger our content and cause our content/label providers to be called. In our example, we’ll add a triggerPoints element below the navigatorContent element. Under triggerPoints, we’ll add an instanceof element and then enter your NavigatorRoot class in the value field. This will cause your content to be added whenever a NavigatorRoot instance is encountered in the tree.

• The final step (we’re almost there!) is to bind the content to the navigator. To do that, we need to declare an org.eclipse.ui.navigator.viewer extension. This extension point registers our view as a navigator and allows us to bind different types of content to it. Create the extension and first add a viewer element to it. Enter the id of your view in the viewerId field. Now add a viewerContentBinding element below the extension. This element is what actually adds our content into the navigator. Again, enter your view id into the viewerId field. Add an includes element below the viewerContentBinding and then a contentExtension element below that. Finally, in the pattern field of the contentExtension element, enter the id of your navigator content.

You should now be able to run your application and see content appear in the navigator!

As you can see, even the simplest CNF example requires a fair number of steps to get working. It’s also rare for the navigator to appear correctly on the first try, and it can be extremely frustrating to debug the CNF when things go wrong. So much of the CNF is wired using extension points that any small typo can cause you a lot of grief. For that reason, I recommend that when working with the CNF you make small, incremental changes and verify functionality after each change.

Because it can be a real pain to get all the linkages working the first time, I’ve created some sample code (Eclipse 3.2, Eclipse 3.3) that will get you up to speed more quickly. Good luck!