How To Add an OSGi Bundle to the Server

Create an Eclipse Plug-in Project

1. right-click in the white space of the Package Explorer view
2. choose New > Project...
3. Choose type Plug-in Project, click next
4. Pick "OSGi Framework" from the Target Platform, click finish

Convert an existing project to a plug-in project

1. right-click the name of the project in the Package Explorer view
2. PDE Tools > Convert Projects to Plug-in Projects...

Anatomy of a Plug-in Project

File structure:

    /build.properties
    /META-INF/MANIFEST.MF

Double clicking on either of these files brings up a GUI editor that presents intuitive forms on multiple tabs. The last two tabs allow you to edit the files directly.

Overview Tab

Indicate the Activator class. See the Bundle Activator section below.

Dependencies Tab

• Add org.ziptie.server.bootstrap to the Required Plug-ins section. This gives you access to IMain.ConfigurationService in your bundle activator class.
• Add shared libraries to the imported packages sections (e.g. org.apache.log4j, org.apache.commons.logging, etc.)

Build Tab

Click on add library and type in the name of the jar you want to create. Choose a short name that indicates the bundle (perhaps the bundle name without the org.ziptie prefix). Choose the src/ folder as the source for that jar. Under Binary Build choose

• the META-INF directory
• the jar you just defined for the src source folder
• any libraries specific to this bundle that cannot be imported as packages in the Dependencies tab

build.properties Tab

Shows the current state of the build.properties file based on the changes from the other tabs. If you edit it directly you may need to close and reopen the tabbed GUI editor in order to reflect the changes on the forms in the other tabs.

/META-INF/MANIFEST.MF

Shows the current state of the MANIFEST.MF file based on the changes from the other tabs.

Bundle Activator

Your bundle may have a class that implements the OSGi BundleActivator interface. The interface has two methods, start and stop, each are passed a BundleContext as a parameter. Add log messages at info level to both methods, so you will know that they were called when you start up the server. Be sure to catch exceptions and log a message at error level within these methods. Both methods throw Exception, but the server does not automatically log a message about exceptions. After you catch and log the exception re-throw it so the container can correctly mark the bundle as resolved (and not started).

Files in the Build project that you must edit

components.properties: add your bundle to the list of server bundles

Files in the conf project that you must edit

• All static configuration files (properties, xml) that are intended to be edited in the field go in the conf project. Read the ConfigurationService wiki page for more details on accessing the files in the conf project from classes in your bundle. Add configuration files for your bundle directly to the conf project.
• config.ini: add your bundle to the list of osgi bundles

build and start the server

1. you should be able to do a clean build in eclipse with no errors
2. follow the instructions on the HowtoBuildServer wiki page
3. when you start the server use the command line switches '-console -consoleLog'
4. view the log output and look for your bundles messages
5. type ss at the osgi> prompt to see the state of your bundle. it should be 'ACTIVE'

-- BrianEdwards - 17 May 2007