PDE/DS Annotations

OSGi Declarative Services (DS) provide a powerful mechanism for developing dynamic, service-oriented applications. Instead of each bundle having to manage the lifecycle, dependencies, and configuration of services on its own, the Service Component Runtime (SCR) can handle all of that for DS Components described using an XML file.

To facilitate the generation and maintenance of Component descriptor files, DS specification includes a set of Java annotations that developers can apply to their Component implementation classes and use them to declare dependencies on other services, define configuration properties and their default values, and designate Component lifecycle methods.

When enabled, PDE tracks Java classes annotated with DS Annotations, validates them, and generates the requisite XML files and bundle manifest entries.

As of Oxygen release, PDE supports DS Annotations version 1.3 in full.

Configuration

You can enable support for DS Annotations for individual projects or the entire workspace by checking Generate descriptors from annotated sources for the appropriate scope:

Workspace:

Open Preferences -> Plug-in Development -> DS Annotations

Project:

Open the project's Properties -> Plug-in Development -> DS Annotations

In both cases, you can customize a number of settings:

Descriptor directory:

Bundle-root-relative path to a directory where PDE generates the XML files. Note that this directory must be included in your bundle's Binary Build in build.properties. By default, it is OSGI-INF.

Add DS Annotations to classpath:

If checked, PDE automatically places the appropriate version of DS Annotations on your project's classpath used by JDT in Eclipse workbench; however, you may still need to include DS Annotations in your project's classpath through other means (see below).

Specification version:

Version of DS Annotations to use. For instance, you may need to downgrade to an earlier version if your deployment environment does not include the latest SCR implementation.

Annotation problem level:

PDE can report any validation problems found in your annotations as Errors or Warnings, or it can completely skip validation (i.e., Ignore).

Missing implicit dynamic reference unbind method:

Dynamic references declared by annotating a bind method should have a corresponding unbind method, which need not be designated explicitly (i.e., if it follows the expected naming convention). However, if a developer makes a mistake when naming that method, or the two methods get out of sync during refactoring, PDE can flag this condition before it causes unexpected problems at runtime.

Generate header "Bundle-ActivationPolicy: lazy":

If checked, PDE adds the corresponding header to the bundle manifest. This is a recommended practice, but not a requirement (i.e., in some cases the developer may want to explicitly activate the bundle when needed).

Adding DS Annotations to classpath

In order to build your annotated code, the compiler needs to resolve the correct version of DS Annotations from your bundle project. Since DS Annotations are only used at design-time (i.e., by your build tools), they are not meant to be (and are typically not) packaged with your application for deployment.

PDE includes every supported version of DS Annotations library and can automatically place the corresponding JAR on your project's classpath used by JDT in Eclipse workbench. However, when building outside of the Eclipse workbench (e.g., using Maven/Tycho, or even the Ant-based PDE Export functionality), that build tool may not see this classpath contribution, since it likely uses other means of inferring the bundle project's classpath (such as package imports, required bundles, custom build properties, etc.)

PDE will warn you if it fails to detect an explicitly contributed DS Annotations library in your project's classpath and offer several Quick Fix options to address this condition. For instance, you can add a PDE-supplied JAR file as an Extra Classpath Entry in your build.properties, or you can include a PDE-supplied bundle with DS Annotations in the Automated Management of Dependencies section. Note that in both cases you must ensure that the referenced PDE bundles are included in your Target Platform.