Section 3.4. Plug-in Class


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).

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 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.

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 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 /> </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.

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 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.

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:

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.



Eclipse(c) Building Commercial-Quality Plug-ins
Eclipse: Building Commercial-Quality Plug-ins (2nd Edition)
ISBN: 032142672X
EAN: 2147483647
Year: 2004
Pages: 200

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net