Eclipse Plug-in Customization

Last revised 19:00 Wednesday May 22, 2002

This note describes how an Eclipse-based product can customize any of the plug-ins installed in the product.

What product developers need to know

Any plug-in may choose to expose preferences or internal configuration parameters that are intended to be given product-specific default settings to better tailor that plug-in for the product's operating environment.

Product-specific customization is controlled from the product's primary feature through the file named "plugin_customization.ini" located within the primary feature's plug-in (a java.io.Properties format file). Only the primary feature gets to do this; other features have no say. The keys in the plugin_customization.ini  file are a property name qualified by the id of the plug-in; for example, the property named "defaultPerspectiveId" in the plug-in with id "org.eclispe.ui" is written "org.eclipse.ui/defaultPerspectiveId". The specified value overrides the default preference value specified by a plug-in. For user preferences, the default override determines the setting that will be used if the user states no preference (or asks to restore defaults). For internal preferences, the default override determines the setting that will be used (since the user has no say).

Translatable strings in "plugin_customization.ini" should be extracted into a companion "plugin_customization.properties" file. The "plugin_customization.properties" file is looked for in NL-specific subdirectories within the feature plug-in or fragment thereof.

No error is reported for a setting that specifies a non-existent plug-in; the default setting will be overridden in any configuration in which the plug-in is configured, and ignored in all others. 

The plug-in customization mechanism does not cause plug-in activation; rather, the default setting is applied the first time a plug-in's preference object is accessed.

What product developers do not need to know

N.B. The details in this section are not Eclipse platform API, and may change over time. Do not rely on anything described in this section.

Individual plug-ins often define user preference settings with pre-wired default values.

Plug-ins present their user preferences to the user via the workbench. The preferences start out at their pre-wired default values. Any settings that the user changes are saved by the plug-in in its internal preference settings file (located in the plug-in's state area, at <workspace>/.metadata/.plugins/<plug-in id>/pref_store.ini). The most recent settings are used when the Eclipse platform is re-launched and the plug-in reactivated.

More generally, a plug-in may also have internal preference settings that are never exposed to the user. For example, a plug-in might be pre-configured with a particular URL where the user would be directed for support (or whatever). Internal preference settings are even simpler than user preference settings because there is never a need to save values - everything works from pre-wired defaults.

In 1.0, preference settings are supported by UI API (on AbstractUIPlugIn), and is therefore something that is limited to UI plug-ins. There is also an undocumented (and consequently unused) mechanism for overriding these default settings.

The changes for 2.0 are as follows: make preference settings available to all plug-ins; provide a simple mechanism that allows a plug-in's preference default values to be externally configured by a product packager through the primary feature; and provide a simple mechanism that allows plug-in preference default values for a packaged product to be externally configured (e.g., by in house teams creating site-specific product installs).

• New Core API in Platform Runtime to support preferences.
  • These are based existing JFace preference and preference store APIs and implementation (based in turn on java.util.Properties.), API and implementation in AbstractUIPlugIn.
  • All default preference settings are expected to be supplied by plug-in itself.
  • Keys are simple name of preference; e.g., "mypref"
  • Plug-in code may set initial default preference values to hard-wired values.
  • Additional default preference value are retrieved from a known read-only file (e.g., "preferences.ini") in the plug-in's root directory (same format as other property settings).
    • Strings are localized using mechanism like plugin.xml/plugin.properties
    • i.e., translatable strings extracted to "preferences.properties" file
  • Default values from file override defaults hard-wired in code.
    • Makes it easy for plug-in writers to configure default preference values without changing code.
• Primary feature supplies preference default overrides.
  • The primary feature is provided by the product packager.
  • This mechanism is for the product packager to customize the plug-ins included in the product.
  • Keys consist of "/'-separated plug-in id and name of preference; e.g., "com.example.myplugin/mypref".
  • A preference default override replaces the default preference value specified by a plug-in.
  • For user preferences, the default override determines the setting that will be used if the user states no preference (or asks to restore defaults).
  • For internal preferences, the default override determines the setting that will be used (since the user has no say).
  • Primary feature's preference default overrides are stored in a properties file with feature (same format as other property settings).
    • Root file in plug-in (or fragment) for feature is named "plugin_customization.ini"
    • Strings are localized using mechanism like plugin.xml/plugin.properties
    • i.e., translatable strings extracted to "plugin_customization.properties" file
• Allow additional preference default overrides to be supplied via the Eclipse command line.
  • This mechanism is for additional after-market product customization.
  • Allows in-house teams to provide site-specific customization (e.g., URL of team repository).
  • Preference default overrides specified on command line should have precedence over preference default overrides from primary feature.
  • Command line option is "-pluginCustomization" followed by a file name 
  • Keys are same as for product packager; e.g., "com.example.myplugin/mypref".

To summarize, the value of a preference named "mypref" from plug-in "com.example.myplugin" is arrived at as follows:

1. A user stated preference value for "mypref", if any. (Persisted in a file in the state are plug-in com.example.myplugin.)
2. A default value:
   1. An override value from after-market customization for "com.example.myplugin/mypref", if any.
   2. An override value from primary feature for "com.example.myplugin/mypref", if any.
   3. A default value for "mypref" as determined by plug-in com.example.myplugin, if any.
      1. A default value for "mypref" from a read-only file found in the root directory of the plug-in, if any.
      2. A default value for "mypref" from code in the plug-in, if any.
   4. The default-default value (i.e., 0 for numbers, false for booleans, empty string for strings, etc.).