OSGi Declarative Services

For those of you who don’t know, the Eclipse SDK now ships an implementation of OSGi Declarative Services (DS). I love DS when working with OSGi services and recommend it to people over using the brittle ServiceTracker mechanism. I’m a big proponent of having people learn by example. To help people understand DS a bit more, PDE includes a DS template now. To access the template, simply create a new project and select the template:

Since the template is based on a simple dictionary service, you can fill out some sample words to be in the dictionary:

Once you click finish, PDE will generate a sample project for you. Inside that sample project, there will be a DictionaryService that allows you to register dictionaries (Dictionary):

package org.eclipse.equinox.ds.example;

public interface Dictionary {
 
    /**
     * Returns the language of the dictionary
     *
     * @return the language of the dictionary
     */
    public String getLanguage();
 
    /**
     * Check for the existence of a word in the dictionary
     * 
     * @param word the word to be checked.
     * @return true if the word is in the dictionary
     */
    public boolean check(String word);

}

You will also notice that the MANIFEST.MF has an entry of ‘OSGI-INF/*.xml’ for the Service-Component header that lists the required DS files. If we take a peak at the component that registers a sample dictionary, it looks like this: The Java code equivalent of registering the sample dictionary without DS would look something like this:

...
service = new DictionaryImpl();
// register the service
context.registerService(DictionaryService.class.getName(), service, null);
...

Great, less code we have to write! Now let’s look at a more complicated example of declaring a component that both needs and registers a service: If we had to write this in code, it would involve a ServiceTracker to track the dictionary service, registering our component’s CommandProvider service implementation and code to track dictionary implementations. All in all, it would be quite a chunk of code to keep track of everything. It would get more complicated if we allowed for different cardinality types.

As a reminder, you can also use the DS Tooling in PDE to help craft these component definitions:

Let’s test this example now by launching a new self-hosted instance and checking out the console:

Cool, we can now check for the existence of words in our dictionary using the Equinox console.

Here’s the code used in this example. To test, simply use the ‘Dictionary Example’ launch configuration included:

For a bonus tip, there are console commands to help you debug DS:

---Service Component Runtime---
     list/ls [-c] [bundle id] - Lists all components; add -c to display the complete info for each component;
     use [bundle id] to list the components of the specified bundle
     component/comp  - Prints all available information about the specified component;
     enable/en  - Enables the specified component;
     disable/dis  - Disables the specified component;

Also, I highly recommend using ‘-Dequinox.ds.print=true’ for extra debug information while debugging components that aren’t working like you expect them.

Good luck and I hope this helps! If you want more in depth knowledge of DS, I highly recommend checking out the new Equinox book which showcases an in depth chapter on DS.