org.eclipse.core.runtime

## Class Plugin

- java.lang.Object
- - org.eclipse.core.runtime.Plugin

All Implemented Interfaces:
  BundleActivator

Direct Known Subclasses:
  AbstractUIPlugin, AntCorePlugin, DebugPlugin, ResourcesPlugin, VariablesPlugin

    public abstract class Plugin
    extends Object
    implements BundleActivator

The abstract superclass of all plug-in runtime class implementations. A plug-in subclasses this class and overrides the appropriate life cycle methods in order to react to the life cycle requests automatically issued by the platform. For compatibility reasons, the methods called for those life cycle events vary, please see the "Constructors and life cycle methods" section below.

Conceptually, the plug-in runtime class represents the entire plug-in rather than an implementation of any one particular extension the plug-in declares. A plug-in is not required to explicitly specify a plug-in runtime class; if none is specified, the plug-in will be given a default plug-in runtime object that ignores all life cycle requests (it still provides access to the corresponding plug-in descriptor).

In the case of more complex plug-ins, it may be desirable to define a concrete subclass of `Plugin`. However, just subclassing `Plugin` is not sufficient. The name of the class must be explicitly configured in the plug-in's manifest (`plugin.xml`) file with the class attribute of the `<plugin>` element markup.

Instances of plug-in runtime classes are automatically created by the platform in the course of plug-in activation. For compatibility reasons, the constructor used to create plug-in instances varies, please see the "Constructors and life cycle methods" section below.

The concept of bundles underlies plug-ins. However it is safe to regard plug-ins and bundles as synonyms.

Clients must never explicitly instantiate a plug-in runtime class.

A typical implementation pattern for plug-in runtime classes is to provide a static convenience method to gain access to a plug-in's runtime object. This way, code in other parts of the plug-in implementation without direct access to the plug-in runtime object can easily obtain a reference to it, and thence to any plug-in-wide resources recorded on it. An example for Eclipse 3.0 follows:

         package myplugin;
         public class MyPluginClass extends Plugin {
             private static MyPluginClass instance;

             public static MyPluginClass getInstance() { return instance; }

             public void MyPluginClass() {
                 super();
                 instance = this;
                 // ... other initialization
             }
             // ... other methods
         }

In the above example, a call to `MyPluginClass.getInstance()` will always return an initialized instance of `MyPluginClass`.

Constructors and life cycle methods

If the plugin.xml of a plug-in indicates <?eclipse version="3.0"?> and its prerequisite list includes `org.eclipse.core.runtime`, the default constructor of the plug-in class is used and `start(BundleContext)` and `stop(BundleContext)` are called as life cycle methods.

The `Plugin(IPluginDescriptor)` constructor 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.

If the plugin.xml of your plug-in does not indicate <?eclipse version="3.0"?> it is therefore not a 3.0 plug-in. Consequently the `Plugin(IPluginDescriptor)` is used and `startup()` and `shutdown()` are called as life cycle methods.

Since Eclipse 3.0 APIs of the Plugin class can be called only when the Plugin is in an active state, i.e., after it was started up and before it is shutdown. In particular, it means that Plugin APIs should not be called from overrides of `Plugin()`.

### Field Summary

Fields
`static String` `PLUGIN_PREFERENCE_SCOPE` String constant used for the default scope name for legacy Eclipse plug-in preferences.
`static String` `PREFERENCES_DEFAULT_OVERRIDE_BASE_NAME` The base name (value `"preferences"`) for the file which is used for overriding default preference values.
`static String` `PREFERENCES_DEFAULT_OVERRIDE_FILE_NAME` The name of the file (value `"preferences.ini"`) in a plug-in's (read-only) directory that, when present, contains values that override the normal default values for this plug-in's preferences.

### Constructor Summary

Constructors
Constructor and Description
`Plugin()` Creates a new plug-in runtime object.
`Plugin(IPluginDescriptor descriptor)` Deprecated.

### Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
`URL` `find(IPath path)` Deprecated. use `FileLocator.find(Bundle, IPath, Map)`
`URL` `find(IPath path, Map<String,String> override)` Deprecated. use `FileLocator.find(Bundle, IPath, Map)`
`Bundle` `getBundle()` Returns the bundle associated with this plug-in.
`IPluginDescriptor` `getDescriptor()` Deprecated.
`ILog` `getLog()` Returns the log for this plug-in.

`Preferences`

`getPluginPreferences()`
Deprecated.
Replaced by `IEclipsePreferences`. Preferences are now stored according to scopes in the `IPreferencesService`. The return value of this method corresponds to a combination of the `InstanceScope` and the `DefaultScope`. To set preferences for your plug-in, use `InstanceScope.INSTANCE.getNode(<yourPluginId>)`. To set default preferences for your plug-in, use `DefaultScope.INSTANCE.getNode(<yourPluginId>)`. To lookup an integer preference value for your plug-in, use `Platform.getPreferencesService().getInt(<yourPluginId>, <preferenceKey>, <defaultValue>, null)`. Similar methods exist on `IPreferencesService` for obtaining other kinds of preference values (strings, booleans, etc).

`IPath` `getStateLocation()` Returns the location in the local file system of the plug-in state area for this plug-in.

`protected void`

`initializeDefaultPluginPreferences()`
Deprecated.
This method has been refactored in the new preference mechanism to handle the case where the runtime compatibility layer does not exist. The contents of this method should be moved to the method named `initializeDefaultPreferences` in a separate subclass of `AbstractPreferenceInitializer`. This class should be contributed via the `org.eclipse.core.runtime.preferences` extension point.

            <extension point="org.eclipse.core.runtime.preferences">
                            <initializer class="com.example.MyPreferenceInitializer"/>
                    </extension>
                    ...
                    package com.example;
                    public class MyPreferenceInitializer extends AbstractPreferenceInitializer {
                            public MyPreferenceInitializer() {
                                    super();
                            }
                            public void initializeDefaultPreferences() {
                                    Preferences node = new DefaultScope().getNode("my.plugin.id");
                                    node.put(key, value);
                            }
                    }

`void` `internalInitializeDefaultPluginPreferences()` Deprecated.
`boolean` `isDebugging()` Returns whether this plug-in is in debug mode.
`InputStream` `openStream(IPath file)` Deprecated. use `FileLocator.openStream(Bundle, IPath, boolean)`
`InputStream` `openStream(IPath file, boolean substituteArgs)` Deprecated. use `FileLocator.openStream(Bundle, IPath, boolean)`
`void` `savePluginPreferences()` Deprecated. Replaced by InstanceScope.getNode(<bundleId>).flush()
`void` `setDebugging(boolean value)` Sets whether this plug-in is in debug mode.
`void` `shutdown()` Deprecated.
`void` `start(BundleContext context)` Starts up this plug-in.
`void` `startup()` Deprecated.
`void` `stop(BundleContext context)` Stops this plug-in.
`String` `toString()` Returns a string representation of the plug-in, suitable for debugging purposes only.

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

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

### Field Detail

#### PLUGIN_PREFERENCE_SCOPE

    public static final String PLUGIN_PREFERENCE_SCOPE

String constant used for the default scope name for legacy Eclipse plug-in preferences. The value of `PLUGIN_PREFERENCE_SCOPE` should match the InstanceScope's variable SCOPE from org.eclipse.core.runtime.preferences. The value is copied in this file to prevent unnecessary activation of the Preferences plugin on startup.

Since:
  3.0
See Also:
  Constant Field Values

#### PREFERENCES_DEFAULT_OVERRIDE_BASE_NAME

    public static final String PREFERENCES_DEFAULT_OVERRIDE_BASE_NAME

The base name (value `"preferences"`) for the file which is used for overriding default preference values.

Since:
  2.0
See Also:
  `PREFERENCES_DEFAULT_OVERRIDE_FILE_NAME`, Constant Field Values

#### PREFERENCES_DEFAULT_OVERRIDE_FILE_NAME

    public static final String PREFERENCES_DEFAULT_OVERRIDE_FILE_NAME

The name of the file (value `"preferences.ini"`) in a plug-in's (read-only) directory that, when present, contains values that override the normal default values for this plug-in's preferences.

The format of the file is as per `java.io.Properties` where the keys are property names and values are strings.

Since:
  2.0
See Also:
  Constant Field Values

### Constructor Detail

#### Plugin

    public Plugin()

Creates a new plug-in runtime object. This method is called by the platform if this class is used as a `BundleActivator`. This method is not needed/used if this plug-in requires the org.eclipse.core.runtime.compatibility plug-in. Subclasses of `Plugin` must call this method first in their constructors. The resultant instance is not managed by the runtime and so should be remembered by the client (typically using a Singleton pattern). Clients must never explicitly call this method.

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

Since:
  3.0

#### Plugin

    @Deprecated
    public Plugin(IPluginDescriptor descriptor)

Deprecated.
As the org.eclipse.core.runtime.compatibility plug-in has been removed in Eclipse 4.6 this method is not supported anymore. In Eclipse 3.0 this constructor has been replaced by `Plugin()`. Implementations of `MyPlugin(IPluginDescriptor descriptor)` should be changed to `MyPlugin()` and call `super()` instead of `super(descriptor)`. The `MyPlugin(IPluginDescriptor descriptor)` constructor was called only for plug-ins which explicitly require the org.eclipse.core.runtime.compatibility plug-in. It is not called anymore.

### Method Detail

#### find

    @Deprecated
    public final URL find(IPath path)

Deprecated. use `FileLocator.find(Bundle, IPath, Map)`
Returns a URL for the given path. Returns `null` if the URL could not be computed or created.

Parameters:
  `path` - path relative to plug-in installation location
Returns:
  a URL for the given path or `null`

#### find

    @Deprecated
    public final URL find(IPath path,
                                      Map<String,String> override)

Deprecated. use `FileLocator.find(Bundle, IPath, Map)`
Returns a URL for the given path. Returns `null` if the URL could not be computed or created.

Parameters:
  `path` - file path relative to plug-in installation location
  `override` - map of override substitution arguments to be used for any $arg$ path elements. The map keys correspond to the substitution arguments (eg. "$nl$" or "$os$"). The resulting values must be of type java.lang.String. If the map is `null`, or does not contain the required substitution argument, the default is used.
Returns:
  a URL for the given path or `null`

#### getDescriptor

    @Deprecated
    public final IPluginDescriptor getDescriptor()

Deprecated.
As the org.eclipse.core.runtime.compatibility plug-in has been removed in Eclipse 4.6 this method is not supported anymore. `IPluginDescriptor` was refactored in Eclipse 3.0. The `getDescriptor()` method was only be called by plug-ins which explicitly require the org.eclipse.core.runtime.compatibility plug-in. It is not called anymore.

#### getLog

    public final ILog getLog()

Returns the log for this plug-in. If no such log exists, one is created.

Returns:
  the log for this plug-in XXX change this into a LogMgr service that would keep track of the map. See if it can be a service factory.

#### getStateLocation

    public final IPath getStateLocation()
                                 throws IllegalStateException

Returns the location in the local file system 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.

The plug-in state area is a file directory within the platform's metadata area where a plug-in is free to create files. The content and structure of this area is defined by the plug-in, and the particular plug-in is solely responsible for any files it puts there. It is recommended for plug-in preference settings and other configuration parameters.

Returns:
  a local file system path XXX Investigate the usage of a service factory (see also platform.getStateLocation)
Throws:
  `IllegalStateException` - when the system is running with no data area (-data @none), or when a data area has not been set yet.

#### getPluginPreferences

    @Deprecated
    public final Preferences getPluginPreferences()

Deprecated. Replaced by `IEclipsePreferences`. Preferences are now stored according to scopes in the `IPreferencesService`. The return value of this method corresponds to a combination of the `InstanceScope` and the `DefaultScope`. To set preferences for your plug-in, use `InstanceScope.INSTANCE.getNode(<yourPluginId>)`. To set default preferences for your plug-in, use `DefaultScope.INSTANCE.getNode(<yourPluginId>)`. To lookup an integer preference value for your plug-in, use `Platform.getPreferencesService().getInt(<yourPluginId>, <preferenceKey>, <defaultValue>, null)`. Similar methods exist on `IPreferencesService` for obtaining other kinds of preference values (strings, booleans, etc).
Returns the preference store for this plug-in.

Note that if an error occurs reading the preference store from disk, an empty preference store is quietly created, initialized with defaults, and returned.

Calling this method may cause the preference store to be created and initialized. Subclasses which reimplement the `initializeDefaultPluginPreferences` method have this opportunity to initialize preference default values, just prior to processing override default values imposed externally to this plug-in (specified for the product, or at platform start up).

After settings in the preference store are changed (for example, with `Preferences.setValue` or `setToDefault`), `savePluginPreferences` should be called to store the changed values back to disk. Otherwise the changes will be lost on plug-in shutdown.

Returns:
  the preference store
Since:
  2.0
See Also:
  `savePluginPreferences()`, `Preferences.setValue(String, String)`, `Preferences.setToDefault(String)`

#### savePluginPreferences

    @Deprecated
    public final void savePluginPreferences()

Deprecated. Replaced by InstanceScope.getNode(<bundleId>).flush()
Saves preferences settings for this plug-in. Does nothing if the preference store does not need saving.

Plug-in preferences are not saved automatically on plug-in shutdown.

Since:
  2.0
See Also:
  `Preferences.store(OutputStream, String)`, `Preferences.needsSaving()`

#### initializeDefaultPluginPreferences

    @Deprecated
    protected void initializeDefaultPluginPreferences()

Deprecated. This method has been refactored in the new preference mechanism to handle the case where the runtime compatibility layer does not exist. The contents of this method should be moved to the method named `initializeDefaultPreferences` in a separate subclass of `AbstractPreferenceInitializer`. This class should be contributed via the `org.eclipse.core.runtime.preferences` extension point.

            <extension point="org.eclipse.core.runtime.preferences">
                            <initializer class="com.example.MyPreferenceInitializer"/>
                    </extension>
                    ...
                    package com.example;
                    public class MyPreferenceInitializer extends AbstractPreferenceInitializer {
                            public MyPreferenceInitializer() {
                                    super();
                            }
                            public void initializeDefaultPreferences() {
                                    Preferences node = new DefaultScope().getNode("my.plugin.id");
                                    node.put(key, value);
                            }
                    }

Initializes the default preferences settings for this plug-in.

This method is called sometime after the preference store for this plug-in is created. Default values are never stored in preference stores; they must be filled in each time. This method provides the opportunity to initialize the default values.

The default implementation of this method does nothing. A subclass that needs to set default values for its preferences must reimplement this method. Default values set at a later point will override any default override settings supplied from outside the plug-in (product configuration or platform start up).

Since:
  2.0

#### internalInitializeDefaultPluginPreferences

    @Deprecated
    public final void internalInitializeDefaultPluginPreferences()

Deprecated.
Internal method. This method is a hook for initialization of default preference values. It should not be called by clients.

Since:
  3.0

#### isDebugging

    public boolean isDebugging()

Returns whether this plug-in is in debug mode. By default plug-ins are not in debug mode. A plug-in can put itself into debug mode or the user can set an execution option to do so.

Note that the plug-in's debug flag is initialized when the plug-in is started. The result of calling this method before the plug-in has started is unspecified.

Returns:
  whether this plug-in is in debug mode XXX deprecate use the service and cache as needed

#### openStream

    @Deprecated
    public final InputStream openStream(IPath file)
                                             throws IOException

Deprecated. use `FileLocator.openStream(Bundle, IPath, boolean)`
Returns an input stream for the specified file. The file path must be specified relative this the plug-in's installation location.

Parameters:
  `file` - path relative to plug-in installation location
Returns:
  an input stream
Throws:
  `IOException` - if the given path cannot be found in this plug-in
See Also:
  `openStream(IPath,boolean)`

#### openStream

    @Deprecated
    public final InputStream openStream(IPath file,
                                                    boolean substituteArgs)
                                             throws IOException

Deprecated. use `FileLocator.openStream(Bundle, IPath, boolean)`
Returns an input stream for the specified file. The file path must be specified relative to this plug-in's installation location. Optionally, the path specified may contain $arg$ path elements that can be used as substitution arguments. If this option is used then the $arg$ path elements are processed in the same way as `find(IPath, Map)`.

The caller must close the returned stream when done.

Parameters:
  `file` - path relative to plug-in installation location
  `substituteArgs` - `true` to process substitution arguments, and `false` for the file exactly as specified without processing any substitution arguments.
Returns:
  an input stream
Throws:
  `IOException` - if the given path cannot be found in this plug-in

#### setDebugging

    public void setDebugging(boolean value)

Sets whether this plug-in is in debug mode. By default plug-ins are not in debug mode. A plug-in can put itself into debug mode or the user can set a debug option to do so.

Note that the plug-in's debug flag is initialized when the plug-in is started. The result of calling this method before the plug-in has started is unspecified.

Parameters:
  `value` - whether or not this plug-in is in debug mode XXX deprecate use the service and cache as needed

#### shutdown

    @Deprecated
    public void shutdown()
                              throws CoreException

Deprecated.
As the org.eclipse.core.runtime.compatibility plug-in has been removed in Eclipse 4.6 this method is not supported anymore. In Eclipse 3.0 this method has been replaced by `stop(BundleContext context)`. Implementations of `shutdown()` should be changed to override `stop(BundleContext context)` and call `super.stop(context)` instead of `super.shutdown()` . The `shutdown()` method was called only for plug-ins which explicitly required the org.eclipse.core.runtime.compatibility plug-in. It is not called anymore.

Throws:
  `CoreException`

#### startup

    @Deprecated
    public void startup()
                             throws CoreException

Deprecated.
As the org.eclipse.core.runtime.compatibility plug-in has been removed in Eclipse 4.6 this method is not supported anymore. In Eclipse 3.0 this method has been replaced by `start(BundleContext context)`. Implementations of `startup()` should be changed to extend `start(BundleContext context)` and call `super.start(context)` instead of `super.startup()`. The `startup()` method was called only for plug-ins which explicitly required the org.eclipse.core.runtime.compatibility plug-in. It is not called anymore.

Throws:
  `CoreException`

#### toString

    public String toString()

Returns a string representation of the plug-in, suitable for debugging purposes only.

Overrides:
  `toString` in class `Object`

#### start

    public void start(BundleContext context)
               throws Exception

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

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 `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`
Parameters:
  `context` - the bundle context for this plug-in
Throws:
  `Exception` - if this method fails to shut down this plug-in
Since:
  3.0

#### getBundle

    public final Bundle getBundle()

Returns the bundle associated with this plug-in.

Returns:
  the associated bundle
Since:
  3.0