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 you to contribute translation for a new language without the need to adjust other parts of the code.

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

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

Last but not 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.

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