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:

<?xml version="1.0" encoding="UTF-8"?>
<jnlp spec="1.0+" codebase="http://localhost/app/" href="app.jnlp">
    <information>
        <title>application titel</title>
        <vendor>provider</vendor>
        <offline-allowed/>
    </information>

    <security>
        <all-permissions/>
    </security>

    <application-desc main-class="org.eclipse.equinox.launcher.WebStartMain">
	<argument>-product</argument>
	<argument>de.techjava.app.webstart.productid</argument>
	<argument>-application</argument>
	<argument>de.techjava.app.webstart.appid</argument>
    </application-desc>

    <resources>
        <j2se version="1.4+" ax-heap-size="128m" />
	<jar href="plugins/org.eclipse.equinox.launcher_1.0.201.R35x_v20090715.jar"/>
	<extension name="wrap feature" href="features/wrap_feature_1.0.0.jnlp" />
	<!-- OSGI setup -->
        <property name="osgi.instance.area" value="@user.home/app"/>
        <property name="osgi.configuration.area" value="@user.home/app"/>
    </resources>
</jnlp>

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:

	<argument>-console</argument>
	<argument>1234</argument>
	<argument>-noExit</argument>

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

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.

1. 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.
2. 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…
3. 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.
4. 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).
5. 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.