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.
If the plugin.xml of a plug-in indicates <?eclipse version="3.0"?> and its prerequisite list includes
org.eclipse.core.runtime.compatibility, the
Plugin(IPluginDescriptor)
constructor is used and
startup() and
shutdown() are called as life cycle methods.
Note that in this situation, start() is called before startup() and stop() is called
after shutdown.
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().
|
Constructor Summary
|
Plugin
()
Creates a new plug-in runtime object. |
Plugin
(
IPluginDescriptor descriptor)
Deprecated. 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 is called only for plug-ins
which explicitly require the org.eclipse.core.runtime.compatibility plug-in.
|
|
Method Summary
|
URL
|
find
(
IPath path)
Deprecated. use
FileLocator.find(Bundle, IPath, Map)
|
URL
|
find
(
IPath path,
Map override)
Deprecated. use
FileLocator.find(Bundle, IPath, Map)
|
Bundle
|
getBundle
()
Returns the bundle associated with this plug-in. |
IPluginDescriptor
|
getDescriptor
()
Deprecated.
IPluginDescriptor was refactored in Eclipse 3.0.
The getDescriptor() method may only be called by plug-ins
which explicitly require the org.eclipse.core.runtime.compatibility plug-in.
See the comments on
IPluginDescriptor and its methods for details.
|
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 new InstanceScope().getNode(<&yourPluginId>). To set default
preferences for your plug-in, use new DefaultScope().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=&quo;org.eclipse.core.runtime.preferences&quo;>
<initializer class=&quo;com.example.MyPreferenceInitializer&quo;/>
</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. 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 is called only for plug-ins which explicitly require the
org.eclipse.core.runtime.compatibility plug-in.
|
void
|
start
(
BundleContext context)
Starts up this plug-in. |
void
|
startup
()
Deprecated. 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 is called only for plug-ins which explicitly require the
org.eclipse.core.runtime.compatibility plug-in.
|
void
|
stop
(
BundleContext context)
Stops this plug-in. |
String
|
toString
()
Returns a string representation of the plug-in, suitable
for debugging purposes only. |
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
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
public Plugin(
IPluginDescriptor descriptor)
-
Deprecated. 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 is called only for plug-ins
which explicitly require the org.eclipse.core.runtime.compatibility plug-in.
- Creates a new plug-in runtime object for the given plug-in descriptor.
Instances of plug-in runtime classes are automatically created
by the platform in the course of plug-in activation.
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.
-
Parameters:
-
descriptor - the plug-in descriptor -
See Also:
-
getDescriptor()
find
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
public final
URL find(
IPath path,
Map 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
public final
IPluginDescriptor getDescriptor()
-
Deprecated.
IPluginDescriptor was refactored in Eclipse 3.0.
The getDescriptor() method may only be called by plug-ins
which explicitly require the org.eclipse.core.runtime.compatibility plug-in.
See the comments on
IPluginDescriptor and its methods for details.
- Returns the plug-in descriptor for this plug-in runtime object.
-
-
-
Returns:
- the plug-in descriptor for this plug-in runtime object
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.
-
IllegalStateException
getPluginPreferences
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 new InstanceScope().getNode(<&yourPluginId>). To set default
preferences for your plug-in, use new DefaultScope().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
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
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=&quo;org.eclipse.core.runtime.preferences&quo;>
<initializer class=&quo;com.example.MyPreferenceInitializer&quo;/>
</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
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
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
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
public void shutdown()
throws
CoreException
-
Deprecated. 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 is called only for plug-ins which explicitly require the
org.eclipse.core.runtime.compatibility plug-in.
- Shuts down this plug-in and discards all plug-in state.
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
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,
as this method will be invoked in the event of a failure during startup.
Note 1: If a plug-in has been 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.
Clients must never explicitly call this method.
-
-
-
Throws:
-
CoreException
- if this method fails to shut down
this plug-in
startup
public void startup()
throws
CoreException
-
Deprecated. 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 is called only for plug-ins which explicitly require the
org.eclipse.core.runtime.compatibility plug-in.
- 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
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.
Plug-in startup code should be robust. In the event of a startup failure,
the plug-in's shutdown method will be invoked automatically,
in an attempt to close open files, etc.
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.
Clients must never explicitly call this method.
-
-
-
Throws:
-
CoreException
- if this plug-in did not start up properly
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
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.
