OSGi uses the META-INF/MANIFEST.MF file (called the manifest file) from the standard Java specification to define its metadata. The Java specification allows additional key-value pairs in this file, which runtimes that do not understand them ignore. Therefore, OSGi plug-ins can be used without restrictions in other Java environments.

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

The following table gives an overview of the OSGi metadata 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) that 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, the symbolic name starts with "com.example".

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

<major>.<minor>.<service>.<qualifier>

The qualifier is optional, Eclipse projects typically use it for a build timestamp.

If you change your plug-in code, increase the version according to the following rules.

For more information on this version scheme, see the Eclipse version numbering guide.

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

The following screenshot shows a 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 screenshot shows an example dependency definition in the Eclipse manifest editor.

A plug-in dependency allows a plug-in to access all exported packages of the other plug-in. A package dependency allows your plug-in to use the classes in this package, independent of 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.

During startup, the OSGi runtime reads the manifest file of the plug-in. The runtime validates if all dependencies are present and can be resolved.

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

If several plug-ins 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 bundle ID is used. The framework assigns this ID to every plug-in during the installation.

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

This lifecycle is depicted in the following graphic.

OSGi allows you to define provisional APIs, that is, packages that can be accessed by other plug-ins but are not yet considered stable. 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.

This results in the following manifest, in which the package is flagged as x-internal.

x-friends also defines provisional API and allows you to define a set of plug-ins that can access the provisional API without a warning or error message. x-friends automatically replaces 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, it plans to keep this API stable for as long as possible.

If an API is marked as provisional, the platform team may change it in future releases. If you use such an API, be prepared to make adjustments to your application when you move to a newer Eclipse release.

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

In Eclipse plug-in development, the Equinox-specific Eclipse-BuddyPolicy header specifies how a bundle (plug-in) can get class-loading assistance from other bundles. The Registered policy requires explicit registration of "buddies" (other bundles) using the Eclipse-RegisterBuddy header.

A bundle that declares Eclipse-BuddyPolicy: Registered in its MANIFEST.MF allows other bundles (buddies) to assist with its class loading, but only if those buddies register themselves via the Eclipse-RegisterBuddy header in their MANIFEST.MF. When the bundle with the Registered policy tries to load a class that is not available in its own classpath, it consults its registered buddies. The buddies are then allowed to attempt to load the class.

The process of class loading is the following:

OSGi declarative services (DS) allow you to define and consume services via metadata. Tooling generates this metadata based on annotations in your source code.

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 components can be:

The following table gives an overview of the OSGi DS terminology. You can skip it and return to it when you need to look up a definition.

Sometimes you need to access information about the bundle, for example, the bundle version or the bundle name. Use the FrameworkUtil class from the OSGi framework to access the Bundle and its BundleContext for a class.

To activate a service immediately after its dependencies are satisfied, use @Component(immediate = true).

You need to ensure that the org.apache.felix.scr plug-in is started before any application plug-in that 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 to a value lower than 4 (4 is the default) for the org.apache.felix.scr plug-in.

If you start an Eclipse RCP application via a product, the required plug-ins for declarative services are started automatically. In this case, you do not need to 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 provides the implementation for this service. This allows you to change the implementation of the service via a different plug-in.

A plug-in that provides a service must be in its ACTIVE lifecycle status. Therefore, ensure that the Activate this plug-in when one of its classes is loaded flag is set in the MANIFEST.MF file. The DS annotation support in Eclipse sets this flag automatically, if you use the default settings.

OSGi services have their own lifecycle, the following states are possible:

If the bundle is started, the Service Component Runtime (SCR) checks if the bundle contains component descriptions. It does this by searching for the Service-Component header in the MANIFEST.MF file. If it finds one, it processes the component description and creates a component configuration. If the configuration is enabled, it checks for required references and configurations if necessary. If all of these conditions are met, the component can be activated.

An immediate component is activated as soon as its requirements are fulfilled.

In contrast, a delayed component moves to the REGISTERED state and waits for the first request to its provided service. If a component configuration contains dynamic references, the references can rebind in the ACTIVE state, otherwise it is reactivated. If a component configuration becomes unsatisfied (for example, a bound service becomes unavailable), the component configuration is deactivated. A delayed component is also deactivated and returns to the REGISTERED state if no other bundle uses it anymore.

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 defining 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 or terminal to interact with the OSGi console.

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

For example, use the ss command to get an overview of all bundles, their status and their 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 via the run configuration.

To access your application with a Telnet client, add a port to the -console parameter.

-console 5555

Connect to this port with a Telnet client, for example, with telnet localhost 5555. In an OSGi console accessed via Telnet, you can use tab completion and a command history similar to the Bash shell on Linux.

You can also access the OSGi console of your running Eclipse IDE. In the Console view, use the Open Console drop-down button in the view toolbar and select Host OSGi Console.

Interfering with your running Eclipse IDE via the OSGi console may put the Eclipse IDE into a bad state.

To develop Eclipse plug-ins and applications, you need to download an Eclipse IDE suitable for this task. The Eclipse project offers multiple downloads specifically for this purpose. The most commonly used options are:

This chapter describes both alternatives, with the SDK download being the recommended one.

Create a simple plug-in project named com.vogella.tasks.model via File  New  Other…​  Plug-in Development  Plug-in Project.

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 using a template.

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

Generate two constructors:

Use the Source  Generate Constructor using Fields…​ menu entry for this.

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 Task class based on the id and summary fields.

Use the Source  Generate hashCode() and equals()…​ menu entry to generate the hashCode() and equals() methods based on the id field. Select the Use Objects.hash and Objects.equals methods (1.7 or higher) option.

Add the following copy() method to the class.

To refer to the fields of Task later, 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 implement and use an OSGi service that 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 that uses this plug-in.

To share your 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 on them.

Open the MANIFEST.MF file of the com.vogella.tasks.services plug-in. Select the Dependencies tab and add the com.vogella.tasks.model package to the Imported Packages section.

On the MANIFEST.MF tab, the file should look similar to the following listing.

To generate OSGi service metadata based on annotations in classes, enable the Generate descriptors from annotated sources option under Window  Preferences  Plug-in Development  DS Annotations.

The implementation uses the @Component annotation. PDE adds the DS annotations to the build path of the plug-in automatically, so you do not need to import their package in the MANIFEST.MF file.

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

The test data uses due dates relative to today and marks some tasks as done, so later exercises have overdue, due, upcoming and done tasks to show.

PDE writes this metadata as an XML file into the OSGI-INF folder of the plug-in. Ensure that OSGI-INF/ is selected in the Binary Build section of the Build tab of the manifest editor, otherwise the exported plug-in does not contain the component description.

The full manifest looks similar to the following listing.

Add your new plug-ins to your feature.

Ensure that you use the Included Plug-ins tab of the feature.xml editor. Start your application via your product configuration to ensure that the plug-ins added to the feature are correctly included in the runtime.

By default, the OSGi runtime initializes and provides services on demand. Therefore, an OSGi service only starts once it is consumed. This is done in the next exercises.

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

Add the com.vogella.tasks.model package dependency in the manifest to use the TaskService interface. The @Component annotation needs no manifest entry, PDE adds the DS annotations to the build path automatically.

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 tasks 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 populate 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 org.eclipse.osgi.framework.console package as imported package dependency to its manifest.

To extend the OSGi console, provide 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 that takes two parameters.

Add the new plug-ins to your product (via your feature configuration). 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.

Add the following plug-in dependencies to your test fragment.

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.

In the above test you did not 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.

To publish a service in your bundle, use the following code.

In the registerService() method of the BundleContext class, you can specify arbitrary properties in the dictionary parameter. Consumers read a property via the getProperty() method of the ServiceReference class from the org.osgi.framework package.

To remove the service from the service registry, call unregister() on the returned ServiceRegistration.

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

The getServiceReference() method returns null if no such service is registered.

OSGi counts the usage of services to enable their dynamic replacement. Once your implementation no longer uses a service, release it as shown in the following code.

A bundle can define an activator class via the Bundle-Activator header in its manifest. This class must implement the BundleActivator interface. OSGi passes the BundleContext to its start() and stop() methods.

If you need more assistance we offer Online Training and Onsite training as well as consulting

See License for license information.