Sunday, January 18, 2009

Tutorial: Export a sample RCP application using Spring, Spring Dynamic Modules for OSGi Service Platforms and AgileRCP

In this article you will learn how to export an RCP application that makes use of Spring, Spring-DM and AgileRCP. The article uses the example from the past tutorial about RCP / Spring / Spring-DM / AgileRCP (see part 1, part 2 and part 3). Please note that the example code has changed slightly, see the downloadable source code archive at the end of this article.

  1. Create a feature that contains all plug-ins:
    • New -> Other... -> Plug-in Development / Feature Project
    • Choose a proper project name, e.g. "org.digitalcure.hellospring.feature"
    • Initialize from the plug-ins list
    • Select the following plugins:
      • org.agilercp.ui
      • org.agilercp.ui.dialog
      • org.agilercp.util
      • org.apache.commons.logging
      • org.digitalcure.hellospring.app
      • org.digitalcure.hellospring.common
      • org.digitalcure.hellospring.service
      • org.springframework.bundle.osgi.core
      • org.springframework.bundle.osgi.extender
      • org.springframework.bundle.osgi.io
      • org.springframework.bundle.spring
    • Finish the wizard. An editor for the file fragment.xml will be opened.
  2. Add the current plug-in versions:
    • Switch to the Plug-ins tab.
    • Select all plug-ins and press the button "Versions...".
    • Select "Copy versions from plug-ins and fragments manifests" and finish the dialog.
    • Save the feature file.
  3. Configure the product to use features:
    • Open the product file (plug-in "org.digitalcure.hellospring.app", file HelloSpringApp.product).
    • Overview tab: The product configuration is based on: features
    • Configuration tab: Press the button "Add..." and select our newly created feature.
    • Press "Add..." once again and add the feature "org.eclipse.rcp".
    • Save the product file.
  4. Export the product (1st try):
    • File -> Export... -> Plug-in Development / Eclipse product
    • Configuration: Press the "Browse..." button, expand the plug-in "org.digitalcure.hellospring.app" and select the file HelloSpringApp.product.
    • Root directory: HelloSpring
    • Synchronize before exporting: yes
    • Destination: Select "Directory" and select a proper folder to export the product to.
    • Finish the dialog. Eclipse should export the product without errors.
  5. Run the exported product.
    • Use a file browser (e.g. Windows Explorer) to navigate to your export directory and run the product (e.g. named "eclipse.exe").
    • The application will be displayed after a short delay, but there is an error message instead of the expected table.
    • First of all: Don't panic! The error is caused by the lazy startup of the plug-ins. Spring-DM is unable to create a proper ApplicationContext and so the application is unable to instrument Spring.
  6. Add a configuration file to the application plug-in:
    • However, the exported product is very useful for us, because it ontains a default configuration file. Copy the file config.ini from the "configuration" folder and paste it into the root folder of the application plug-in.
    • Edit the build properties of the application plug-in and add the file config.ini to the binary build.
    • Open config.ini inside the Eclipse IDE.
    • Edit the line for the property "osgi.bundles" in the following way:

      osgi.bundles=org.eclipse.equinox.common@2:start,org.eclipse.update.configurator@3:start,org.eclipse.core.runtime@start,org.agilercp.ui@start,org.digitalcure.hellospring.app@start,org.digitalcure.hellospring.common@start,org.digitalcure.hellospring.service@start,org.springframework.bundle.osgi.extender@start

  7. Use the configuration file in the product:
    • Open the product definition file and switch to the Configuration tab. Take a look at the section "Configuration File".
    • Choose the tab for your operating system.
    • Select "Use an existing config.ini file".
    • Press the button "Browse..." and select the newly created configuration file.
    • Save the product definition file.
  8. Export the product (2nd try). Just the same as the 1st try.
  9. Run the exported product:
    • Same procedure as described above.
    • The application will be displayed, including the expected table. That's it!
You may download the source code of the tutorial from here.