platform-core/documents/rfc/0010/dynamic_capabilities.html - www.eclipse.org/eclipse - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN2">
 <html>
 <head>
 <title>Markup to express bundle dynamic capabilities.</title>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
     <meta http-equiv="Content-Style-Type" content="text/css">
     <link href="http://dev.eclipse.org/default_style.css" rel="stylesheet" type="text/css">
 </head>
 <body bgcolor="#ffffff">

 <table width="100%">
 <tr><td style="background:#0080C0"><b><span style="color:white">RFC</span></b></td></tr>

 </table>

 <h1>Markup to express bundle dynamic capabilities.</h1>

 <blockquote> <b>Summary</b><br>
 This RFC highlights the need for bundles to express their dynamic capabilities and proposes a solution based on the introduction of a new header in the manifest.mf.
 <p>
 <font size="-1">Last modified: Decemver 1, 2004 - revision 2, <a href="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/platform-core-home/documents/rfc/0010/dynamic_capabilities.html?rev=1.5">previous revision</a></font>
 </blockquote>
 <p>
 <h3>Background</h3>
 <p>
 In 3.0 the concept of a dynamic plugin has been introduced. Even though some infrastructure has been added, plugins did not become automatically / magically dynamic. Some work was expected by the plugin writers.
 This resulted in the eclipse 3.0 SDK being only partially dynamic possibly leading to strange behavior. Indeed, because the runtime and some other plugins are dynamic, it is possible to install and uninstall plug-ins and be under the impression that everything worked fine.
 For example if a new builder is being added, it will not be picked up because org.eclipse.core.resources is not dynamic aware.
 <p>
 Being able to detect such things is important for the user, since they can lead to incorrect behavior of the system.
 <p>

 <h3>Proposed solution</h3>
 <p>
 Plugins must be able to express their dynamic capabilities in order to enable runtime and development time checks. This markup is purely descriptive and
 will not interfere with the behavior of plugins. There is several levels of dynamic capabilities:
 <ul>
 	<li> A bundle / plugin can be dynamic enabled."Most importantly, to be dynamic enabled, your plug-in has to properly clean up after itself in the Plugin shutdown method." ( FAQ 117). This is the behavior that has been recommanded since eclipse 1.0.</li>
  	<li> A bundle / plugin can be addition aware. It will take into account new bundles being added to the system. For example this means tracking extension / extension poins and/or new bundles being installed, started.</li>
 	<li> A bundle / plugin can be removal aware. It will take into account bundles being removed from the system. For example this means tracking extension / extension poins and releasing the objects from the bundles being uninstalled.</li>
 	<li> A bundle / plugin can be not dynamic at all.</li>
 </ul>
 <p>
 Because being dynamic is not a property reserved for bundles declaring extensions, this characteristic is being captured in the bundle manifest by the following header: <tt>Eclipse-Dynamic:</tt> whose values are either
 <tt>enabled</tt>, <tt>addition-aware</tt>, <tt>removal-aware</tt> or <tt>unspecified</tt> and are separated by semi colons. It is important to note that there is no relation among the values. For example being addition-aware
 does <u>not</u> include enabled.
 <p>
 <tt>
 Eclipse-Dynamic: enabled; addition-aware; removal-aware
 </tt>
 <p>
 <h3>Default values</h3>
 This section describes the default values that are infered when the <code>Eclipse-Dynamic</code> is absent from the manifest.mf, or that are generated from plugin.xml.<br>
 The following list gives for each case the value:
 <li>
   <ul>2.1 plugin: unspecified - generated by the plugin converter</ul>
   <ul>3.0/3.1 plugin (without manifest.mf): unspecified - generated by the plugin converter</ul>
   <ul>3.0/3.1 plugin (with a manifest.mf): unspecified - infered</ul>
   <ul>OSGi R3.0 Bundle: enabled, addition-aware, removal-aware</ul>
   <ul>OSGi R4.0 Bundle: enabled, addition-aware, removal-aware</ul>
 </li>
 eclipse. In this case, the following value should be infered: "<tt>Eclipse-Dynamic: enabled, addition-aware, removal-aware</tt>.
 </p>
 <h3>Usage</h3>
 <h4>Tools</h4>
 There are two main use cases for this markup:
 <ul>
 <li>PDE which given a target platform could check if all plugins are dynamic enabled, support removal, etc.</li>
 <li>Configurators and installers could check on addition or removal if the system needs to be restarted.</li>
 </ul>
 <p>
 <h4>Recommanded usage behavior</h4>
 When a plugin P is being added to a running instance of eclipse<br>
 <pre>
 	for all P's prerequisite (transitively)
 		if prereq is addition-aware
 			OK
 		else
 			if prereq is not active
 				OK
 			else
 				return Need to reboot
 			end if
 		end if
 	end for
 	return OK;
 </pre>
 <p>
 When a plugin P is being removed from a running instance of eclipse<br>
 <pre>
 	for all P's prerequisite (transitively)
 		if prereq is removal-aware
 			OK
 		else
 			if prereq is not active
 				OK
 			else
 				return Need to reboot
 			end if
 		end if
 	end for

 	for all plugins requiring P
 		if requiringPlugin is not enabled && requiringPlugin is active
 			return Need to reboot
 		end if
 	end for
 	return OK;
 </pre>
 <p>
 <h3>Changes required</h3>
 As a plug-in writer, no changes are absolutely required. If you are expecting your plug-ins to run in a dynamic environment, it might be a good thing
 to review the code and set the appropriate value. If the dynamic capability is overstated by a plug-in and bugs results from that, this will be considered as a bug.
 <p>
 Given that the format of a manifest.mf is open ended, the addition of this new header can be done immediatly. <br>
 The first change to do is to update the PluginManifest converter to generate default values.<br>
 PDE and other configurators can be updated at their own schedule.<br>
 <p>

 <h3>Other solutions considered</h3>
 <p>
 1 - Runtime defines an extension point and every plugin declares by an extension it dynamic capability. This has the drawback of forcing the addition of a plugin.xml in all pure bundle (like junit, tomcat, swt). <br>
 A varient on that was to provide a generic extension point for people to declare other capabilities such as "running without instance location" , "running without configuration location".<br>
 Given that the manifest is open ended, those capabilities can be expressed in the manifest if needed.<br>
 <p>

 2 - Special markup in the plugin.xml. Drawbacks are the same than in the previous solution and more over it was requiring PDE and runtime to change their plugin parsers.
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN2">
	<html>
	<head>
	<title>Markup to express bundle dynamic capabilities.</title>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<meta http-equiv="Content-Style-Type" content="text/css">
	<link href="http://dev.eclipse.org/default_style.css" rel="stylesheet" type="text/css">
	</head>
	<body bgcolor="#ffffff">

	<table width="100%">
	<tr><td style="background:#0080C0"><b><span style="color:white">RFC</span></b></td></tr>

	</table>

	<h1>Markup to express bundle dynamic capabilities.</h1>

	<blockquote> <b>Summary</b><br>
	This RFC highlights the need for bundles to express their dynamic capabilities and proposes a solution based on the introduction of a new header in the manifest.mf.
	<p>
	<font size="-1">Last modified: Decemver 1, 2004 - revision 2, <a href="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/platform-core-home/documents/rfc/0010/dynamic_capabilities.html?rev=1.5">previous revision</a></font>
	</blockquote>
	<p>
	<h3>Background</h3>
	<p>
	In 3.0 the concept of a dynamic plugin has been introduced. Even though some infrastructure has been added, plugins did not become automatically / magically dynamic. Some work was expected by the plugin writers.
	This resulted in the eclipse 3.0 SDK being only partially dynamic possibly leading to strange behavior. Indeed, because the runtime and some other plugins are dynamic, it is possible to install and uninstall plug-ins and be under the impression that everything worked fine.
	For example if a new builder is being added, it will not be picked up because org.eclipse.core.resources is not dynamic aware.
	<p>
	Being able to detect such things is important for the user, since they can lead to incorrect behavior of the system.
	<p>

	<h3>Proposed solution</h3>
	<p>
	Plugins must be able to express their dynamic capabilities in order to enable runtime and development time checks. This markup is purely descriptive and
	will not interfere with the behavior of plugins. There is several levels of dynamic capabilities:
	<ul>
	<li> A bundle / plugin can be dynamic enabled."Most importantly, to be dynamic enabled, your plug-in has to properly clean up after itself in the Plugin shutdown method." ( FAQ 117). This is the behavior that has been recommanded since eclipse 1.0.</li>
	<li> A bundle / plugin can be addition aware. It will take into account new bundles being added to the system. For example this means tracking extension / extension poins and/or new bundles being installed, started.</li>
	<li> A bundle / plugin can be removal aware. It will take into account bundles being removed from the system. For example this means tracking extension / extension poins and releasing the objects from the bundles being uninstalled.</li>
	<li> A bundle / plugin can be not dynamic at all.</li>
	</ul>
	<p>
	Because being dynamic is not a property reserved for bundles declaring extensions, this characteristic is being captured in the bundle manifest by the following header: <tt>Eclipse-Dynamic:</tt> whose values are either
	<tt>enabled</tt>, <tt>addition-aware</tt>, <tt>removal-aware</tt> or <tt>unspecified</tt> and are separated by semi colons. It is important to note that there is no relation among the values. For example being addition-aware
	does <u>not</u> include enabled.
	<p>
	<tt>
	Eclipse-Dynamic: enabled; addition-aware; removal-aware
	</tt>
	<p>
	<h3>Default values</h3>
	This section describes the default values that are infered when the <code>Eclipse-Dynamic</code> is absent from the manifest.mf, or that are generated from plugin.xml.<br>
	The following list gives for each case the value:
	<li>
	<ul>2.1 plugin: unspecified - generated by the plugin converter</ul>
	<ul>3.0/3.1 plugin (without manifest.mf): unspecified - generated by the plugin converter</ul>
	<ul>3.0/3.1 plugin (with a manifest.mf): unspecified - infered</ul>
	<ul>OSGi R3.0 Bundle: enabled, addition-aware, removal-aware</ul>
	<ul>OSGi R4.0 Bundle: enabled, addition-aware, removal-aware</ul>
	</li>
	eclipse. In this case, the following value should be infered: "<tt>Eclipse-Dynamic: enabled, addition-aware, removal-aware</tt>.
	</p>
	<h3>Usage</h3>
	<h4>Tools</h4>
	There are two main use cases for this markup:
	<ul>
	<li>PDE which given a target platform could check if all plugins are dynamic enabled, support removal, etc.</li>
	<li>Configurators and installers could check on addition or removal if the system needs to be restarted.</li>
	</ul>
	<p>
	<h4>Recommanded usage behavior</h4>
	When a plugin P is being added to a running instance of eclipse<br>
	<pre>
	for all P's prerequisite (transitively)
	if prereq is addition-aware
	OK
	else
	if prereq is not active
	OK
	else
	return Need to reboot
	end if
	end if
	end for
	return OK;
	</pre>
	<p>
	When a plugin P is being removed from a running instance of eclipse<br>
	<pre>
	for all P's prerequisite (transitively)
	if prereq is removal-aware
	OK
	else
	if prereq is not active
	OK
	else
	return Need to reboot
	end if
	end if
	end for

	for all plugins requiring P
	if requiringPlugin is not enabled && requiringPlugin is active
	return Need to reboot
	end if
	end for
	return OK;
	</pre>
	<p>
	<h3>Changes required</h3>
	As a plug-in writer, no changes are absolutely required. If you are expecting your plug-ins to run in a dynamic environment, it might be a good thing
	to review the code and set the appropriate value. If the dynamic capability is overstated by a plug-in and bugs results from that, this will be considered as a bug.
	<p>
	Given that the format of a manifest.mf is open ended, the addition of this new header can be done immediatly. <br>
	The first change to do is to update the PluginManifest converter to generate default values.<br>
	PDE and other configurators can be updated at their own schedule.<br>
	<p>

	<h3>Other solutions considered</h3>
	<p>
	1 - Runtime defines an extension point and every plugin declares by an extension it dynamic capability. This has the drawback of forcing the addition of a plugin.xml in all pure bundle (like junit, tomcat, swt). <br>
	A varient on that was to provide a generic extension point for people to declare other capabilities such as "running without instance location" , "running without configuration location".<br>
	Given that the manifest is open ended, those capabilities can be expressed in the manifest if needed.<br>
	<p>

	2 - Special markup in the plugin.xml. Drawbacks are the same than in the previous solution and more over it was requiring PDE and runtime to change their plugin parsers.