This tutorial describes the purpose and usage of Eclipse fragment projects

1. Using fragment projects

1.1. What are fragments in OSGi?

A fragment is an optional attachment to another plug-in. This other plug-in is called the host plug-in. At runtime the fragment is merged with its host plug-in. Therefore, for the Equinox runtime both projects are just one.

Fragments are always optional for their host plug-in and the host plug-in doesn’t even know that it exists.

The Eclipse IDE supports the creation of fragments via fragment projects. To create a fragment project select File  New  Other…​  Plug-in Development  Fragment Project.

1.2. Typical use cases for fragments

Fragments can be used to contain test classes. This way the tests can access the internal API of the plug-in classes and test it. Tests can also be contained in their own plug-in. In this case, they can only test the external API of other plug-ins.

Fragments are also used to contribute property files for additional translations. This allows contributing translation for a new language without the need to adjust other part of the code.

In addition, fragments can also provide native code which is specific to certain operating system (OS). In this case a platform filter is used to define that the fragment is only valid a certain OS.

For example, the SWT user interface implementation of Eclipse uses this approach.

Last but not the least, fragments can be used to contain resources like icon sets or other images. This allows you to customize your application icons via the provided fragment.

1.3. Example manifest for a fragment

The following lists a fragment only valid for the Windows OS. The OS is specified via the Eclipse-PlatformFilter property and the Fragment-Host makes this a fragment. If you remove Fragment-Host, the component is a regular plug-in again.

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: %fragmentName
Bundle-SymbolicName: org.eclipse.ui.win32
Bundle-Version: 3.4.300.qualifier
Bundle-ClassPath: .
Bundle-Vendor: %providerName
Fragment-Host: org.eclipse.ui.ide;bundle-version="[3.2.0,4.0.0)"
Bundle-Localization: fragment-win32
Export-Package: org.eclipse.ui.internal.editorsupport.win32;x-internal:=true
Eclipse-PlatformFilter: (osgi.ws=win32)
Bundle-RequiredExecutionEnvironment: JavaSE-1.8
Automatic-Module-Name: org.eclipse.ui.win32

The available platforms filters are: * Eclipse-PlatformFilter: (osgi.ws=win32) * Eclipse-PlatformFilter: (osgi.ws=gtk) * Eclipse-PlatformFilter: (osgi.ws=cocoa)

Nothing listed.

3. vogella training and consulting support

Copyright © 2012-2019 vogella GmbH. Free use of the software examples is granted under the terms of the Eclipse Public License 2.0. This tutorial is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Germany license.