OSGi uses the META-INF/MANIFEST.MF file (called the manifest file) from the standard Java specification to define its meta information. The Java specification defines that additional key/values can be added to this file without affecting runtimes which do not understand these key/value combinations. Therefore, OSGi plug-ins can be used without restrictions in other Java environments.

The following listing is an example for a manifest file containing OSGi metadata.

The following table gives an overview of the OSGi meta-data used in the manifest file.

The combination of Bundle-SymbolicName and Bundle-Version uniquely identifies a plug-in.

Each plug-in has a unique name (id) which is defined via the Bundle-SymbolicName property. By convention, this name uses the reverse domain name of the plug-in author. For example, if you own the "example.com" domain then the symbolic name would start with "com.example".

Each plug-in defines its version number in the Bundle-Version property. OSGi recommends to use the following schema for versions in the Bundle-Version field identifier.

<major>.<minor>.<patch/service>

If you change your plug-in code you increase the version according to the following rule set.

For more information on this version scheme see the Version Numbering Wiki.

A plug-in defines its API via the Export-Package identifier in its manifest file. All packages which are not explicitly exported are not visible to other plug-ins.

The following screenshot shows one plug-in which exports one package as API in the Eclipse manifest editor.

To access classes from another plug-in A in the source code of your plug-in B you need to:

The following screenshots shows an example dependency definition in the Eclipse manifest editor.

A plug-in dependency allows a plug-in to access all exported packages from this plug-in. A package dependency allows your plug-in to use the classes in this package, independent which plug-in provides it.

A plug-in can define that it depends on a certain version (or a range) of another plug-in. For example, plug-in A can define that it depends on plug-in C in version 2.0. Another plug-in B can define that it depends on version 1.0 of plug-in C.

The OSGi runtime reads the manifest file of a plug-in during startup. It ensures that all dependencies are present and can also check their dependencies.

If all required dependencies are resolved, the plug-in is in the RESOLVED status otherwise it stays in the INSTALLED status.

In case several plug-ins exist which can satisfy the dependency, the plug-in with the highest valid version is used.

If the versions are the same, the plug-in with the lowest unique identifier (ID) is used. Every plug-in gets this ID assigned by the framework during the installation.

When the plug-in starts, its status is STARTING. If a plug-in sets the lazy flag to true in its manifest, the Equinox runtime moves that plug-in to the ACTIVE state, if one of its classes or interface is used. In this state the plug-in can provide OSGi services in Equinox.

This life cycle is depicted in the following graphic.

OSGi allows you to define provisional API, i.e. packages which can be accessed by other plug-ins but are not yet defined as API. This can be done via the x-internal or the x-friends flag.

The following screenshot shows how to define a package as provisional API.

Such a setting would result in the package flagged as x-internal.

x-friends also defines provisional API but also allows you to define a set of plug-ins which can access the provisional API without a warning or error message. x-friends replaces automatically x-internal if you use the Eclipse manifest editor and add a plug-in to the Package Visibility section on the Runtime tab.

The Eclipse platform project marks almost all packages either as public API or as provisional API. If the Eclipse platform project releases an API, the platform project plans to keep this API stable for as long as possible.

If API is marked as provisional, the platform team can change this API in the future. If you use such API, you must be prepared that you might have to make some adjustments to your application in a future Eclipse release.

If you use unreleased API, you see a Discouraged access: The …​is not API (restriction on required project …​) warning in the Java editor.

The OSGi declarative services (DS) allows you to define and consume service via meta-data. Tooling allows you to generate service metadata based on annotations in your source code, we cover this in the exercises for the Eclipse IDE.

The following is an example of using an annotation to define an OSGi service. It provides a service implementation for the TaskService interface.

The annotation is used to generate an XML file, which is read once the plug-in gets activated.

OSGi service definitions can be:

The following table gives a brief overview of the OSGi ds terminology, you can skip this table and return to it, in case you want to lookup a definition.

Sometimes you need to access information about the bundle, e.g., the bundle version or the bundle name. Access to the bundle and its bundleContext is performed via the Bundle and BundleContext class.

You can use the FrameworkUtil class from the OSGi framework to access the BundleContext for a class.

If you want to activate a service immediately after its dependencies are satisfied, the immediate parameter to the @Component annotation can be used.

You need to ensure that the org.apache.felix.scr plug-in is started before any application plug-in which wants to consume a service.

You can ensure this in your run configuration by setting the auto-start field to true and the start level lower than 4 (4 is the default value) for the org.apache.felix.src plug-in

The Eclipse RCP framework automatically starts the required plug-ins for using declarative OSGi service. It is not required to manually set a start level in your product configuration file.

It is good practice to define a service via a plug-in which only contains the interface definition. Another plug-in would provide the implementation for this service. This allows you to change the implementation of the service via a different plug-in.

OSGi service can define dependencies to other services. You can use the @Reference annotation to define (so-called event) methods to bind to these services and to update them. You can also use it on fields.

The bind event methods are typically prefixed with either bind, set or add. The unbind method should have the corresponding prefixes unbind, unset or remove, so they are automatically picked up by @Reference. T

OSGi allows to define multiple service implementations. To define the importance of them, it is possible to define a ranking for a service.

This is done via a service property, called service.ranking. By default, the service ranking is zero, the higher the ranking the more important is the service. The ranking order is defined as follows:

Sorted on descending ranking order (highest first) If the ranking numbers are equal, sorted on ascending service.id property (oldest first)

You can specify these properties via the @ServiceRanking annotation or the property value.

Frameworks like the Eclipse dependency injection framework automatically inject the service with the highest service ranking.

As OSGi service component can be configured via key-value pairs (properties). These are accessed via a Map<String, Object>. These properties can be defined via the following ways:

These configurations options are processed in the above order, so a Java properties file can override inline configuration. The first three options are demonstrated in a later exercise.

If you specify the -console parameter in your run configuration, you can use a console / terminal to interact with the OSGi console.

The OSGi console is like a command-line shell. In this console you can type a command to perform an OSGi action. This can be useful to analyze problems on the OSGi layer of your application.

Use, for example, the command ss to get an overview of all bundles, their status and bundle-id. The following table is a reference of the most important OSGi commands.

The following plug-ins are necessary to use the OSGi console. The easiest way to add them to your Eclipse application is to add them directly via the runtime configuration.

If you want to access your application via a Telnet client, you can add another parameter to the -console parameter. This specifies the port to which you can connect via the telnet protocol.

-console 5555

To access such a application, use a telnet client, for example on Linux: telnet localhost 5555 from the command line. In an OSGi console accessed via telnet, you can use tab completion and a history of the commands similar to the Bash shell under Linux.

You can also access the OSGi console of your running Eclipse IDE. In the Console View you find a menu entry with the tooltip Open Console. If you select Host OSGi Console, you will have access to your running OSGi instance.

Please note that interfering with your running Eclipse IDE via the OSGi console, may put the Eclipse IDE into a bad state.

The Eclipse IDE provides multiple downloads which can be used to develop Eclipse based applications and plug-ins. The most commonly used are:

Download either one of them. The packages include a Java runtime, no additional download is needed for them.

We describe two alternatives:

Create a simple plug-in project via the File  New  Other…​  Plug-In Development  Plug-In Project menu entry with the following name:

The following screenshot depicts the second page of the plug-in project wizard and its corresponding settings.

Press the Finish button on this page to avoid the usage of templates.

Create the com.vogella.tasks.model package and the following model class.

Generate two constructors:

You can do this via the Select Source  Generate Constructor using Fields…​ menu entry.

Use the Source  Generate Getter and Setter…​ menu to create getters and setters for your fields.

At this point the resulting class should look like the following listing.

Use the Source  Generate toString()…​ menu entry to generate a toString() method for the Todo class based on the id and summary field.

Use the Source  Generate hashCode() and equals()…​ menu entry to generate the hashCode() and equals() methods based on the id field. If possible prefer the 1.7 version, but also without this flag the generated methods are fine.

Add the following copy() method to the class.

To access later the fields on Task create the following constants in the class.

The resulting Task class should now look similar to the following.

Create the following TaskService interface.

Export the com.vogella.tasks.model package to define it as API.

For this, open the MANIFEST.MF file and select the Runtime tab. Add com.vogella.tasks.model to the exported packages.

In the following exercises, you will implement and use an OSGi service which uses this data model.

Select Run  Run Configurations…​ from the top-level menu. Select OSGi Framework and press the new button.

On the Bundles tab, deselect all existing selection and add the following framework plug-ins:

Also add your plug-in to the runtime.

As a result the following bundles should be selected.

Switch to the Arguments tag.

The generated run configuration uses the -console parameter by default. Also it specifies the VM argument, eclipse.ignoreApp and osgi.noShutdown.

Press the Run button to start your OSGi runtime.

By default, this starts an OSGi runtime with your modules.

As you specified the `-console ` parameter, you can use OSGi console commands.

Type ss into the console view to get an overview of the plug-ins and their status. The model plug-in should be listed and in RESOLVED or in the ACTIVE status, if the Default Auto-Start setting on the Bundles tab is set to true.

In the next exercise you define an OSGi service which uses this plug-in.

To share you run configuration, you can also save the file.

As you specified the osgi.noShutdown=true flag, the OSGi application will not shutdown. This is useful if the OSGi instance provides services to the outside.

Use the exit command or the terminate button to terminate the running instance.

If you have multiple instance running, you can use the drop-down button in Eclipse to switch to them.

Create a new simple plug-in project called com.vogella.tasks.services.

To use classes from other plug-ins in a plug-in, you need to add a dependency to them.

To achieve this, open the MANIFEST.MF file of the com.vogella.tasks.services plug-in. Select the Dependencies tab and add the following to the Imported Packages selection:

Select the org.osgi.service.component.annotations and press Properties…​.

Mark this package as Optional and ensure you specify the highest available number (currently 1.3.0) as minimun requirement.

The result should look similar to the following screenshot.

The text file should look similar to the following.

You want to generate OSGi service metadata based on annotations in classes. For this, enable the option under Window  Preferences  Plug-in Development  DS annotations.

Create the com.vogella.tasks.services.internal package in your service plug-in and create the following class.

The service implementation should define the information for the runtime, that is provides the service. You can do this via the following entry in the manifest.

Provide-Capability: osgi.service; objectClass=com.vogella.tasks.model.TaskService

The full manifest looks similar to the following listing:

Add this new plug-in to your product (via the feature).

By default, the OSGi runtime initializes and provides OSGi services on demand. Hence you need to consume the OSGI service to start it. This is done in the next exercises.

Create another simple plug-in named com.vogella.osgi.taskconsumer.

Add the required package dependencies in the manifest to use the TaskService interface and the @Component annotation. See below solution for the correct entry.

Use the @Component annotation to add another OSGi component via a class named TaskConsumer.

Receive the TaskService the @Reference annotation, either on a field or on a method.

Also implement a method annotated with the @Activate annotation to write to the number of task to the console. This tasks can be received from the service.

Also add Require-Capability: osgi.service;filter:="(objectClass=com.vogella.tasks.model.TaskService)" to your MANIFEST.MF, indicating that such a service is required for this plug-in to work. The resulting MANIFEST should look like the following, Service-Component and Bundle-ActivationPolicy are added by the tooling.

Add the new plug-in to your product via your feature.

Start again via the product and ensure you see the output of the @Activate on the console.

Remove the System.out statements in TaskConsumer, these are only useful to demonstrate the functionality but should be removed to avoid unnecessary output on the console in future exercises.

Create a feature project named com.vogella.osgi.feature via File  New  Other…​  Plug-in Development  Feature Project.

If you have already an existing launch configuration you can use that to popular the feature.

Open the feature.xml file and switch to the _Included Plug-ins` tag. Ensure the following framework plug-ins are included in your feature.xml file:

Also ensure that your plug-in is part of the feature.

Create a new project named com.vogella.osgi.runtime of type General via the Menu  File  New  Project  General  Project menu entry.

Right-click on the com.vogella.osgi.runtime project and select New  Other…​  Plug-in Development  Product Configuration.

Create a product configuration file called osgi-runtime.product inside the main folder of the project using basis settings.

Press the Finish button. The file is created and opened in an editor.

On the Overview tab ensure the following settings:

Leave the product and application empty. Product and Application are used in RCP products, and therefore not needed for a headless OSGi command line application.

Also set that the product is based on features.

On the Contents tab, add your feature as content.

Configure the Start Levels:

Configure the following properties:

The above configuration is used for the exported application. You also have to configure the parameters for the start from the IDE.

Add on the Launching tab:

Click on the Run button to start your OSGi command line application.

Create a new plug-in named com.vogella.osgi.console.

Add the following imported package dependencies to its manifest:

As always, mark org.osgi.service.component.annotations as optional.

To extend the OSGi console, provide new new class AndQuitCommand implements org.eclipse.osgi.framework.console.CommandProvider as OSGi component via the @Component annotation.

Add methods prefixed with _ are available as additional commands.

For example, you can add the following method to provide the add command which take two parameters.

Add the new plug-ins to your product (via the feature). Start via the product to ensure that it is added to the run configuration.

Check that you can use your new commands in the OSGi shell, e.g. add 1 2 or quit.

Add the following to your target platform from the https://download.eclipse.org/releases/latest update site: The easiest way to do this is to use the Source tab of the target editor which also provides code completion.

Create a new fragment project called com.vogella.tasks.services.tests via the File  New  Other…​  Plug-in Development  Fragment Project menu entry.

Enter com.vogella.tasks.services as host plug-in.

First you implement a unit test, without considering the OSGi environment.

Right-click on the project and select New  Other…​  Java  JUnit Test Case.

Also add JUnit 5 to your build path.

Implement the following class.

Right-click the test and select Run-as  JUnit test. The tests should both execute successfully.

To access the OSGi API for service in your test, add the following plug-ins as plug-in dependencies to your test plug-in.

org.junit is necessary to avoid java.lang.ClassNotFoundException: org.apache.maven.surefire.junitplatform.JUnitPlatformProvider for JUnit 5 tests. See Bug report

The osgi and felix plug-in are required as runtime to provide the OSGi runtime and the OSGi ds component.

In the above test you didn’t use the OSGi service layer but initialized the service yourself. In the next test, you will test if the OSGi server layer correctly initialized the service. This is especially necessary if the services to test reference other services or OSGi features are used, like the EventAdmin for event processing or the ConfigurationAdmin to configure components at runtime.

Create the following unit test.

Add your test plug-in as module to an existing Tycho build. In case you are using pomless builds, this should allow to execute the tests on the command.

The test plug-in should successfully execute the tests.

A bundle can also register itself for the events(ServiceEvents) of the BundleContext. These are, for example, triggered if a new bundle is installed or de-installed or if a new service is registered.

To publish a service in your bundle use:

Once the service is no longer used, you must unregister the service with OSGi. OSGi counts the usage of services to enable the dynamic replacement of services. So once the service is no longer used by your implementation, unregister it. This is demonstrated by the following code:

In the registerService() method from the BundleContext class you can specify arbitrary properties in the dictionary parameter.

You can use the getProperty() method of the ServiceReference class from the org.osgi.framework package, to access a specific property.

A bundle can acquire a service via the BundleContext class. The following code demonstrates that.

A bundle can define a Bundle-Activator (Activator) in its declaration. This class must implement the BundleActivator interface.

If defined, OSGi injects the BundleContext into the start() and stop() methods of the implementing Activator class.