|
|
3.4. Plug-in ClassBy 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). Tip Historically, plug-ins have exposed their Plugin subclass as an entry point. To better control access to your plug-in's initialization, consider either a Bundle-Activator other than your Plugin subclass or moving public access methods to a new class and hiding your Plugin subclass. 3.4.1. Startup and shutdownThe 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. Be Careful When Overriding start() and stop() When overriding these methods, be careful; always call the superclass implementation, and only take the minimum action necessary so that you do not impact the speed or memory requirements during Eclipse startup or shutdown. 3.4.2. Early plug-in startupEclipse 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 resourcesPlug-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:
3.4.4. Plug-in preferencesPlug-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:
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 filesIf 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. Read-Only Installation Be warned that if Eclipse is installed in a read-only location, then this method will return null. In addition, neither the following code nor the Preferences object returned by the method below is thread safe. 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 AbstractUIPluginAll 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. Older Preference Storage Methods AbstractUIPlugin provides alternate preferences storage methods and classes that you should not use. These methods, such as getPreferenceStore() and the associated IPreferenceStore interface, predate Eclipse 3.1 and the Plugin class preference methods, such as getPluginPreferences() and the associated class Preferences. They exist only for backward compatibility. These older preference storage methods do not provide any advantages when used in AbstractUIPlugin, so use the Preferences interface and associated methods unless the Eclipse API specifically requires the older interface (see Chapter 12, Preference Pages, for more on preferences). Other methods provided by AbstractUIPlugin include:
|
|
|