Planned changes to the plug-in registry API and implementation

Summary of planned changes:

• Provide API for fragments in the platform registry
• Provide modular way to externalize strings in fragment.xml
• Provide API for checking if a given plug-in descriptor element has been contributed by a fragment

Provide API for fragments in the platform registry

Related bugs:

• Bug 14460 - [runtime] No APIs for obtaining fragments installation directory for a given plugin
• Bug 20499 - Need a public API similer to FragmentDescriptor#getInstallURL()

The platform registry API, whose starting point is the Platform.getPluginRegistry(), provides access to descriptors for the plug-ins in the registry but not for the fragments. Fragments provide objects (pre-requisites, libraries, extensions, extension points) that are combined with those in the plug-in they associate to during the registry resolution process.

Requisites:

• the install URL for a fragment is needed: the general use case is that plug-in's/fragment's code need to know the location of specific files contributed by fragments.

Proposed solution:

• add new API interface org.eclipse.core.runtime.IFragmentDescriptor;
• add new API method URL[] getInstallURL() to IFragmentDescriptor;
• add new API methods IFragmentDescriptor[] getFragments() and IFragmentDescriptor getFragment(String id) to IPluginDescriptor.

Notes:

Currently, clients rely on the fact that the implementations for plug-in registry interfaces in org.eclipse.core.runtime extend the corresponding model classes in org.eclipse.core.runtime.model. This is not specified - we should document if this is expected or disallowed (and we would be able to change the implementation hierarchy for those classes).

Provide modular way to externalize strings in fragment.xml

Related bugs:

• Bug 18617 - [runtime] modular way to externalize strings in fragment.xml
• Bug 18339 - API clarification: where to find translations for labels and provider names for plug-ins and fragments
• Bug 31094 - [About] show real plugin names in 'About'
• Bug 31596 - fragment_*.properties should participate in the plugin resource bundle find path
• Bug 35992 - [runtime] Fragments should know their plug-ins

From Jeem's comments in bug 18617:

"Externalized strings for all plug-in fragments must be placed in the their plug-in's "plugin.properties" resource bundle. In other words, a fragment's strings must be merged into the main plug-in's file. Although this is not very modular, it does at least allow strings to be externalized and translated."

Requisites:

• UI needs to translate fragment name and fragment's provider name to show in the about dialog (bug 31094).
• fragments should be able to have their externalized strings provided by themselves, by the plug-in, or by other fragments (bugs 18617, 31596).

Proposed solution:

From Jeem's comments in bug 18617:

"In order to dovetail with existing mechanisms, each fragment must have its own *.properties files. It would be a non-started if these *.properties files all had the same name (e.g., "fragment.properties"), since all OS-specific fragments would collide on this name making it impossible to spuuly translations for any of they. It is therefore essential that each fragment get a distinctively named *.properties file. The simplest way to arrange this is to add a new attribute to the <fragment> element to specific the name of the properties file; e.g., resource-bundle="win32fragment" would mean that the file named "win32fragment.properties" would contain the translated strings ("win32fragment" is the base name of the property resource bundle, in Java parlance).

The attribute would also be meaningful on a <plugin> element. If the attribute is omitted, the default resource bundle base name is "plugin". This makes the new story upwards compatible with the current story where all "%vars" in the plugin.xml and in all the fragment.xmls get resolved in the plug-in's property resource bundle "plugin.properties"."

Methods in the model objects return strings as they appear in the manifest file. Clients that want those strings properly translated should (as suggested in bug 18339) call IPluginDescriptor#getResolvedString(String) and the new proposed method IFragmentDescriptor#getResolvedString(String).

Also, since the ".properties" file may be anywhere in th plug-in's classpath, the fragment descriptor implementation should ask its plug-in descriptor for the path where to look for it (what requires a fix for bug 35992).

• add new API methods String getLabel(), String getProviderName() and String getResourceString(String) to IFragmentDescriptor - these methods would do the same thing as their counterparts in IPluginDescriptor but would take into consideration the bundle built on the corresponding fragment.properties file;
• the internal implementation for IPluginDescriptor should be refactored in order to share the translation funcionality with the new method getResourceString(String) to be implemented by FragmentDescriptor.

Provide API for checking if a given plug-in descriptor element has been contributed by a fragment

Related bugs:

• Bug 23165 - [runtime] Plug-in model objects should know where they are coming from

Fragments provide objects (pre-requisites, libraries, extensions, extension points) that are combined with those in the plug-in they associate to during the registry resolution process.

Requisites:

• it should be possible to tell apart elements provided by plug-ins from those contributed by fragments: PDE currently casts the IPluginRegistry and IPluginDescriptor to their corresponding model objects (already in memory) to avoid reparsing the manifests. But since the registry is already resolved, PDE does not know which elements were originally part of a plug-in. A simple isFragmentContributed() (in a sense that it is contributed by a fragment) in library, pre-requisite, extension and extension point model objects would be enough. To reduce memory footprint, the PluginModelObject.flags field could be used to store this information.

Proposed solution:

• add new API class FragmentContributableModel (sub-class of PluginModelObject);
• add new API methods boolean FragmentContributableModel.isFragmentContributed() and void FragmentContributableModel.markFragmentContributed();
• make LibraryModel, PrerequisiteModel, ExtensionModel and ExtensionPointModel sub-classes of FragmentContributableModel;
• make PluginModelObject.flags package-private so they can be accessed from FragmentContributableModel.