This chapter is from the book
This chapter is from the book
This chapter is from the book
3.4 Plug-in Class
By default, the plug-in class or Bundle-Activator provides methods for accessing static resources associated with the plug-in, and for accessing and initializing plug-in-specific preferences and other state information. A plug-in class is not required, but if specified in the plug-in manifest, the plug-in class is the first class notified after the plug-in loads and the last class notified when the plug-in is about to shut down (see Section 3.5.2, Plug-ins and Bundles, on page 120 and the source code listing in Section 2.3.2, The Plug-in class, on page 77).
3.4.1 Startup and shutdown
The plug-in loader notifies the plug-in class when the plug-in is loaded via the start() method and when the plug-in shuts down via the stop() method. These methods allow the plug-in to save and restore any state information between Eclipse sessions.
3.4.2 Early plug-in startup
Eclipse loads plug-ins lazily, so it may not call the start() method when it launches. Eclipse can provide resource change information indicating the changes that occurred while the plug-in was inactive (see Section 9.5, Delayed Changed Events, on page 387). If this is not enough and the plug-in must load and start when Eclipse launches, the plug-in can use the org.eclipse.ui.startup extension point by inserting the following into its plug-in manifest:
<extension point="org.eclipse.ui.startup"> <startup class="myPackage.myClass"/> </extension>
Doing this requires that the myPackage.myClass class implement the org.eclipse.ui.IStartup interface so that the workbench can call the earlyStartup() method immediately after the UI completes its startup. For more on early startup and the issues involved, see Section 20.10, Early Startup, on page 747.
Like most plug-ins, the Favorites plug-in does not need to load and start when Eclipse launches, so it does not use this extension point. If there is a need for early startup, then place only what is necessary for it into a separate plug-in and use the early startup extension point there so that the additional overhead of early startup has only a small impact on startup time and memory footprint.
3.4.3 Static plug-in resources
Plug-ins can include images and other file-based resources that are installed into the plug-in directory along with the plug-in manifest and library file. These files are static in nature and shared between multiple workbench incarnations. Declarations, such as actions, views, and editors, in the plug-in manifest can reference resources such as icons stored in the plug-in installation directory. Additionally, the plug-in class provides methods for locating and loading these resources:
- find (IPath path)— Returns a uniform resource locator (URL) for the given path or null if the URL could not be computed or created.
- openStream (IPath file)— Returns an input stream for the specified file. The file path must be specified relative to the plug-in's installation location (the plug-in directory).
3.4.4 Plug-in preferences
Plug-in preferences and other workspace-specific state information are stored in the workspace metadata directory hierarchy. For example, if Eclipse is installed at C:\eclipse and the default workspace location is being used, then the Favorites preferences would be stored in:
C:/eclipse/workspace/.metadata/.plugins
/com.qualityeclipse.favorites/pref_store.ini
The plug-in class provides methods for accessing plug-in preferences and other state-related files as follows:
- getPluginPreferences()— Returns the preference store for this plug-in (see Section 12.3, Preference APIs, on page 467).
- getStateLocation()— Returns the location in the local filesystem of the plug-in state area for this plug-in (see Section 7.5.2, Saving global view information, on page 311). If the plug-in state area did not exist prior to this call, it is created.
- savePluginPreferences()— Saves the preference settings for this plug-in; it does nothing if the preference store does not need saving.
You can supply default preferences to a plug-in in several ways. In order to programmatically define default preference values, override the method initializeDefaultPluginPreferences(). Alternatively, you can specify default preferences in a preferences.ini file located in the plug-in directory (see Section 12.3.4, Specifying default values in a file, on page 472). Using this second approach also lets you easily internationalize the plug-in using a preferences.properties file (see Section 16.1, Externalizing the Plug-in Manifest, on page 576).
3.4.5 Plug-in configuration files
If you need to store plug-in information that needs to be shared among all workspaces associated with a particular Eclipse installation, then use the method Platform.getConfigurationLocation() and create a plug-in specific subdirectory. If Eclipse is installed in a read-only location, then Platform.getConfigurationLocation() will return null. You could add the following field and method to the FavoritesPlugin class to return a configuration directory for this plug-in. If Eclipse is installed in a read-only location, then this method would gracefully degrade by returning the workspace-specific state location rather than the configuration directory so that plug-in state information could still be stored and retrieved.
public static final String ID = "com.qualityeclipse.favorites";
public File getConfigDir() {
Location location = Platform.getConfigurationLocation();
if (location != null) {
URL configURL = location.getURL();
if (configURL != null
&& configURL.getProtocol().startsWith("file")) {
return new File(configURL.getFile(), ID);
}
}
// If the configuration directory is read-only,
// then return an alternate location
// rather than null or throwing an Exception.
return getStateLocation().toFile();
}
Preferences can also be stored in the configuration directory by adding the following field and method to the FavoritesPlugin class.
private IEclipsePreferences configPrefs;
public Preferences getConfigPrefs() {
if (configPrefs == null)
configPrefs = new ConfigurationScope().getNode(ID);
return configPrefs;
}
If you add the preceding method to your plug-in class, then you should also modify the stop() method to flush the configuration preferences to disk when Eclipse shuts down.
public void stop(BundleContext context) throws Exception {
if (configPrefs != null) {
configPrefs.flush();
configPrefs = null;
}
plugin = null;
super.stop(context);
}
When you launch a Runtime Workbench (see Section 2.6, Debugging the Product, on page 88), you can specify the configuration directory using the Configration page of the Run dialog (see Figure 3-6).
)
Figure 3-6 The Launch Configuration page for specifying the configuration directory.
3.4.6 Plugin and AbstractUIPlugin
All plug-in classes must implement the BundleActivator interface. Typically, UI-based plug-ins (plug-ins requiring the org.eclipse.ui plug-in) have a plug-in class that subclasses AbstractUIPlugin, while non-UI plug-ins subclass Plugin. Both classes provide basic plug-in services for the plug-in programmer, but there are important differences.
AbstractUIPlugin automatically saves plug-in preferences when the plug-in shuts down. When subclassing the Plugin class directly, modify the stop() method to always call savePluginPreferences() and saveDialogSettings() so that preferences will persist across sessions.
Other methods provided by AbstractUIPlugin include:
- createImageRegistry()— Returns a new image registry for this plug-in. You can use the registry to manage images that are used frequently by the plug-in. The default implementation of this method creates an empty registry. Subclasses can override this method if necessary.
- getDialogSettings()— Returns the dialog settings for this UI plug-in (see Section 11.2.7, Dialog settings, on page 441). The dialog settings hold persistent state data for the various wizards and dialogs of this plug-in in the context of a workbench.
- getImageRegistry()— Returns the image registry for this UI plug-in (see Section 4.4.3, Images, on page 181 and Section 7.7, Image Caching, on page 315).
- initializeImageRegistry(ImageRegistry reg)— Initializes an image registry with images that are used frequently by the plug-in.
- loadDialogSettings()— Loads the dialog settings for this plug-in by looking first for a dialog_settings.xml file in the plug-in's metadata directory, then for a file with the same name in the plug-in directory; failing both of these, it creates an empty settings object. This method can be overridden, although this is typically unnecessary.