The Open Services Gateway Initiative (OSGi) and Datalogics PDF Java Toolkit

Introduction

PDF Java Toolkit Core is OSGi compliant out of the box. Other components of Datalogics PDF Java Toolkit are not provided as OSGi compliant bundles. Datalogics has tested PDF Java Toolkit Core with Eclipse Equinox and Apache Felix, other OSGi containers, like Knopflerfish and ProSyst, have not been tested.

The Open Services Gateway Initiative (OSGi) is a framework used for developing and deploying modular components for Java applications that are designed with reuse in mind.

Using the OSGi specification focuses on creating standard Java modules. OSGI helps by defining how components are installed and updated (including updating while applications are running) and requiring well-defined interfaces to communicate between bundles. For more information about the benefits of using OSGi, take a look at the Benefits of Using OSGi on the www.osgi.org website.

Using modular Java components serves to make it easier to:

  • design and build large software applications that are less complex
  • develop software more efficiently and at a lower cost
  • create structured, disciplined code
  • deliver software packages to customers quickly
  • save time and effort when maintaining existing software products

The OSGi specification supports a wide variety of software platforms, including enterprise, consumer products, and mobile devices.

Developing a project designed to be compatible with OSGi standards involves building an application using the OSGi APIs and then deploying the application to a bundle. A bundle is like a plugin or a library file; the bundle is the built version of an application, made up of a collection of classes and configuration files that can run dynamically within an OSGi compatible runtime session called a container.

Bundles can run processes or services with the container, and the container manages all of the bundle’s requirements and dependencies. Each bundle can run independently, in its own class path, as a separate system module. OSGi bundles are standardized; any bundle built to meet OSGi specifications can be installed and run seamlessly on any container designed to work with OSGi.

You can run multiple versions of the same application bundle in the container environment at one time, and you can add new modules at run time. You can install or uninstall the app, or stop or restart it, without affecting the environment or the other applications running in that environment. And bundles running in the same container can be given varying levels of priority, allowing some to complete faster than others.

Working with the Equinox Framework


You can easily set up Equinox from within Eclipse.  

Setting up Equinox

  1. Open Eclipse.
  2. Click Help and go to the Eclipse Marketplace.
  3. Search for "Equinox."
  1. Click Install, then  and .
  2. You may need to respond to a message regarding installing software with unsigned content. Click OK, and then click Yes to restart Eclipse.
  3. Under Project Explorer right click and select , or click File and  .
  4. At the import menu under Plug-in Development click Plug-ins and Fragments.
    1. Click . Under Import From, select  and browse to where your stored your OSGI bundle file.
    1. Click .
    2. On the Selection Screen, you should see a window pane on the left with your OSGI bundle listed.
    1. Click on your bundle to select it and click .
    2. Click .
    3. The new OSGI bundle will appear in the Project Explorer.

    Check that your OSGI bundle is valid

    1. Make sure that you are in the Plug-Development perspective. Click Window, Open Perspective, and Other.
    2. Select Plug-in Development, and click OK.
    3. The Plug-ins tab appears in the upper left corner of the Eclipse window. Click on that tab to select it.
    4. On the bottom of the Eclipse window, you should see the Target Platform State tab. Click this tab and look for your bundle.
    1. Click the Error Log tab. Scroll through the most recent error messages, appearing at the top of the tab. Make sure there are no errors listed for your bundle.

    Running your bundle with the Equinox Framework

    1. Click the Package Explorer tab, and right click the bundle that appears, the list plug-in project. Select Run As.
    2. Select Run Configurations.
    3. Select OSGI Framework.
    4. If needed, click the New launch configuration button, .
    5. Click the Bundles tab. Make sure that your bundle is selected. If you have a test bundle also make it a lower start level.
    6. Click . Your configuration will be saved.

    Apache Felix Framework

    Setting up Felix

    1. Download the latest version of Apache Felix.
    2. Unzip the download file and folder structure to your preferred directory.
    3. Copy your OSGI bundle file to the installation package for Apache Felix, under the /Bundle subdirectory. Create a new directory for your bundle, /bundle/plugins.
    4. Open a command prompt and move to the directory structure where you installed Felix.
    5. Start the Adobe Felix framework:
    6. java -jar bin/felix.jar
    1. You should see the prompt for Felix:
    1. Enter the install command:
      felix:install
      Followed by the path and file name. The command would look something like this:
      felix:install bundle/plugins/pdfjt-3.1.1-SNAPSHOT.jar
    2. The system will respond by assigning an ID number to the bundle:
    3. Bundle ID: 10
      g!

    Running your bundle with the Apache Felix Framework

    1. To list the installed bundles, type, at the command prompt:
    2. LB
    3. You should see your installed bundle appear, with a number to the left.
    1. Type start and the number of your bundle to run it. In this case, you would type:
    2. Start 10
    3. To stop the bundle, type Stop and the number of your bundle:
    4. Stop 10

    Feedback and Knowledge Base