The Eclipse plug-in class for Lotus Notes and Domino

Learn about the Eclipse plug-in class for Lotus Notes and Domino, as well as other methods used to acess static resources for the plug-in.

The following is tip #4 from "Developing Eclipse plug-ins for Lotus Notes and Domino -- 7 tips in 7 minutes," excerpted from Chapter 3 of the book Eclipse: Building Commercial Quality Plug-ins, published by Addison-Wesley Publishing.


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.

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.

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.

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

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

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.

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

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.
  • getStateLocation() - Returns the location in the local filesystem of the plug-in state area for this plug-in. 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. Using this second approach also lets you easily internationalize the plug-in using a preferences.properties file.

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.

Note: 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, you can specify the configuration directory using the Configration page of the Run dialog (see Figure 6.).

Figure 6: The Launch Configuration page for specifying the configuration directory.

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.

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

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


Developing Eclipse plug-ins for Lotus Notes and Domino

 Home: Introduction
 Tip 1: The Eclipse plug-in structure for Lotus Notes and Domino
 Tip 2: The Eclipse plug-in directory for Lotus Notes and Domino
 Tip 3: The Eclipse plug-in manifest for Lotus Notes and Domino
 Tip 4: The Eclipse plug-in class for Lotus Notes and Domino
 Tip 5: The Eclipse plug-in model for Lotus Notes and Domino
 Tip 6: Eclipse logging for Lotus Notes and Domino
 Tip 7: Eclipse plug-in types for Lotus Notes and Domino


This chapter is excerpted from Eclipse: Building Commercial-Quality Plug-ins, 2nd Edition, by Eric Clayberg and Dan Rubel, published by Addison-Wesley Professional in March 2006. Copyright 2006 Pearson Education Inc. ISBN: 032142672X. Reprinted with permissions, all rights reserved. Click here to see a complete Table of Contents for this book. Click here for the chapter download.
This was first published in April 2007

Dig deeper on Eclipse for Lotus Notes Domino

0 comments

Oldest 

Forgot Password?

No problem! Submit your e-mail address below. We'll send you an email containing your password.

Your password has been sent to:

-ADS BY GOOGLE

SearchWindowsServer

Search400

  • iSeries tutorials

    Search400.com's tutorials provide in-depth information on the iSeries. Our iSeries tutorials address areas you need to know about...

  • V6R1 upgrade planning checklist

    When upgrading to V6R1, make sure your software will be supported, your programs will function and the correct PTFs have been ...

  • Connecting multiple iSeries systems through DDM

    Working with databases over multiple iSeries systems can be simple when remotely connecting logical partitions with distributed ...

SearchEnterpriseLinux

SearchDataCenter

SearchExchange

SearchContentManagement

Close