16.3. Using Fragments

All the translated properties files could be included in the main plug-in, but this is less than ideal in a situation where the translations will be delivered later than the product itself. If all the translated files need to be included with the main plug-in, you would either need to delay the release of the main plug-in or rerelease it when the translations are available. Fortunately, Eclipse includes a mechanism called a plug-in fragment that provides an elegant solution to this problem.

Fragments are used to extend the functionality of another plug-in. Fragments are typically used to supply alternative language packs, maintenance updates, and platform-specific implementation classes. When a fragment is loaded, its features and capabilities are merged with those of the base plug-in such that they appear to have come from the base plug-in itself.

The developer does not need to know whether the plug-in or one of its fragments contributes a specific resource because the plug-in class loader handles this transparently. This makes it easy to deliver translated versions of plug-in files (e.g., HTML, XML, INI, and properties files) independently of the main plug-in.

The properties files follow the resource bundle-naming rules (as noted earlier). Other resources, such as HTML, XML, and INI files are placed into nl/<language> or nl/<language>/<country> directories, where <language> and <country> represent the two-letter codes used to signify the language and country (this directory structure was first introduced in Section 15.2.3, Table of contents (toc) files, on page 548).

16.3.1. New Fragment Project wizard

Creating a new fragment is easy using the New Fragment Project wizard. From the File menu, select New > Project to launch the new project wizard (see Figure 16-8). On this first page of the wizard, select Plug-in Development > Fragment Project, followed by the Next button.

On the next page of the wizard (see Figure 16-9), enter the name of the project; in this case, it should be "com.qualityeclipse.favorites.nl1", which is the same as the plug-in fragment identifier. The Eclipse convention is to name a plug-in fragment project that contributes national language support to a base plug-in with the same name as the base plug-in plus the suffix ".nl1". Click the Next button.

The Fragment Content page (see Figure 16-10) provides fields to name the fragment, set its ID and version number, and identify the plug-in ID and version that it extends. Use the Browse... button to select the plug-in, if necessary. In this case, you want to extend the existing com.qualityeclipse.favorites plug-in (see Figure 16-11).

The choices available in the Match Rule field control the versions of the associated plug-in that can be extended.

• Perfect means that the base plug-in exactly matches the supplied version number.

• Equivalent means that the version may differ at the service or qualifier level.

• Compatible means that plug-in may have a newer minor version number.

• Greater or Equal means that the plug-in may have any newer version number. This is the option you should normally choose.

Choose the Greater or Equal option and click the Finish button to complete the wizard and generate the fragment manifest file.

16.3.2. Fragment manifest file

Double-clicking in the fragment manifest file, MANIFEST.MF, will open the fragment manifest editor (see Figure 16-12). The editor looks very similar to the plug-in manifest editor with Overview, Dependencies, Runtime, Extension Points, etc. pages.

Figure 16-12. Fragment manifest editor.

[View full size image]

If you switch to the Runtime page (see Figure 16-13), you will see that nothing is included in the runtime classpath for the fragment. Various files, such as translated HTML, XML, and INI files, are located in specially named subdirectories based on the associated locale (language and country combination).

Figure 16-13. Fragment Runtime Information page.

[View full size image]

To get those directories to show up in the runtime classpath, click the New... button to add a "New Library" entry to the list. Right-click on that entry and Rename it to "$nl$/". This is special syntax that will cause the system to substitute the correct classpath entry at runtime based on the current locale. If the locale is set to Germany, for example, "$nl$" would be substituted by "de", and the "de/" subdirectory would be added to the runtime path.

Next, let's switch to the MANIFEST.MF page and take a look at the generated text:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Favorites NLS Fragment
Bundle-SymbolicName: com.qualityeclipse.favorites.nl1
Bundle-Version: 1.0.0
Bundle-Vendor: QualityEclipse
Fragment-Host: com.qualityeclipse.favorites;
    bundle-version="1.0.0"
Bundle-Localization: plugin
Bundle-ClassPath: $nl$/

This source is very similar to what you would expect to see for a plug-in. The first major difference is that fragments don't have their own plug-in lifecycle (they conform to the lifecycle of their associated plug-in), and thus, they don't need their own Bundle-Activator attribute. The second difference is that the fragment does not declare any of its own dependencies (again, they are inherited from the associated plug-in).

The interesting attributes relative to those found in full plug-ins are the Fragment-Host and the bundle-version attributes. The Fragment-Host identifies the plug-in that this fragment will extend. The bundle-version specifies the version of the target plug-in that this fragment expects to be able to extend.

16.3.3. Fragment project contents

The last thing you need to do is add all the translated files to the appropriate directories within the fragment project folder (see Figure 16-14). Assuming that you want to supply German and French translations of various files, the project would have nl/de and nl/fr directories to contain any translated HTML, XML, and INI files (like those mentioned in Section 15.2.3, Table of contents (toc) files, on page 548).

The translated versions of the plugin.properties files are placed at the root of the fragment, and the translated versions of the messages.properties files are placed in the com.qualityeclipse.favorites.views directory.