Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep
Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> org >> eclipse >> core >> [ runtime overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of org.eclipse.core.runtime.Plugin JAVADOC | Sourc code of org.eclipse.core.runtime.Plugin SOURCE | Download org.eclipse.core.runtime.Plugin DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.eclipse.core.runtime
Class Plugin  view Plugin download Plugin.java

java.lang.Object
  extended byorg.eclipse.core.runtime.Plugin
All Implemented Interfaces:
org.osgi.framework.BundleActivator
public abstract class Plugin
extends java.lang.Object
implements org.osgi.framework.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 desireable 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) 55 and stop(BundleContext) 55 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) 55 constructor is used and startup() 55 and shutdown() 55 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) 55 is used and startup() 55 and shutdown() 55 are called as life cycle methods.

Field Summary
private  org.osgi.framework.Bundle bundle
          The bundle associated this plug-in
private  boolean debug
          The debug flag for this plug-in.
private  IPluginDescriptor descriptor
          Deprecated. Marked as deprecated to suppress deprecation warnings.
static java.lang.String PLUGIN_PREFERENCE_SCOPE
          String constant used for the default scope name for legacy Eclipse plug-in preferences.
private  org.eclipse.core.internal.preferences.PreferenceForwarder preferences
          The preference object for this plug-in; initially null meaning not yet created and initialized.
static java.lang.String PREFERENCES_DEFAULT_OVERRIDE_BASE_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.
static java.lang.String PREFERENCES_DEFAULT_OVERRIDE_FILE_NAME
           
 
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() 55 . 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
 java.net.URL find(IPath path)
          Returns a URL for the given path.
 java.net.URL find(IPath path, java.util.Map override)
          Returns a URL for the given path.
 org.osgi.framework.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()
          Returns the preference store for this plug-in.
 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 org.eclipse.core.runtime.preferences.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() {
				MyPlugin.getPlugin().getPluginPreferences().setDefault(key, value);
			}
		}
private  void initializeDescriptor(java.lang.String symbolicName)
          Deprecated. Marked as deprecated to suppress deprecation warnings.
 void internalInitializeDefaultPluginPreferences()
          Internal method.
 boolean isDebugging()
          Returns whether this plug-in is in debug mode.
 java.io.InputStream openStream(IPath file)
          Returns an input stream for the specified file.
 java.io.InputStream openStream(IPath file, boolean localized)
          Returns an input stream for the specified file.
 void savePluginPreferences()
          Saves preferences settings for this plug-in.
 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) 55 . 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(org.osgi.framework.BundleContext context)
          Starts up this plug-in.
 void startup()
          Deprecated. In Eclipse 3.0 this method has been replaced by start(BundleContext context) 55 . 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(org.osgi.framework.BundleContext context)
          Stops this plug-in.
 java.lang.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 java.lang.String PLUGIN_PREFERENCE_SCOPE
String constant used for the default scope name for legacy Eclipse plug-in preferences.

Since:
3.0
See Also:
Constant Field Values

bundle

private org.osgi.framework.Bundle bundle
The bundle associated this plug-in

debug

private boolean debug
The debug flag for this plug-in. The flag is false by default. It can be set to true either by the plug-in itself or in the platform debug options.

descriptor

private IPluginDescriptor descriptor
Deprecated. Marked as deprecated to suppress deprecation warnings.

The plug-in descriptor.

PREFERENCES_DEFAULT_OVERRIDE_BASE_NAME

public static final java.lang.String PREFERENCES_DEFAULT_OVERRIDE_BASE_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

PREFERENCES_DEFAULT_OVERRIDE_FILE_NAME

public static final java.lang.String PREFERENCES_DEFAULT_OVERRIDE_FILE_NAME
See Also:
Constant Field Values

preferences

private org.eclipse.core.internal.preferences.PreferenceForwarder preferences
The preference object for this plug-in; initially null meaning not yet created and initialized.

Since:
2.0
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

public Plugin(IPluginDescriptor descriptor)
Deprecated. In Eclipse 3.0 this constructor has been replaced by Plugin() 55 . 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.

Method Detail

find

public final java.net.URL find(IPath path)
Returns a URL for the given path. Returns null if the URL could not be computed or created.

find

public final java.net.URL find(IPath path,
                               java.util.Map override)
Returns a URL for the given path. Returns null if the URL could not be computed or created.

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.

getLog

public final ILog getLog()
Returns the log for this plug-in. If no such log exists, one is created.

getStateLocation

public final IPath getStateLocation()
                             throws java.lang.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.

getPluginPreferences

public final Preferences getPluginPreferences()
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.

Since:
2.0

savePluginPreferences

public final void savePluginPreferences()
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

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 org.eclipse.core.runtime.preferences.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() {
				MyPlugin.getPlugin().getPluginPreferences().setDefault(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()
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.

openStream

public final java.io.InputStream openStream(IPath file)
                                     throws java.io.IOException
Returns an input stream for the specified file. The file path must be specified relative this the plug-in's installation location.

openStream

public final java.io.InputStream openStream(IPath file,
                                            boolean localized)
                                     throws java.io.IOException
Returns an input stream for the specified file. The file path must be specified relative to this plug-in's installation location. Optionally, the platform searches for the correct localized version of the specified file using the users current locale, and Java naming convention for localized resource files (locale suffix appended to the specified file extension).

The caller must close the returned stream when done.

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.

shutdown

public void shutdown()
              throws CoreException
Deprecated. In Eclipse 3.0 this method has been replaced by stop(BundleContext context) 55 . 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.

startup

public void startup()
             throws CoreException
Deprecated. In Eclipse 3.0 this method has been replaced by start(BundleContext context) 55 . 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.

toString

public java.lang.String toString()
Returns a string representation of the plug-in, suitable for debugging purposes only.

start

public void start(org.osgi.framework.BundleContext context)
           throws java.lang.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.

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.

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.

Clients must never explicitly call this method.

Specified by:
start in interface org.osgi.framework.BundleActivator
Since:
3.0

initializeDescriptor

private void initializeDescriptor(java.lang.String symbolicName)
Deprecated. Marked as deprecated to suppress deprecation warnings.

stop

public void stop(org.osgi.framework.BundleContext context)
          throws java.lang.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, as this method will be invoked in the event of a failure during startup.

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.

Clients must never explicitly call this method.

Specified by:
stop in interface org.osgi.framework.BundleActivator
Since:
3.0

getBundle

public final org.osgi.framework.Bundle getBundle()
Returns the bundle associated with this plug-in.

Since:
3.0
Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> org >> eclipse >> core >> [ runtime overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of org.eclipse.core.runtime.Plugin JAVADOC | Sourc code of org.eclipse.core.runtime.Plugin SOURCE | Download org.eclipse.core.runtime.Plugin DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD