Package org.eclipse.ui.plugin

# Class AbstractUIPlugin

java.lang.Object
org.eclipse.core.runtime.Plugin
org.eclipse.ui.plugin.AbstractUIPlugin

All Implemented Interfaces:
  `BundleActivator`

Direct Known Subclasses:
  `ConsolePlugin`

public abstract class AbstractUIPlugin extends Plugin
Abstract base class for plug-ins that integrate with the Eclipse platform UI.

Subclasses obtain the following capabilities:

Preferences

- The platform core runtime contains general support for plug-in preferences (`org.eclipse.core.runtime.Preferences`). This class provides appropriate conversion to the older JFace preference API (`org.eclipse.jface.preference.IPreferenceStore`).
- The method `getPreferenceStore` returns the JFace preference store (cf. `Plugin.getPluginPreferences` which returns a core runtime preferences object.
- Subclasses may reimplement `initializeDefaultPreferences` to set up any default values for preferences using JFace API. In this case, `initializeDefaultPluginPreferences` should not be overridden.
- Subclasses may reimplement `initializeDefaultPluginPreferences` to set up any default values for preferences using core runtime API. In this case, `initializeDefaultPreferences` should not be overridden.
- Preferences are also saved automatically on plug-in shutdown. However, saving preferences immediately after changing them is strongly recommended, since that ensures that preference settings are not lost even in the event of a platform crash.

Dialogs

- The dialog store is read the first time `getDialogSettings` is called.
- The dialog store allows the plug-in to "record" important choices made by the user in a wizard or dialog, so that the next time the wizard/dialog is used the widgets can be defaulted to better values. A wizard could also use it to record the last 5 values a user entered into an editable combo - to show "recent values".
- The dialog store is found in the file whose name is given by the constant `FN_DIALOG_STORE`. A dialog store file is first looked for in the plug-in's read/write state area; if not found there, the plug-in's install directory is checked. This allows a plug-in to ship with a read-only copy of a dialog store file containing initial values for certain settings.
- Plug-in code can call `saveDialogSettings` to cause settings to be saved in the plug-in's read/write state area. A plug-in may opt to do this each time a wizard or dialog is closed to ensure the latest information is always safe on disk.
- Dialog settings are also saved automatically on plug-in shutdown.

Images

- A typical UI plug-in will have some images that are used very frequently and so need to be cached and shared. The plug-in's image registry provides a central place for a plug-in to store its common images. Images managed by the registry are created lazily as needed, and will be automatically disposed of when the plug-in shuts down. Note that the number of registry images should be kept to a minimum since many OSs have severe limits on the number of images that can be in memory at once.

For easy access to your plug-in object, use the singleton pattern. Declare a static variable in your plug-in class for the singleton. Store the first (and only) instance of the plug-in class in the singleton when it is created. Then access the singleton when needed through a static `getDefault` method.

See the description on `Plugin`.

## Field Summary

### Fields inherited from class org.eclipse.core.runtime.Plugin

`PLUGIN_PREFERENCE_SCOPE, PREFERENCES_DEFAULT_OVERRIDE_BASE_NAME, PREFERENCES_DEFAULT_OVERRIDE_FILE_NAME`

## Constructor Summary

Constructors
Constructor
Description
`AbstractUIPlugin()`
Creates an abstract UI plug-in runtime object.

## Method Summary

Modifier and Type
Method
Description
`protected ImageRegistry`
`createImageRegistry()`
Returns a new image registry for this plugin-in.
`IDialogSettings`
`getDialogSettings()`
Returns the dialog settings by calling `PlatformUI.getDialogSettingsProvider`(`getBundle()`).`getDialogSettings()`.
`ImageRegistry`
`getImageRegistry()`
Returns the image registry for this UI plug-in.
`IPreferenceStore`
`getPreferenceStore()`
Returns the preference store for this UI plug-in.
`IWorkbench`
`getWorkbench()`
Deprecated.
Use `PlatformUI.getWorkbench()` directly
`static ImageDescriptor`
`imageDescriptorFromPlugin(String pluginId, String imageFilePath)`
Creates and returns a new image descriptor for an image file located within the specified plug-in.
`protected void`
`initializeDefaultPluginPreferences()`
Deprecated.
this is only called if the runtime compatibility layer is present.
`protected void`
`initializeDefaultPreferences(IPreferenceStore store)`
Deprecated.
this is only called if the runtime compatibility layer is present.
`protected void`
`initializeImageRegistry(ImageRegistry reg)`
Initializes an image registry with images which are frequently used by the plugin.
`protected void`
`loadDialogSettings()`
Deprecated.
`protected void`
`loadPreferenceStore()`
Deprecated.
As of Eclipse 2.0, a basic preference store exists for all plug-ins.
`protected void`
`refreshPluginActions()`
Refreshes the actions for the plugin.
`protected void`
`saveDialogSettings()`
Deprecated.
`protected void`
`savePreferenceStore()`
Deprecated.
As of Eclipse 2.0, preferences exist for all plug-ins.
`void`
`shutdown()`
Deprecated.
In Eclipse 3.0, `shutdown` has been replaced by `Plugin.stop(BundleContext context)`.
`void`
`start(BundleContext context)`
The `AbstractUIPlugin` implementation of this `Plugin` method refreshes the plug-in actions.
`void`
`startup()`
Deprecated.
`void`
`stop(BundleContext context)`
The `AbstractUIPlugin` implementation of this `Plugin` method saves this plug-in's preference and dialog stores and shuts down its image registry (if they are in use).

### Methods inherited from class org.eclipse.core.runtime.Plugin

`find, find, getBundle, getLog, getPluginPreferences, getStateLocation, internalInitializeDefaultPluginPreferences, isDebugging, openStream, openStream, savePluginPreferences, setDebugging, toString`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

## Constructor Details

### AbstractUIPlugin

public AbstractUIPlugin()
Creates an abstract UI plug-in runtime object.

Plug-in runtime classes are `BundleActivators` and so must have an default constructor. This method is called by the runtime when the associated bundle is being activated.

For more details, see `Plugin`'s default constructor.

Since:
  3.0
See Also:
  - `Plugin()`

## Method Details

### createImageRegistry

protected ImageRegistry createImageRegistry()
Returns a new image registry for this plugin-in. The registry will be used to manage images which are frequently used by the plugin-in.

The default implementation of this method creates an empty registry. Subclasses may override this method if needed.

Returns:
  ImageRegistry the resulting registry.
See Also:
  - `getImageRegistry()`

### getDialogSettings

public IDialogSettings getDialogSettings()
Returns the dialog settings by calling `PlatformUI.getDialogSettingsProvider`(`getBundle()`).`getDialogSettings()`.

For new code, consider using the following idiom directly instead of relying on a UI plugin class:

     PlatformUI.getDialogSettingsProvider(FrameworkUtil.getBundle(My.class)).getDialogSettings()

Returns:
  the dialog settings
See Also:
  - `FrameworkUtil.getBundle(Class)`
  - `PlatformUI.getDialogSettingsProvider(Bundle)`

### getImageRegistry

public ImageRegistry getImageRegistry()
Returns the image registry for this UI plug-in.

The image registry contains the images used by this plug-in that are very frequently used and so need to be globally shared within the plug-in. Since many OSs have a severe limit on the number of images that can be in memory at any given time, a plug-in should only keep a small number of images in their registry.

Subclasses should reimplement `initializeImageRegistry` if they have custom graphic images to load.

Subclasses may override this method but are not expected to.

Returns:
  the image registry

### getPreferenceStore

public IPreferenceStore getPreferenceStore()
Returns the preference store for this UI plug-in. This preference store is used to hold persistent settings for this plug-in in the context of a workbench. Some of these settings will be user controlled, whereas others may be internal setting that are never exposed to the user.

If an error occurs reading the preference store, an empty preference store is quietly created, initialized with defaults, and returned.

NOTE1: As of Eclipse 3.1 this method is no longer referring to the core runtime compatibility layer and so plug-ins relying on Plugin#initializeDefaultPreferences will have to access the compatibility layer themselves.

NOTE2: This method may be called from a none UI-Thread.

Returns:
  the preference store

### getWorkbench

@Deprecated public IWorkbench getWorkbench()
Deprecated.
Use `PlatformUI.getWorkbench()` directly
Returns the Platform UI workbench.

This method exists as a convenience for plugin implementors. The workbench can also be accessed by invoking `PlatformUI.getWorkbench()`.

Returns:
  IWorkbench the workbench for this plug-in

### initializeDefaultPreferences

@Deprecated protected void initializeDefaultPreferences(IPreferenceStore store)
Deprecated.
this is only called if the runtime compatibility layer is present. See `initializeDefaultPluginPreferences()`.
Initializes a preference store with default preference values for this plug-in.

This method is called after the preference store is initially loaded (default values are never stored in preference stores).

The default implementation of this method does nothing. Subclasses should reimplement this method if the plug-in has any preferences.

A subclass may reimplement this method to set default values for the preference store using JFace API. This is the older way of initializing default values. If this method is reimplemented, do not override `initializeDefaultPluginPreferences()`.

Parameters:
  `store` - the preference store to fill

### initializeDefaultPluginPreferences

@Deprecated protected void initializeDefaultPluginPreferences()
Deprecated.
this is only called if the runtime compatibility layer is present. See the deprecated comment in `Plugin.initializeDefaultPluginPreferences()`.
The `AbstractUIPlugin` implementation of this `Plugin` method forwards to `initializeDefaultPreferences(IPreferenceStore)`.

A subclass may reimplement this method to set default values for the core runtime preference store in the standard way. This is the recommended way to do this. The older `initializeDefaultPreferences(IPreferenceStore)` method serves a similar purpose. If this method is reimplemented, do not send super, and do not override `initializeDefaultPreferences(IPreferenceStore)`.

Overrides:
  `initializeDefaultPluginPreferences` in class `Plugin`
Since:
  2.0
See Also:
  - `initializeDefaultPreferences(org.eclipse.jface.preference.IPreferenceStore)`

### initializeImageRegistry

protected void initializeImageRegistry(ImageRegistry reg)
Initializes an image registry with images which are frequently used by the plugin.

The image registry contains the images used by this plug-in that are very frequently used and so need to be globally shared within the plug-in. Since many OSs have a severe limit on the number of images that can be in memory at any given time, each plug-in should only keep a small number of images in its registry.

Implementors should create a JFace image descriptor for each frequently used image. The descriptors describe how to create/find the image should it be needed. The image described by the descriptor is not actually allocated until someone retrieves it.

Subclasses may override this method to fill the image registry.

Parameters:
  `reg` - the registry to initialize
See Also:
  - `getImageRegistry()`

### loadDialogSettings

@Deprecated protected void loadDialogSettings()
Deprecated.
Reloads the dialog settings for this bundle. This framework method may be overridden, although this is typically unnecessary.

See Also:
  - `PlatformUI.getDialogSettingsProvider(Bundle)`

### loadPreferenceStore

@Deprecated protected void loadPreferenceStore()
Deprecated.
As of Eclipse 2.0, a basic preference store exists for all plug-ins. This method now exists only for backwards compatibility. It is called as the plug-in's preference store is being initialized. The plug-ins preferences are loaded from the file regardless of what this method does.
Loads the preference store for this plug-in. The default implementation looks for a standard named file in the plug-in's read/write state area. If no file is found or a problem occurs, a new empty preference store is silently created.

This framework method may be overridden, although this is typically unnecessary.

### refreshPluginActions

protected void refreshPluginActions()
Refreshes the actions for the plugin. This method is called from `startup`.

This framework method may be overridden, although this is typically unnecessary.

### saveDialogSettings

@Deprecated protected void saveDialogSettings()
Deprecated.
Dialog settings are saved automatically when the workbench stops.

See Also:
  - `IDialogSettingsProvider.saveDialogSettings()`

### savePreferenceStore

@Deprecated protected void savePreferenceStore()
Deprecated.
As of Eclipse 2.0, preferences exist for all plug-ins. The equivalent of this method is `Plugin.savePluginPreferences`. This method now calls `savePluginPreferences`, and exists only for backwards compatibility.
Saves this plug-in's preference store. Any problems which arise are silently ignored.

See Also:
  - `Plugin.savePluginPreferences()`

### startup

@Deprecated public void startup() throws CoreException
Deprecated.
The startup method was called only for plug-ins which explicitly require the org.eclipse.core.runtime.compatibility plug-in. It is not called anymore as Eclipse 4.6 removed this plug-in.

Overrides:
  `startup` in class `Plugin`
Throws:
  `CoreException` - Never thrown as method as no longer called.

### shutdown

@Deprecated public void shutdown() throws CoreException
Deprecated.
In Eclipse 3.0, `shutdown` has been replaced by `Plugin.stop(BundleContext context)`. Implementations of `shutdown` should be changed to extend `stop(BundleContext context)` and call `super.stop(context)` instead of `super.shutdown()`. Unlike `super.shutdown()`, `super.stop(context)` must be called as the very last thing rather than as the very first thing. The `shutdown` method is called only for plug-ins which explicitly require the org.eclipse.core.runtime.compatibility plug-in; in contrast, the `stop` method is always called.
The `AbstractUIPlugin` implementation of this `Plugin` method does nothing. Subclasses may extend this method, but must send super first.

Overrides:
  `shutdown` in class `Plugin`
Throws:
  `CoreException` - Never thrown as method as no longer called.

### start

public void start(BundleContext context) throws Exception
The `AbstractUIPlugin` implementation of this `Plugin` method refreshes the plug-in actions. Subclasses may extend this method, but must send super first. Starts up this plug-in.

This method should be overridden in subclasses that need to do something when this plug-in is started. Implementors should call the inherited method at the first possible point to ensure that any system requirements can be met.

If this method throws an exception, it is taken as an indication that plug-in initialization has failed; as a result, the plug-in will not be activated; moreover, the plug-in will be marked as disabled and ineligible for activation for the duration.

Note 1: This method is automatically invoked by the platform the first time any code in the plug-in is executed.

Note 2: This method is intended to perform simple initialization of the plug-in environment. The platform may terminate initializers that do not complete in a timely fashion.

Note 3: The class loader typically has monitors acquired during invocation of this method. It is strongly recommended that this method avoid synchronized blocks or other thread locking mechanisms, as this would lead to deadlock vulnerability.

Note 4: The supplied bundle context represents the plug-in to the OSGi framework. For security reasons, it is strongly recommended that this object should not be divulged.

Note 5: This method and the `Plugin.stop(BundleContext)` may be called from separate threads, but the OSGi framework ensures that both methods will not be called simultaneously.

Clients must never explicitly call this method.

Specified by:
  `start` in interface `BundleActivator`
Overrides:
  `start` in class `Plugin`
Parameters:
  `context` - the bundle context for this plug-in
Throws:
  `Exception` - if this plug-in did not start up properly
Since:
  3.0

### stop

public void stop(BundleContext context) throws Exception
The `AbstractUIPlugin` implementation of this `Plugin` method saves this plug-in's preference and dialog stores and shuts down its image registry (if they are in use). Subclasses may extend this method, but must send super last. A try-finally statement should be used where necessary to ensure that `super.stop()` is always done. Stops this plug-in.

This method should be re-implemented in subclasses that need to do something when the plug-in is shut down. Implementors should call the inherited method as late as possible to ensure that any system requirements can be met.

Plug-in shutdown code should be robust. In particular, this method should always make an effort to shut down the plug-in. Furthermore, the code should not assume that the plug-in was started successfully.

Note 1: If a plug-in has been automatically started, this method will be automatically invoked by the platform when the platform is shut down.

Note 2: This method is intended to perform simple termination of the plug-in environment. The platform may terminate invocations that do not complete in a timely fashion.

Note 3: The supplied bundle context represents the plug-in to the OSGi framework. For security reasons, it is strongly recommended that this object should not be divulged.

Note 4: This method and the `Plugin.start(BundleContext)` may be called from separate threads, but the OSGi framework ensures that both methods will not be called simultaneously.

Clients must never explicitly call this method.

Specified by:
  `stop` in interface `BundleActivator`
Overrides:
  `stop` in class `Plugin`
Parameters:
  `context` - the bundle context for this plug-in
Throws:
  `Exception` - if this method fails to shut down this plug-in
Since:
  3.0

### imageDescriptorFromPlugin

public static ImageDescriptor imageDescriptorFromPlugin(String pluginId, String imageFilePath)
Creates and returns a new image descriptor for an image file located within the specified plug-in.

Prefer to use `ResourceLocator.imageDescriptorFromBundle(String, String)` to create a new `ImageDescriptor` for a file inside a bundle or

`ImageDescriptor imageDescriptor = PlatformUI.isWorkbenchRunning() ? PlatformUI.getWorkbench().getSharedImages().getImageDescriptor(imageSymbolicName) : null;`

to reuse already declared `ImageDescriptor` (refer to `ISharedImages.getImageDescriptor(String)` for more details)

This is a convenience method that simply locates the image file in within the plug-in. It will now query the ISharedImages registry first. The path is relative to the root of the plug-in, and takes into account files coming from plug-in fragments. The path may include $arg$ elements. However, the path must not have a leading "." or path separator. Clients should use a path like "icons/mysample.png" rather than "./icons/mysample.png" or "/icons/mysample.png".

Parameters:
  `pluginId` - the id of the plug-in containing the image file; `null` is returned if the plug-in does not exist
  `imageFilePath` - the relative path of the image file, relative to the root of the plug-in; the path must be legal
Returns:
  an image descriptor, or `null` if no image could be found
Since:
  3.0