TechJava » TechJava – Articles tagged by rcp

Launching Eclipse RCP via Java Web Start

Simon Zambrovski — Wed, 03 Feb 2010 16:32:15 +0000

The Eclipse RCP became a prominent platform for building client software. One of the delivery mechanisms supported by Eclipse RCP is Sun’s Java Web Start (JWS). Since Galileo Edition some changes has been introduced in the platform. This article provides some hints for creation of the RCP delivered by Java Web Start.

Packaging

In order to package the RCP I suggest to use feature-based products as described in a previous article. Following it, you should have a top-level plug-in (also refered as product-defining plug-in) and top-level feature, which is called “wrap”-feature in the context of the Java Web Start.

Exporting the product

Before you start with Java Web Start (JWS), export the product and make sure it starts as a standalone application. In doing so, you have to ensure that your references to the plug-ins are correct. One of the way of doing it is to hit the Validate button in the top left of the product editor. If the validation is successful, try to export the product. The PDE builder will run and create a distribution. The errors of the compiler/builder/assembler, if any, are reported to files zipped to the logs.zip file in the distribution directory. A prominent error is

Compliance level '1.3' is incompatible with source level '1.6'. A compliance level '1.6' or better is required.

Which actually means that the plug-in classes has not been compiled at all. In order to avoid this error make sure to set the following properties in the build.properties file of the corresponding plug-in:

javacSource=1.3
javacTarget=1.3

Exporting the wrap-feature

After a successful export of the product, just export the top-level feature (the wrap-feature). Make sure to provide the signing information, since JWS requires all resources to be signed. If you are aiming to deliver for different platforms, make sure to define a target platform (Window > Preferences > Plug-in Development > Target Platform) which contains a Delta Pack. A Delta Pack is a set of plug-ins which can be downloaded separately on the Eclipse Homepage. Also, don’t forget to switch over to the Java Web Start tab of the Feature Export Wizard, activate the checkbox “Create JNLP manifest for the JAR archives” and specify the site URL where the resulting JNLP will be located. Make sure all your features has the provider attribute set, since it is used as the “vendor” inside of the JNLP file, which is a mandatory attribute.

Creating the main JNLP

The PDE build will run and create a distribution in the specified directory. Along with the exported JARs in features and plug-ins, the packaging script will generate the JNLP descriptors for every feature. Still, the main JNLP file required for launching the application is missing and has to be provided separately. Here is, how it looks like:



    
        application titel
        provider
        
    

    
        
    

    
	-product
	de.techjava.app.webstart.productid
	-application
	de.techjava.app.webstart.appid

Important is to specify both, the product id and the applciation id, otherwise you will see the “Application id not found” exception. Of course you can specify additional options as command-line arguments of the launcher itself. I found it useful to be able to let the OSGi running and then connect to it and query for loaded bundles. You can do it by adding the following arguments:

	-console
	1234
	-noExit

This will allow to connect via telnet with running OSGi, even after the application finishes.
This is basically it.

Eclipse CNF: Navigator Content Extensions

Simon Zambrovski — Mon, 17 Aug 2009 20:55:11 +0000

Abstract

After providing the basic example of how the Eclipse Common Navigator Framework (CNF) can be used to display custom content, this article focuses on the main feature of the CNF – the contribution of content to the same navigator by several independent plug-ins. First of all, I will explain some minor changes introduced to the CNF in the Gallileo Edition, then I will focus on the content itself and finally provide an overview of how the action contributions can be provided. In the end of the post, some ideas on control of dynamic content are explained.

Gallileo Changes

There are two noticeable changes in the CNF that have been added with Eclipse Galileo. The return type of the method CommonNavigator#getInitialInput() has been changed to Object (which is important for the RCP usage of the CNF) and the call of the method org.eclipse.ui.internal.ide.model.WorkbenchAdapterBuilder#registerAdapters() has been replaced by the org.eclipse.ui.ide.IDE.registerAdapters(); which should be executed in the initialize method of the ApplicationWorkbenchAdvisor of your RCP if you are using resources with the CNF.

public class CommonNavigator ...
{
  /**
   * Used to provide the initial input for the {@link CommonViewer}.
   * By default getSite().getPage().getInput() is used.
   * Subclass this to return your desired input.
   * @return The initial input for the viewer.
   * Defaults to getSite().getPage().getInput()
   * @since 3.4
   */
  protected Object getInitialInput() {...}
}

Content contribution

The main advantage of the use of the CNF over a simple tree view is the ability to contribute content to the view from several plug-ins. Thus, the plug-in that contains the view does not depend on the contributing plug-ins. If you are not familiar with the CNF, please review the previous post, since the example provided there will be extended. The data model used previously will be extended by an additional layer: along with parents and children, the pets are introduced. Let’s assume that pets are owned by children.

/**
 * Represents a pet
 * @author Simon Zambrovski
 */
public class Pet
{
    private String name;
    private Child owner;

    public Pet(String name, Child owner)
    {
        super();
        this.name = name;
        this.owner = owner;
    }
    ...
    // getter and setter
}

First of all create a new plug-in project called de.techjava.rcp.cnf.subcontent, add a plug-in dependency to the de.techjava.rcp.cnf and to the org.eclipse.ui.navigator. Then add two extensions org.eclipse.ui.navigator.navigatorContent and org.eclipse.ui.navigator.viewer. The first extension defines the new Navigator Content Extension (NCE) and the second one is used to bind it to the existing viewer.

The Sub Content is defined following the same scheme as the content in the previous article of this series. Its contentProvider and labelProvider attributes point to the corresponding classes. The label provider implementation is straight forward. The content provider has to be able to return a list of children, if the instance of the Child-class is selected in the Navigator. The enablement is defined in this way respectively. An important thing to understand at this point is that the CNF will join contributions of all NCEs triggered on the element selection. This means, that even if the NCE of the first plug-in does not provide any children for the Child element, there will be children contributed by the second plug-in’s content provider. Here is the example content provider, which returns the number of pets depending on the last digit in a child’s name:

public class CNFSubContentProvider implements ITreeContentProvider
{
    ...
    public Object[] getChildren(Object parentElement)
    {
        if (parentElement instanceof Child
                && !(parentElement instanceof Parent))
        {
            Child child = ((Child) parentElement);
            char lastDigit = child.getName().charAt(child.getName().length() - 1);
            if (Character.isDigit(lastDigit))
            {
                int petCount = Integer.parseInt(String.valueOf(lastDigit));
                Pet[] pets = new Pet[petCount];
                for (int i = 0; i > petCount; i++)
                {
                    pets[i] = new Pet(child.getName() + "'s pet " + (i + 1), child);
                }
                return pets;
            }
            return EMPTY_ARRAY;
        } else
        {
            return EMPTY_ARRAY;
        }
    }
    ...
}

After this trivial configuration and the inclusion of the new plug-in into the example product, the resulting Navigator should show pets as sub-elements of the child-elements.

Shared commands

If the Navigator displays content from several plug-ins, the contributed commands should be handled carefully. The commands (contributed to the pop-up menu shown upon right-click on the corresponding item) should appear only on items they belong to. In order to achieve this, let us first look at the standard way of the command contribution. The CNF developer is strongly recommend to use the declarative contribution techniques instead of the Action Contribution Provider. For this purpose, the extension point org.eclipse.ui.navigator.viewer allows to contribute a popupMenu element as a child element of the viewer. The pop-up menu element defines the structure (in terms of separators) of the pop-up menu. There is a standard pop-up menu structure defined, which is default if a user-specific definition is ommited. In the example, the user-specific pop-up menu is defined:

Using the Eclipse Command Framework, the commands can be contributed to the defined pop-up menu in the following way. Using the org.eclipse.ui.menus extension point one or several menuContribution elements can be defined. Each menu contribution defines a set of commands, controls, menus, tool bars or dynamic contributions (or any combination) which are added to a specific separator addressed in a special way (see Command Framework Documentation). In this example the set of commands is contributed:

Please note that the commandId must point to an existing command, which is either user-defined, or defined by the Eclipse platform. A command is an abstraction of a user command which is referenced from the User Interface on one hand and has assigned handlers (which execute the command) on the other hand. The representation of the command is shown in the UI only if a handler is assigned to it. The idea of using shared commands is to have multiple handlers for the same command, which are activated depending on the selected element.

In order to enable and disable handlers in a declarative way, the Eclipse Core Expressions are used. Core expressions can be written in the enabledWhen and activeWhen child elements of the handler definition. The core expressions can also be defined and referenced externally using the org.eclipse.core.expressions.definitions extension point. Here is an example definition of the handler assigned to the Rename command:

The handler is enabled and active if the expression de.techjava.rcp.cnf.elementSelected is triggered. The definition of the expression is as follows. It defines the with-scope on the current selection, iterates over the elements and applies the instance of operator on the elements using the OR-conjunction. In doing so, the expression will trigger if among the currently selected elements is at least one Child element.

In order to use the same action (the Rename item of the pop-up menu) in the Pet plug-in, the handler enabled on the Pet element has to be provided. The code is analogous to the code before:

This should enable the Rename action on the Pet elements, too.

Dynamic content change

Finally, the last topic, which is covered in this article is the control of which content is shown in the Common Navigator. The developer can define the initial behaviour by setting the activeByDefault attribute of the NavigatorContent element. The user can customize the visible NCEs in the special dialog:

Of course there is a way to change the content shown in the Common Navigator at run-time. The following section describes how this can be done.

Responsible for loading the NCEs is the NavigatorContentService, which can be retrieved from the running Navigator instance. Using it is straight forward.

    /**
     * Sets the status of a NCE of the current viewer if any
     */
    public static void setToolboxNCEActive(final String extensionId, final boolean active)
    {
        CommonNavigator instance = findCommonNavigator(CNFNavigator.VIEW_ID);
        if (instance != null)
        {
            INavigatorContentService contentService = instance.getNavigatorContentService();
            boolean isActive = contentService.getActivationService().isNavigatorExtensionActive(extensionId);
            if (active && !isActive)
            {
                contentService.getActivationService().activateExtensions(new String[] { extensionId }, false);
            } else if (!active && isActive)
            {
                contentService.getActivationService().deactivateExtensions(new String[] { extensionId }, false);
            } else
            {
                // do nothing, just quit
                return;
            }
            contentService.getActivationService().persistExtensionActivations();
            contentService.update();
        }
    }

The method findCommonNavigator(String viewId) is responsible for delivering the instance of the CNF. For example it could query the view for visible viewers and compare them with the requested Id:

    public static CommonNavigator findCommonNavigator(String navigatorViewId)
    {
        IWorkbenchPage page = PlatformUI.getWorkbench().getActiveWorkbenchWindow().getActivePage();
        if (page != null)
        {
            IViewPart view = page.findView(navigatorViewId);
            if (view != null && view instanceof CommonNavigator)
                return ((CommonNavigator) view);
        }
        return null;
    }

After the NCE status is changed the viewer has to be updated. Please note, that retrieving the instance of the INavigatorContentService via the Factory (NavigatorContentServiceFactory) will not work for this scenario (see Bug 284650).

Making a step back and thinking about the usage of the method above, I realized that it can be reduced to the usage of core expressions instead of the simple boolean activeByDefault attribute. Maybe this enhancement could be contributed to the CNF at some point…

The source code to this post is available for download. It includes two plug-in projects (the CNF and the child content) which are packaged into a small RCP application. Just launch the product included in the CNF plug-in.

References

The compass image used in the post is taken from the FlickR gallery of Jean Franco Castro.

Passing Data between Plug-ins

Simon Zambrovski — Wed, 22 Jul 2009 20:57:12 +0000

Abstract

The Eclipse Platform provides a very rich API for the development and configuration of plug-ins and RCPs. It does this in two ways: by providing the corresponding classes and interfaces or by using the extension point mechanism. During the development the question arises, how to develop own extension points and how those plug-in interfaces look like. This article summarizes some of my experiences with developing plug-ins extension points.

Introduction

The extensive use of extension points is the standard approach during the development of own plug-ins and Eclipse-based applications. Especially, in the 3.x branch, the Eclipse Developers introduced tons of new extension points, primarily for the user interface, moving towards the declarative definition of the UI. Even if the the topic of the definition of extension points is covered in several books and articles, it is a bit challenging to come up with a clean extension point design for a particular scenarios, especially for beginners. This has to do with the specific way, how the Eclipse platform handles extensions.

In order to have a concrete scenario, lets assume that a small RCP application consisting of two plug-ins is being developed. The application prints out the time every ten seconds. One plug-in is responsible for the functionality of the time generation (lets call it the Core plug-in) and another, for the presentation of the results of the first one (lets call it UI plug-in). The separation of code in UI and non-UI plug-ins is a common practice and the standard question is, how to to pass data between the two. In general we assume, that the UI plug-in depends on the Core plug-in.

In the following the different alternatives are discussed.

Call me synchronously

One of the most simple and common cases is the situation, in which the UI plug-in has the control and needs to call a method on some instance of the Core plug-in. This happens particularly in cases, in which a command handler or an action implemented in the UI plug-in is invoked on behalf of user interaction and the functionality of the Core plug-in is called. The only thing to do is to add the classes to the exported by the Core plug-in. Since the UI plug-in depends on Core, the classes will become visible (in terms of OSGi) and can be imported and used directly. If the method is synchronous, the result can be received upon the completion of the method and displayed by the UI plug-in. In this case the plug-in boundary disappears.

Call me asynchronously

The things get more complicated, if the call is not synchronous, but is invoked inside of a IWorkspaceRunnable or a Job. This situation is common in enterprise scenarios, when the invoked functionality is a long running operation, like loading data from a database or accessing a resource over the network. The signatures of the methods for those operations do not provide a possibility to get the invocation result.

public interface IWorkspaceRunnable {
    public void run(IProgressMonitor monitor) throws CoreException;
}

public abstract class Job extends InternalJob implements IAdaptable {
    protected abstract IStatus run(IProgressMonitor monitor);
}

In fact the method invocation of asynchronous calls can be performed from any plug-in (so not only UI) and it does not play any role for the result. Thus, this case can be discussed together with the case, in which the Core plug-in broadcasts the data change.

Don’t call us, we will call you

Another case, which can be seen as a general extension of the asynchronous case is if the state changes, and consequently the UI change originates from the Core plug-in. This use case is possible if there are several UI plug-ins working with one Core plug-in, and the changes inside of the Core plug-in have to be propagated to the views, following the well-known Model-View-Controller Design Pattern. Then, a common approach is the implementation of the Listener-Broadcaster Design Pattern. The UI plug-ins (Views) should register themselves as listeners by the Core plug-ins and will be notified on changes of its (Model) state. In this case the extension point mechanism of Eclipse can be used as discussed in the following. It is also a good idea, to hide the code dealing with Eclipse Extension Registry and extensions, so a simple implementation of the broadcaster is provided, too.

Definition of the extension point (Core plug-in side)

The definition of extension point for the listener/broadcaster case involves four steps:

Creation of the listener interface
Registration of the extension point
Creation of the extension point schema
Implementation of the broadcaster

The so defined extension point can be used by plug-ins, which then provide implementations of the listener interface. The broadcaster, located in the Core plug-in is responsible for sending the data to them. Note, that providing the implementation of the listener via extension point is logically equivalent to the creation of a factory which is responsible for the production of listeners. The Core plug-in has the control of how this factory is used, how many listeners (from each extension) are created, and when these are notified.

Creation of the listener interface

The interface for the listener is usually very simple. It provides a method, which is called by the broadcaster, e.G:

public interface ISimpleListener
{
    public void eventOccured();
}

Sometimes the method takes parameters, like public void eventOccured(String message) or public void eventOccured(ISimpleEvent event) and sometimes it returns a value. In general, the signature of the notification method is application-specific and will not be discussed further. Since the implementers of the listener does not have control over the way, how and when this method is used, it is advised to add two life-cycle methods to the interface initialize() and terminate():

package de.techjava.rcp.plugins.core.listener;

/**
 * A simple listener
 * @author Simon Zambrovski, TechJava Group
 */
public interface ISimpleListener
{
    /**
     * Initialization life-cycle method
     */
    public void initialize(Object source);

    /**
     * Signals the event occurrence
     * @param event
     */
    public void eventOccured(SimpleEvent event);

    /**
     * Termination life-cycle method
     */
    public void terminate();
}

The life-cycle of the listener is then defined as follows: first, its parameter-less constructor is called, then the initialize method is invoked, providing the ability to hook into some infrastructure inside of the implementing plug-in. After the initialization, the eventOccured method is called multiple times. Finally, the listener is informed about the fact that the source will not send any information by the invocation of the terminate method. The source parameter of the ISimpleListener#initialize(Object) method again is application specific and should be chosen that way, that the listener is able to determine the source of events. Alternatively, the method ISimpleListener#eventOccured(SimpleEvent) can carry this information on every invocation, either in the SimpleEvent object or as additional parameter.

Registration of the extension point

After the Java interface of the listener has been created, the extension point can be defined. The easiest way to this, is to use the Plug-In Manifest Editor > Extension Points, but you can edit the plugin.xml directly. Basically, three values are required: id, name and schema location.

The corresponding plugin.xml code looks like this:

Since the dependent plug-ins should implement the ISimpleListener interface, the containing package has to be exposed. This can be done either by adding the package to the list of exported packages using the Plug-In Manifest Editor > Runtime > Exported Packages or by simple editing of the MANIFEST.MF file and adding the following line to it:

Export-Package: de.techjava.rcp.plugins.core.listener

Creation of the extension point schema

The definition of the extension point is performed by creation of the XML-Schema document, describing the structure and the data of the extension point. The Eclipse IDE provides a convenient Extension Point Schema Editor for this task, implemented as multi-page editor with master-detail page for schema definition. The creation wizard already creates the extension element. What has to be done is this:

Create New Element
Provide an adequate Name for it (listener in our case)
Add an Attribute to this element
Provide an adequate Name for it (class in our case)
Change the Use to required
Change the Type to java
Fill the Implements with the full-qualified name of the listener interface (de.techjava.rcp.plugins.core.listener.ISimpleListener)
Optionally, fill the description
Add a Sequence to the extension
Add a reference to the listener to the Sequence
Optionally, adjust the multiplicity of the listener element, to allow multiple listeners to be registered using one extension point

In the Extension Point Schema Editor the corresponding changes should look like this:

Implementation of the broadcaster

After the interface is created and the corresponding extension point is defined, a broadcaster can be implemented. Its purpose is to hide the code related to the use of the Extension Point Registry. For convenience, the broadcaster can implement the same interface as the listeners do (ISimpleListener).

/**
 * Simple broadcaster implementing the listener interface
 * @author Simon Zambrovski, TechJava Group
 */
public class SimpleBroadcaster implements ISimpleListener
{

    private static final String POINT_ID = "de.techjava.rcp.plugins.core.listener";
    private static final String CLASS_ATTRIBUTE = "class";

    private List listeners = null;

    /**
     * Construct the broadcaster and initializes the listeners registered
     * using {@link de.techjava.rcp.plugins.core.listener} extension
     * point
     */
    public SimpleBroadcaster(Object source)
    {
        // initialize on creation
        initialize(source);
    }

    public void eventOccured(SimpleEvent event)
    {
        // broadcast the events
        for (ISimpleListener listener : this.listeners)
        {
            if (listener != null)
            {
                listener.eventOccured(event);
            }
        }
    }

    public void initialize(Object source)
    {
        // retrieve the registered listeners
        this.listeners = getRegisteredListeners();

        // initialize
        for (ISimpleListener listener : this.listeners)
        {
            if (listener != null)
            {
                listener.initialize(source);
            }
        }
    }

    public void terminate()
    {
        // terminate
        for (ISimpleListener listener : this.listeners)
        {
            if (listener != null)
            {
                listener.terminate();
            }
        }
        this.listeners = null;
    }
...
}

The broadcaster holds the list of registered ISimpleListener instances. Its own implementation of the ISimpleListener is trivial and just delegates the calls to the elements of this list. The static method SimpleBroadcaster#getRegisteredListeners() is responsible for querying the registry for the registered extension and looks as follows:

    /**
     * Retrieves all registered listeners
     */
    public static List getRegisteredListeners()
    {
        IConfigurationElement[] decls = Platform.getExtensionRegistry().getConfigurationElementsFor(POINT_ID);

        Vector validExtensions = new Vector();
        for (int i = 0; i < decls.length; i++)
        {
            try
            {
                ISimpleListener extension = (ISimpleListener) decls[i].createExecutableExtension(CLASS_ATTRIBUTE);
                validExtensions.add(extension);
            } catch (CoreException e)
            {
                Activator.logError("Error instatiating the " + POINT_ID + " extension", e);
            }
        }
        return validExtensions;
    }

Use of the broadcaster

The use of the broadcaster from the Core plug-in is straight-forward. Here is an example of a job, which periodically sends message containing the time to the listeners.

/**
 * Broadcasts the current time
 * @author Simon Zambrovski
 * @version $Id$
 */
public class SimpleTimeBroadcastJob extends Job
{
    private SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd hh:mm:ss");
    private SimpleBroadcaster broadcaster = null;

    public SimpleTimeBroadcastJob()
    {
        super("Time Broadcast Job");
    }

    protected IStatus run(IProgressMonitor monitor)
    {
        try
        {
            broadcaster = new SimpleBroadcaster(this);
            broadcaster.eventOccured(new SimpleEvent("Curent time in Core is " + sdf.format(new Date())));
            broadcaster.terminate();
            return Status.OK_STATUS;
        } finally
        {
            // restart again in a 10 seconds
            schedule(10 * 1000);
        }
    }
}

Now, after the Core part is implemented, we focus on the implementation of the UI part, which receives the events.

Use of extension point (UI plug-in side)

The usage of the extension point is simpler than its definition and basically consists of the implementation of the listener interface and its registration. Here is a sample implementation writing to System.out:

public class SimpleListener implements ISimpleListener
{
    private Object source;

    public SimpleListener()
    {
    }

    public void eventOccured(SimpleEvent event)
    {
        String message = "Event from " + source.toString() + ": " + event.getMessage();
        System.out.println(message);
    }

    public void initialize(Object source)
    {
        this.source = source;
        System.out.println("New " + SimpleListener.class.getName() + " listens to " + source.toString());
    }

    public void terminate()
    {
        this.source = null;
        this.consoleStream = null;
        System.out.println("Listners destroyed");
    }
}

In order to tell the Eclipse Platform about the existence of this implementation, the extension point defined in the Core plug-in and has to be used in the UI plug-in. For this purpose, the UI plug-in must list the Core plug-in in its Dependencies and define the use of the extension point in the plugin.xml:

That’s it.

Example

The example source for this article is available here. It is a little bit more elaborate and provides a simple application, which prints the time into the Eclipse Console. I used Eclipse Galileo (3.5.0) – just copy the two projects into your workspace and run the product.

References

Packaging Eclipse-based RCP for the use in enterprise context

Simon Zambrovski — Wed, 08 Jul 2009 20:00:33 +0000

Abstract

Using Eclipse-based rich-clients as stand-alone applications is discussed in many books and articles. In the context of enterprise systems, the software development adopted several paradigms to improve the quality of the overall architecture. This short article describes some issues in packaging the application for using it in the context of enterprise systems.

Architectural Assumptions

Designing enterprise architectures is a standard discipline for IT-consulting companies or freelancers involved in software development. Maybe one of the main characteristics of enterprise architectures is the framework-driven approach of software creation. Thus, the software has to comply certain rules and standards adopted inside the enterprise. In order to simplify such constrained development process, it is common to use an in-house software framework, which enforces the compliance of the enterprise-internal standards and acts as glue between different technologies adopted as parts of the enterprise architecture.

Using such frameworks has major implications for the software development in general, and especially for the rich client development. The design issues are summarized in the next section.

Usaging an Enterprise Framework

The major goal of the enterprise in-house framework is to simplify the process of software systems development and to enforce standardization among the software systems. This usually includes the following aspects:

Domain-specific component framework
Methods for master data management
Infrastructure services: authentication, authorization, communication, security, printing, reporting
Application skeletons and launchers

The more unification and standardization is included inside the framework, the easier it is for a software developer to concentrate on the particular business task and the easier is the maintenance of the software system.

From the previous list, the most interesting part related to RCP packaging and deployment is the existence of the application skeletons and launchers. So, when launching an application, the framework libraries are loaded and executed first and pass the control to the application-specific modules. The advantage of this approach is that infrastructure services can be loaded first, which can be developed and shared among different applications.

The required plug-ins

Following the general idea of RCP packaging (see rules provided in the RCP Book) and assuming one target platform (in terms of one RCP product), one top-level plug-in and should be defined. In addition, we assume at least one in-house framework plug-in and at least one application-specific plug-in. Usually there will be more of each type, but it will not change the picture much. Important at this point is the fact, that the application-specific code depends on the in-house framework code. In order to simplify the identification of the plug-ins, an example project is introduced. Let’s assume the project is called FooBar. Then, the plug-ins are called:

de.techjava.foobar: This is the functional plug-in, which contains the application-specific code.
de.techjava.framework: This is the framework plug-in, which contains framework component code.
de.techjava.foobar.product.standalone: This is an application and product definition plug-in which contains the definition of the product and application-agnostic code for launching the application.

Managing plug-in dependencies

A difficult issue for the RCP beginners is the management of dependencies between plug-ins. Especially, the transition from the development of a single plug-in to the configuration of features and products seem to be non-trivial. In order to solve this problem, there are simple rules to follow. You can violate these rules in sophisticated scenarios, but for the beginners it is a good idea to follow them.

Create dependencies only if you need them. Each plug-in should only list plug-ins (or even better packages) it really depends on. Make sure to check it with the “Find unused dependencies” action available on the right-click in the Dependencies Tab of the Plug-in Manifest Editor.
Use versioning information. Plug-ins (or better bundles, or as Chris call them Plundles) provide version information. And it is highly advisable to include them in the import statements of the plug-ins, which simplifies the migration later on…
Don’t forget anything. Every Plug-in should appear in at least in one Plug-In section of the Feature definition. Every feature should be included by another feature, higher in the hierarchy.
Keep the hierarchy flat. For simple scenarios, it is sufficient to have two levels of features (top-level feature, one per-product and the underlying features include their plug-ins).
Don’t re-export dependencies. Every Feature for a group of plug-ins should also include plug-ins required by the members of the group. It does not hurt if a plug-in is included several times, but it does if it is not included at all. You can optimize here if you check which plug-ins are imported by the Eclipse RCP feature (which can be considered as stable), but it does not make assumptions about features developed by third parties.

Following these rules it is simple to create features for the corresponding plug-ins. Several plug-ins which belong together and are handled as a fixed piece can be grouped into Features. Usaging Features is highly advisable, and sometimes simply required (e.G. by RCP in a Java Web Start target deployment strategy). So in addition to the previously mentioned plug-in projects, at least three feature projects are required:

de.techjava.foobar.feature: This is a functional feature, which includes the de.techjava.foobar plug-in and all plug-ins required by it, which do not appear in the Eclipse RCP feature
de.techjava.framework.feature: This is a framework feature, which includes the de.techjava.framework plug-in and all plug-ins required by it, which do not appear in the Eclipse RCP feature
de.techjava.foobar.feature.standalone This is the top level feature, which is used for the product configuration. It includes the two features above and the Eclipse RCP feature (and optional other features used, like e.G. org.eclipse.help). It also includes exactly one plug-in, which is not included anywhere else: de.techjava.foobar.standalone.product

The product definition plug-in

The definition of the product is spread among several files. First of all the plug-in.xml of the de.techjava.foobar.standalone.product plug-in makes uses of two extensions:

org.eclipse.core.runtime.applications
org.eclipse.core.runtime.products

The application extension point is used to point to the Java class implementing the interface org.eclipse.equinox.app.IApplication. Along with this implementation, other classes needed to start up the RCP (like Advisors, etc…) are placed into the source directory of the plug-in. The product extension point is used for the association of the application with a product id. The previously-defined top-level feature includes all required features and the product definition plug-in. Finally, the .product file is the place, where all things are bound together: product id, application id, launcher parameters, and the one top level feature: de.techjava.foobar.feature.standalone. Other customization of the RCP is possible from the plugin-customization.ini, which is placed together with the .product file into the plug-in root directory.

As a result the following configuration should be achieved after the packaging is finished. The product references the product-id and the application, defined in the plugin.xml of the plug-in project it is contained in. The product configuration is feature-based and includes one top-level feature. The top-level feature includes all other features (functional, framework, Eclipse RCP, other optional) and the one plugin, in which the product file resides.

The simple example provided in this articles is available as sourcecode for download ( rcp-packaging.zip).

The framework hooks

In the introduced scenario, the packaging is not specific to the in-house framework. It just includes the feature containing the framework plug-in. This approach works fine, if the framework is used in a white-box manner, which means that the framework provides ready-to-use components to be plugged-in to the application (like e.G. a component for the master data management). The other type of frameworks is the so-called black-box framework, which provides components that have to be configured and integrated into the application components. In this case, the framework components can not be plugged-in using some declarative extension points, but need to be called from the application code. In the latter case, the dependencies appear between the plug-in launching the application (de.techjava.foobar.standalone.product) and the framework plug-ins. This requires a modification in the previous setup and the violation of one of the rules posted above. The plug-in has to define the dependency to the framework plug-in, but the top-level feature does not include the required plug-in directly, but imports the whole framework feature.

Technorati-Tags: eclipse, java, rcp, packaging, plugin, feature, product, enterprise systems

Eclipse Common Navigator Framework

Simon Zambrovski — Tue, 28 Apr 2009 01:13:02 +0000

Abstract

This article describes some efforts to use the Common Navigator Framework (CNF). In doing so it incorporates the information already covered in different articles, but also focuses on the specific use case of providing a view of something completely unrelated to the platform resources. So the aim is not to add some content to the “Project Explorer” which is an example of resource-oriented CNF usage, but to provide a view on a completely own data model.

Introduction

A very common UI element to represent data is a tree view. In SWT this UI element is implemented using the Tree widget. Following the MVC design pattern in the TreeViewer, JFace simplifies the usage of the Tree widget by delegating the task of content adoption to the ContentProvider and the label production to the LabelProvider (and using Sorters and Filters for sorting and filtering). Still for a single representation one has to construct a viewer and configure it with a corresponding Label- and ContentProvider. Further code reduction can be achieved by the use of WorkbenchContentProvider and WorkbenchLabelProvider if the elements can be made adaptable (implement IAdaptable interface and making them first-class workbench citizens). This approach is helpful, if the elements has to be displayed in several different viewers (e.G. Table). Finally, the Common Navigator Framework (CNF) is a facility provided by the Eclipse Platform which allows the usage of multiple Label- and ContentProvider on the same view. The providers are activated and used dynamically and can be configured declarative or programmatically. The advantage of CNF approach is the ability to combine elements in one view which have different origins(e.G. contributed by different plugins). CNF is used in Eclipse IDE: e.G. “ProjectExplorer” and “CVS Synchrnoize” are both instances of the CNF.

The usage of the CNF in your own application for purposes of representation of resource-based (and usually file-based) content is discussed in articles of Micael Elder in detail. The main idea is to instantiate the view, declare the default content and UI interface and make some additions where needed. This post has a different aim: we start from scratch and represent completely resource unrelated content. Before diving in the implementation details, some overview is provided.

UI Overview

There are many things which can be configured by the usage of CNF and it is beyond the scope of this post to cover all of them. Still there are several things to understand before the actual code can be written. The user interacts with a View which shows the data elements. Which elements are shown is configured using the navigation content extensions. Shown elements can be filtered with Filters and sorted using Sorters on behalf of the user. There are some predefined actions and their positions in the UI and corresponding extension points to contribute to. . The actions for Working sets, Customize View, Link with editor belong to this category. The user can also right-click on particular element in the tree and sees a popup-menu. This menu is configured based on the content element and can be (is) contributed by several plugins. The action contribution is also covered in the article series from Michael Elder.

Minimal non-resource based CNF viewer

The following example provide a set of minimal steps required to create a non-resource based CNF viewer. Your plug-in requires at least a dependency to org.eclipse.ui.navigator, org.eclipse.ui.

Data model

Let us assume a simple data model that should be represented in the view. There are two kinds of elements: parents and children (see Composite design pattern). Both Child and Parent are POJOs:

public class Child
{
    private String name;
    private Parent parent;

    public Child(String name)
    {
        super();
        this.name = name;
    }

    // getters and setter
...
}

Every child stores information about its parent, and every parent knows its children. In order to maintain the model in-sync the setChildren() method of the Parent class takes care of unsetting on all previous children and setting the parent on new children. This is just a sample code and there are different ways to implement this more elegantly (like e.G. holding the parent-child relation externally).

public class Parent extends Child
{
    private Child[] children = new Child[0];
    private Object rootElement;

    public Parent(String name)
    {
        super(name);
    }

    public void setChildren(Child[] children)
    {
        if (children != null)
        {
            setChildrensParent(null, this.children);
        }
        this.children = children;
        setChildrensParent(this, this.children);
    }

    /**
     * Sets children's parent
     * @param parent parent to be set
     * @param children children to set the parent
     */
    private static void setChildrensParent(Parent parent, Child[] children)
    {
        for (int i = 0; i < children.length; i++)
        {
            children[i].setParent(parent);
        }
    }

    // getter and setter
...
}

Please note, that nothing more is assumed about the parent and the child. It is a good idea to make such elements implement IAdaptable, which simplifies a lot of issues later, but this is another topic. You may have noticed the rootElement member of the Parent. Again, this is only used in order to keep the object tree structure as simple as possible and provide a hook to the root of the tree. The final tree structure contains one root object, several parent objects containing several child objects each.

public class Root extends PlatformObject
{
}

Declaring the viewer

In order to contribute a view to RCP/IDE the org.eclipse.ui.views extension point is used:

The two important things here are the class attribute pointing to the class of the CNF Navigator and the id attribute that will be used later in order to identify the view. Instead of pointing to the org.eclipse.ui.navigator.CommonNavigator
the reference to ParentChildNavigator is provided which is a subclass of the CommonNavigator. The reason for that is, that CommonNavigator gets its initial input (during initialization) from the Workbench by calling getSite().getPage().getInput(). In the IDE scenario, the default page input is IWorkspaceRoot, in the RCP scenario it is null and can be configured in the WorkbenchAdvisor. Instead, another implementation of getInitialInput() can be provided, passing the dummy Root object, which indicates the root of the tree.

public class CNFNavigator extends CommonNavigator
{
    protected IAdaptable getInitialInput()
    {
        return new Root();
    }
}

Defining viewer content

In order to see something in the freshly-defined viewer, the information about the content has to be provided. The extension point org.eclipse.ui.navigator.navigatorContent is defined for this purpose. The main element responsible for the content is called navigatorContent and contains the following information:

id – the id of the content, to be referenced in the viewer
name – the name of the content, which is seen in the Customize View dialog using the content tab, which can be activated or deactivated there by the user.
contentProvider – the contentProvider class responsible for providing content elements
labelProvider – the labelProvider class responsible for rendering a content element in the view

In addition, nested elements triggerPoints and possibleChildren describe when the current content is activated. This means that a CNF Viewer can compose the content coming from multiple providers and needs to know what content to display. These will be covered in the following sections.

How the platform uses the viewer

Before diving into the code section, it is worth spending a small section on the topic, how the platform uses the CNF viewer. In general, if an element is selected in the viewer, the CNF consults triggerPoints of all Navigation Content Extensions (NCEs) provided and tries to match the element to the trigger point expression. If the expression matches, the NCE is activated by the platform and the corresponding contentProvider is responsible for delivering content. If the element is activated by other means than in the viewer (e.G. in the Editor), the platform consults possibleChildren list and tries to match the corresponding expression. For resource-based approaches, the NCE with id org.eclipse.ui.navigator.resourceContent is usually provided. This NCE is enabled / triggered on any element that is instance of IResource. By this means e.G. the Project Explorer in the IDE passes the workspace root to the ResourceExtensionContentProvider which is responsible for delivering the children of the workspace root – the projects. In a non-resource based approach, the NCE must be triggered by the initial input of the viewer, in this example by the Root object. If the selected element is a Parent node, the NCE should also be triggered. The following definition of the trigger point accomplishes this task:

Since the children delivered by the content provider on Root as parent element are instances of Parent and on Parent as parent element are instances of Child, the possibleChildren code looks as follows:

Label and Content providers

After the way how the navigation content is being activated is discussed, the Content and Label providers can be addressed. The label provider implementation is straight-forward. Its task is to produce a textual and graphical representation of every element. In addition, it implements the IDescriptionProvider interface to provide description in the status bar when an element is selected. Please note, that this section is not CNF-specific but is related to JFace ContentProvider and JFace LabelProvider, as usual for any Viewer. It is provided here only for completion and if the user is not familiar with it in detail.

public class CNFLabelProvider extends LabelProvider implements ILabelProvider, IDescriptionProvider
{
    public String getText(Object element)
    {
        if (element instanceof Parent)
        {
            return ((Child)element).getName() + " [ " +((Parent)element).getChildren().length + " ]";
        } else if (element instanceof Child)
        {
            return ((Child)element).getName();
        }
        return null;
    }

    public String getDescription(Object element)
    {
        String text = getText(element);
        return "This is a description of " + text;
    }

    public Image getImage(Object element)
    {
        if (element instanceof Parent)
        {
            return PlatformUI.getWorkbench().getSharedImages()
              .getImage(ISharedImages.IMG_OBJ_FOLDER);
        } else if (element instanceof Child)
        {
            return PlatformUI.getWorkbench().getSharedImages()
              .getImage(ISharedImages.IMG_OBJ_FILE);
        }
        return null;
    }
}

The methods above are self-describing. For any element the text and image is selected based on element type. For children, the name is shown, for parents the number of children is displayed, additionally. The platform built-in icons of folder and file are used for convenience. The methods for the Label/Content provider usually follow this pattern of a instanceof cascade.

The content provider is responsible for the following tasks:

At requested of Root it should deliver the list of Parent elements
At requested of Parent it should deliver the list of its children (Child elements)
At requested of Child it should deliver an empty list

Since no real data model is available, its creation is hooked to the first access (that is, of course, for demonstration purposes only)

public class CNFContentProvider implements ITreeContentProvider
{

    private static final Object[] EMPTY_ARRAY = new Object[0];
    private Parent[] parents;

    public Object[] getChildren(Object parentElement)
    {
        if (parentElement instanceof Root)
        {
            if (parents == null)
            {
                initializeParents(parentElement);
            }
            return parents;
        } else if (parentElement instanceof Parent)
        {
            return ((Parent) parentElement).getChildren();
        } else if (parentElement instanceof Child)
        {
            return EMPTY_ARRAY;
        } else
        {
            return EMPTY_ARRAY;
        }
    }

    public Object getParent(Object element)
    {
        if (element instanceof Child)
        {
            return ((Child) element).getParent();
        } else if (element instanceof Parent)
        {
            return ((Parent) element).getRoot();
        }
        return null;
    }

    public boolean hasChildren(Object element)
    {
        return (element instanceof Root || element instanceof Parent);
    }

    public Object[] getElements(Object inputElement)
    {
        return getChildren(inputElement);
    }

    public void dispose()
    {
        this.parents = null;
    }

    public void inputChanged(Viewer viewer, Object oldInput, Object newInput)
    { /* ... */
    }
    ...
}

The class has three important methods: getChildren(Object), getParent(Object) and hasChildren(Object). The getChildren(Object) is responsible for delivering children elements to a given parent element. The getParent() delivers a parent for a given child element (e.G. when the child is selected using the editor and the viewer is requested to show the element in it). The hasChildren(Object) is a way of providing a more efficient implementation than (getChildren(element).length == 0). The getElements(Object) method is usually delegated to getChildren(Object). The difference between these methods is that getElements(Object) is called to obtain the tree viewer’s root elements, whereas getChildren(Object) is used to obtain the children of a given parent element in the tree (including a root). Since there is only one root (the not shown IWorkspaceRoot), it is OK to delegate. Finally, the parents member variable needs to be initialized on the first access, which can be done using the following code:

    /**
     * Init code for empty model
     */
    private void initializeParents(Object parentElement)
    {
        this.parents = new Parent[3];
        for (int i = 0; i < this.parents.length; i++)
        {
            this.parents[i] = new Parent("Parent " + i);
            this.parents[i].setRoot(parentElement);
            Child[] children = new Child[3];
            for (int j = 0; j < children.length; j++)
            {
                children[j] = new Child("Child " + i + j);
            }
            this.parents[i].setChildren(children);
        }
    }

Binding the content to the viewer

The last remaining piece in the puzzle is to bind the content defined in the navigation content extension to the view defined in the view extension. The extension point org.eclipse.ui.navigator.viewer is responsible for that. It consists of several parts: the viewer element, that references the id of the view and the viewerContentBinding element that one one hand specifies the view to bind the content to and on the other hand provides a reference to the content definition id.

Please note, that the content id is provided in the pattern attribute. Instead of pointing to particular content id, the regex can be used (e.G. de.techjava.rcp.cnf.content.*). That’s it, look at the result.

Under “Custimize View” the content tab allows to show the defined “virtual content”. Since no filters are defined, the filter section is empty.

Conclusion

To my opinion, for almost every application using a tree/list view to represent entities the CNF should serve as a basis for the implementation. Thus, CNF documentation should be improved and get to the level “for beginners” rather than “for experts”. In this post, I have tried to provide an introduction for non-expert RCP/PDE developers. I’m interested in your comments.

Further directions

Currently, neither filters, sorters nor actions or pop-up menu are defined for the viewer. This can be a subject of the follow-up post, if requested, but is partly covered in the articles of Michael Edler. Especially, the application of the new command framework has to be described.

Resources

Eclipse

Digital Paper Napkin by Michael D. Elder

A basic set of introduction articles written in 2006. The articles introduce contribution to the resource-based CNF viewer displaying the content of the property files. A good overview to get into the subject. The blog seems to be dead, according to many spam comments.

Eclipse from the bottom up by Michael Valenta

A good hint is to look on the implementation of the CVS Synchronize View. Pretty old content, but still valid.

vAAni by Aashish Patil

Weakly formatted article, providing some hints on how to implement a not “resource only”-based CNF viewer. Still, the information from here helped me to create a complete non-resource based CNF viewer described here.

Other

Thanks to Francis Upton, who reviewed the post and corrected some mistakes and misconceptions.

Special thanks to Michael “Mike” L. Baird for the beautiful picture of the compass. I found the picture on Google Image Search and became a big fan of his pictures (some of you know about my photo passion). It is funny that from all places in the world, the picture is shot in Morro Bay, about 200 Miles away from where I’m located now. It is also funny that Mike is a computer science guy, even if retired…

RCP Help System

Simon Zambrovski — Fri, 24 Apr 2009 22:04:23 +0000

Eclipse Platform provides a help system that can be used during creation of the help content for your application. It is very convenient while used inside of the IDE, but needs a special approach if used in the RCP. This article tries to gather the information which may be useful.

Adding Help Support

Basic preparations

As discussed in Eclipse RCP Book and RCP Articles, the help system is not a part of the RCP-Runtime and should be added separately. The question arises where to add at to? If you follow the best practices for packaging of RCP applications, you should have at least one product and the top level feature defined (See Rule 1 of Chapter 23 of Eclipse Rich Client Platform). The top level feature includes the branding plug-in (containing the product definition) and refer to other features (like org.eclipse.rcp, and your functional features). In order to add the help system, you need to add the org.eclipse.help feature in this list.

Platform help buttons

There are several predefined buttons (actions) you can use for calling the help system. These are:

Help Contents
Help Search
Dynamic Help

In order to activate them from your ApplicationActionBarAdvisor just call:

private IWorkbenchAction helpContentsAction;
private IWorkbenchAction helpSearchAction;
private IWorkbenchAction dynamicHelpAction;

protected void makeActions(IWorkbenchWindow window)
{
helpContentsAction = ActionFactory.HELP_CONTENTS.create(window);
dynamicHelpAction = ActionFactory.DYNAMIC_HELP.create(window);
helpSearchAction = ActionFactory.HELP_SEARCH.create(window);
register(helpContentsAction);
register(helpSearchAction);
register(dynamicHelpAction);
}

If you want to do the same declarative, you have to create commands that use the following actionDefinitionIds:

org.eclipse.ui.help.helpContents
org.eclipse.ui.help.helpSearch
org.eclipse.ui.help.dynamicHelp

The same ids are required for registration of key bindings (e.G. Ctrl + F1, Shift + F1, F1 on Win32). Apparently, since these actions adjust their status depending on the state of the system and the plug-ins installed, I could not figure out how to force them to be enabled, when installed in a declarative way. Since they are still provided as ActionFactory (which is legacy due to the changes introduced by new Command Framework), they should be further activated from the ApplicationActionBarAdvisor.

Context-Sensitive Help UI Integration

The Eclipse platform provides not only the help system, but also support the so-called Context-Sensitive Help (a very confusing name, because the context is only the widget, and not the data). In the following, it is shown, how the connection between the widgets and the help system can be established.

The big picture

The content already defined in the help system can be pointed at from various places in the your application using the so-called help contexts, which on one hand point to the places in the documentation and on the other hand can be assigned to widgets in the application UI.

Establishing contexts

In order to assign the help context to a widget the invocation of the method PlatformUI.getWorkbench().getHelpSystem().setHelp(Control control, String contextId); is used. The contextId is a full-qualified string constructed from the pluginId and the local context name. The context name should be unique for this plug-in (usage of non-unique ids leads to a merge of different subjects, which is a nice feature, but may be not desired). I prefer to create the convenience method for this invocation:

public class HelpUtil
{
public static void setHelp(Control control, String localContextId)
{
if (localContext == null || control == null) return;
PlatformUI.getWorkbench().getHelpSystem().setHelp(control,
Activator.PLUGIN_ID + "." + localContextId);
}
}

There are also methods for registration of other SWT widgets (Control, IAction, Menu, or MenuItem) in the help system, which can be handled by the overloaded version of the method. The invocation of the convenenience method usually looks like: HelpUtil.setHelp(composite, "newWizardPage") and should be invoked from the createControls() of the correponding element. Please note, that the “newWizardPage” is a local name, and the pluginId is added to it inside of the conveninece method. Widgets that do not get focus should not be assigned context ids, since they will never trigger a context-sensitive help

The declarative part

As usual in Eclipse, there is a declarative part, that connects the context ids, set up in the code with the help pages. The connection is established by a special XML file. In order for the platform to know, where to find the file, there is an extension point (org.eclipse.help.contexts), that you need to contribute to:

The file attribute specifies the full path to the XML file containing the context definition. The plugin attribute is optional and declares for which plugin the context definition applies. Please note, that if the plugin attribute is ommited, the context names used in the context definition file will be seen as local to the plugin they are declared in. For example, if you want to support the context-sensitive help in plug-in de.techjava.rcp.xyz then your in-code definition of the context should define full qualified context names like de.techjava.rcp.xyz.context1. Either you use the extension point (org.eclipse.help.contexts) in the plugin.xml of the de.techjava.rcp.xyz plugin.xml, or if you put the usage of the extension point into some other plugin (e.G. central for all help), you must provide the plugin attribute with value “de.techjava.rcp.xyz”. This issue is badly discussed in the help guide and is a little confusing. In the context definition file the contexts are defined as follows:



This is a test context


...

Wizards and Dialogs

Wizards are used with or without dialog.

The call of the Wizard#setHelpAvailable(true) shows the Help button.
The call of the WizardDialog.setHelpAvailable(true); shows the small sexy round Question button.

References

RCP with multiple application windows

Simon Zambrovski — Wed, 14 Jan 2009 21:25:37 +0000

Eclipse RCP by default promotes the usage of a single application window with multiple views and editors inside. This default can be changed to multi-windowed application. The platform API offers several methods to operate with multiple application windows:

package org.eclipse.ui;
...
public interface IWorkbench ...
{
/**
* Retrieves the number of opened windows
*/
public int getWorkbenchWindowCount();
/**
* Retrieves the array of opened windows
*/
public IWorkbenchWindow[] getWorkbenchWindows();
/**
* Openes a new window with given perspective
*/
public IWorkbenchWindow openWorkbenchWindow(String perspectiveId,
IAdaptable input) throws WorkbenchException;
/**
* Performs a perspective switch in a given window
*/
public IWorkbenchPage showPerspective(String perspectiveId,
IWorkbenchWindow window, IAdaptable input)
throws WorkbenchException;
...

}

Using this API, opening of new windows seems simple. For example one could define a perspective, that is always opens in a new window.

Closing windows is generally performed by calling close method on the IWorkbenchWindow instance.

package org.eclipse.ui;
...
public interface IWorkbenchWindow ...
{
  /**
   * Closes the window
   */
  public boolean close();
}

Unfortunaly, there is no elegant way to find out which window are you in. A workaround which uses Eclipse internal API works fine for WorkbenchWindow, which is a standard platform implementation of the IWorkbenchWindow interface.

/**
 * Determines if the window is a root window
 * @param window a window to be checked
 * @return true, if the window is considered to be a root window
 */
public static int getWindowId(IWorkbenchWindow window)
{
// HACK: note this could change in future
  if (window != null && window instanceof WorkbenchWindow))
  {
    return ((WorkbenchWindow)window).getNumber();
  }
  return -1;
}

The initial application window gets the id 1. The lookup in the implementation reveals that the internal method finds the smalles unused positive number and assigns it to the newly opened window. If you do not want to rely on this algorithm, just hash the newly created windows by they ids.