bundles/org.eclipse.platform.doc.isv/porting/3.2/incompatibilities.html - platform/eclipse.platform.common - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <html>

 <head>

 <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >

 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
 <meta http-equiv="Content-Style-Type" content="text/css">
 <link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1" type="text/css">
 <title>Incompatibilities between Eclipse 3.1 and 3.2</title>
 </head>

 <body>

 <h1>Incompatibilities between Eclipse 3.1 and 3.2</h1>

 <p> Eclipse changed in incompatible ways between 3.1 and 3.2 in ways that affect
   plug-ins. The following entries describe the areas that changed and provide
   instructions for migrating 3.1 plug-ins to 3.2. Note that you only need to look
   here if you are experiencing problems running your 3.1 plug-in on 3.2.</p>
 <ol>
   <li><a href="#nonLocalResources">Resources are no longer necessarily in the local file system</a></li>
   <li><a href="#MultiPageEditorSiteProgress">API changes to MultiPageEditorSite</a></li>
   <li><a href="#configIni">Content changes in config.ini</a></li>
   <li><a href="#jwsConfigIni">Content changes in jnlp deployed applications</a></li>
   <li><a href="#bundleStart">Explicit calls to Bundle.start() force the bundle to be activated on next restart</a></li>
   <li><a href="#pluginVersion">Underscore no longer replaced by hyphen in plug-ins version numbers</a></li>
 </ol>
 <hr>

 <!-- ############################################## -->
 <h2>1. <a name="nonLocalResources"></a>Resources are no longer necessarily in
   the local file system</h2>
 <p><strong>What is affected:</strong>Clients of the <code>IWorkspace</code> API
 that assume resources are stored in the local file system.</p>
 <p><strong>Description:</strong>
 Prior to Eclipse 3.2, each existing <code>IResource</code> had a corresponding
 file or directory in a file system accessible by <code>java.io.File</code>.  In
 Eclipse 3.2, support was added for creating resources whose contents are stored
 in an arbitrary backing file system.  Resources using this support can no longer
 be represented directly as a <tt>java.io.File</tt>.
 </p>
 <p><strong>Action required:</strong>
 The old method <tt>IResource.getLocation()</tt> returns the local file
 system path of a resource.  This method returns null for resources
 that are not stored in the local file system.  Most callers of <tt>getLocation()</tt>
 did so in order to obtain an instance of <tt>java.io.File</tt>, which can
 no longer be used for resources that are not stored in the local file system.
 </p>
 <p>
 The new <tt>org.eclipse.core.filesystem</tt> plug-in provides a generic file
 system API that can be used in place of <tt>java.io.File</tt>.  In particular,
 an instance of <tt>org.eclipse.core.filesystem.IFileStore</tt> provides most
 of the same methods that are available on <tt>java.io.File</tt>. The following
 snippet of code obtains an instance of <tt>IFileStore</tt> for a given resource:</p>
 <pre>
    IResource resource = ...;//some resource
    IFileStore store = EFS.getStore(resource.getLocationURI());
 </pre>
 <p>
 The following table provides equivalent methods on <tt>IFileStore</tt>
 for operations usually done with <tt>java.io.File</tt>:
 </p>
 <table border=1>
 <tr>
 <th align=left>java.io.File</th><th align=left>IFileStore</th>
 </tr>
 <tr><td>delete</td><td>delete</td></tr>
 <tr><td>getName</td><td>getName</td></tr>
 <tr><td>getParent</td><td>getParent</td></tr>
 <tr><td>list</td><td>childNames</td></tr>
 <tr><td>mkdir</td><td>mkdir(EFS.SHALLOW, null)</td></tr>
 <tr><td>mkdirs</td><td>mkdir(EFS.NONE, null)</td></tr>
 <tr><td>renameTo</td><td>move</td></tr>
 <tr><td>new FileInputStream(file)</td><td>openInputStream</td></tr>
 <tr><td>new FileOutputStream(file)</td><td>openOutputStream</td></tr>
 </table>
 <p>
 In the <tt>IFileStore</tt> API, most information about a file is stored in a
 structure called <tt>IFileInfo</tt>, obtained by calling <tt>IFileStore.fetchInfo()</tt>.
 This design allows for greater optimization over code using <tt>java.io.File</tt>,
 because many attributes about a file can often be obtained with a single file system
 call.  Note that the information in an <tt>IFileInfo</tt> will become stale
 if the underlying file is changed, so instances should only be held onto
 as long as they are needed.  Here are some methods on <tt>java.io.File</tt>
 that have equivalent methods on <tt>IFileInfo</tt>:
 </p>
 <table border=1>
 <tr><th align=left>java.io.File</th><th align=left>IFileInfo</th></tr>
 <tr><td>canWrite</td><td>getAttribute(EFS.ATTRIBUTE_READ_ONLY)</td></tr>
 <tr><td>exists</td><td>exists()</td></tr>
 <tr><td>getName</td><td>getName()</td></tr>
 <tr><td>isDirectory</td><td>isDirectory()</td></tr>
 <tr><td>isFile</td><td>!isDirectory()</td></tr>
 <tr><td>isHidden</td><td>getAttribute(EFS.ATTRIBUTE_HIDDEN)</td></tr>
 <tr><td>lastModified</td><td>getLastModified()</td></tr>
 <tr><td>length</td><td>getLength()</td></tr>
 <tr><td>setLastModified</td><td>setLastModified(long)</td></tr>
 <tr><td>setReadOnly</td><td>setAttribute(EFS.ATTRIBUTE_READ_ONLY, true)</td></tr>
 </table>
 <p>
 As a concrete example, code that was previously calling <tt>java.io.File.exists()</tt>
 can now call <tt>IFileStore.fetchInfo().exists()</tt>.  When a <tt>IFileInfo</tt>
 is modified, the result needs to be stored back using the <tt>IFileStore.putInfo</tt>
 method. For example, this snippet flips the read only attribute on a file
 </p>
 <pre>
    IFileStore store = ...;//some file store
    IFileInfo info = store.fetchInfo();
    boolean readOnly = info.getAttribute(EFS.ATTRIBUTE_READ_ONLY);
    info.setAttribute(EFS.ATTRIBUTE_READ_ONLY, !readOnly);
    store.putInfo(info, EFS.SET_ATTRIBUTES, null);
 </pre>
 <h4>IProjectDescription.getLocation()</h4>
 <p>
 As with the <tt>getLocation()</tt> method, the project description's location
 may no longer be in the local file system.  The method
 <tt>IProjectDescription.getLocationURI()</tt> can be used to obtain the location
 of a resource in an arbitrary file system.
 </p>
 <h4>Local caching</h4>
 <p>
 Some clients absolutely must have a local representation of a file.  For example,
 they may be launching a native tool against that file, or using non Eclipse-aware
 libraries that can only handle file system resources (such as <tt>java.util.zip.ZipFile</tt>).
 In these cases, you can ask an IFileStore to return a cached local copy of its contents:
 </p>
 <pre>
    IFileStore store = ...;//some file store
    //see if it can directly be represented as a local file
    java.io.File local = store.toLocalFile(EFS.NONE, null);
    //if not, ask for a cached local copy of the file
    if (local == null)
       local = store.toLocalFile(EFS.CACHE, null);
 </pre>
 <p>
 Note that once a cached copy of a file is obtained, it does not remain in sync with
 the actual file system it came from.  Modifying the cached copy will not cause the
 underlying file to be modified.
 </p>
 <h4>Graceful failure</h4>
 <p>
 Clients that cannot handle resources outside the local file system may still
 want to adapt their code to fail more gracefully. Clients can check if a resource
 is in the local file system, and either ignore the resource or alert the user when
 they encouter a resource they cannot handle.  To determine if a resource is
 in the local file system, you need to find out its file system <i>scheme</i>.
 This can be obtained from a resource as follows:
 </p>
 <pre>
    IResource resource = ...;//some resource
    URI uri = resource.getLocationURI();
    if (uri != null &amp;&amp; EFS.SCHEME_LOCAL.equals(uri.getScheme())) {
       //file is in local file system
    } else {
       //file is not in the local file system
    }
 </pre>
 <p>
 If you have an <tt>IFileStore</tt> instance in hand, you can obtain the scheme
 as follows:
 </p>
 <pre>
    IFileStore store = ...;//a file store
    store.getFileSystem().getScheme();
 </pre>

 <!-- ############################################## -->
 <h2>2. <a name="MultiPageEditorSiteProgress"></a>API changes to MultiPageEditorSite</h2>
 <p><strong>What is affected:</strong> Clients that call <code>MultiPageEditorSite.progressStart()</code> or <code>MultiPageEditorSite.progressEnd()</code>.</p>
 <p><strong>Description:</strong> During Eclipse 3.0 development, these
   methods were added as part of the progress support work.  Before the 3.0
   release, the way in which progress was handled was changed, and this method
   was no longer necessary.  Through programmer error, these public methods were
   left in for the 3.0 release.  These two methods have never served any function
   in an Eclipse release, and so have been deleted.</p>
 <p><strong>Action required:</strong> Clients calling
   <code>MultiPageEditorSite.progressStart()</code> or
   <code>MultiPageEditorSite.progressEnd()</code> should switch to using
   <code>IWorkbenchSiteProgressService</code> instead.</p>

 <!-- ############################################## -->

 <!-- ############################################## -->
 <h2>3. <a name="configIni"></a>Content changes in config.ini</h2>
 <p><strong>What is affected:</strong> Clients who have a custom a config.ini and are moving their application to 3.2.
 </p>
 <p><strong>Description:</strong> Prior to 3.2, the typical value for osgi.bundles contained in the config.ini was  <code>org.eclipse.core.runtime@2:start, org.eclipse.update.configurator@3:start</code>.
 Because of the <a href="recommended.html#runtimeSplit">runtime refactoring</a>, this value needs to be updated for the application to successfully start.
 </p>
 <p><strong>Action required:</strong>Change the value of osgi.bundles to includes <code>org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@3:start,
 org.eclipse.core.runtime@start.</code>
 </p>
 <!-- ############################################## -->


 <!-- ############################################## -->
 <h2>4. <a name="jwsConfigIni"></a>Content changes in jnlp deployed applications</h2>
 <p><strong>What is affected:</strong> Clients deploying RCP applications and specified a value to osgi.bundles.
 </p>
 <p><strong>Description:</strong> Prior to 3.2, the typical value for osgi.bundles contained in the main jnlp file was  <code>org.eclipse.core.runtime@2:start, org.eclipse.update.configurator@3:start</code>.
 Because of the <a href="recommended.html#runtimeSplit">runtime refactoring</a>, this value needs to be updated otherwise <code>NullPointerException</code>s could be thrown preventing the application to start.
 </p>
 <p><strong>Action required:</strong>Change the value of osgi.bundles to includes <code>org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@3:start,
 org.eclipse.core.runtime@start.</code>
 </p>
 <!-- ############################################## -->

 <!-- ############################################## -->
 <h2>5. <a name="bundleStart"></a>Explicit calls to Bundle.start() force the bundle
   to be activated on next restart</h2>
 <p><strong>What is affected:</strong> Clients that call <code>Bundle.start()</code>.
 </p>
 <p><strong>Description:</strong>
   In Eclipse a bundle is specified to be a lazy start bundle
   by using the <code>Eclipse-LazyStart</code> header (or the deprecated
   <code>Eclipse-AutoStart</code> header).  In Eclipse 3.1, the method
   <code>org.osgi.framework.Bundle.start()</code> did not mark lazy start bundles as
   persistently started.  Since lazy start bundles never got marked as persistently
   started they would not be automatically started when eclipse was restarted.  The
   javadoc for <code>Bundle.start()</code> states that the following must occur when the method is called:
 </p>
 <p>
   &quot;Persistently record that this bundle has been started. When the Framework is restarted, this bundle must be automatically started.&quot;
 </p>
 <p>
   In Eclipse 3.2 the <code>Bundle.start()</code> method has been fixed to properly mark
   the bundle as persistently started even if the bundle is a lazy start bundle.  This fix
   was required to comply with the OSGi Framework specification.  As a result callers of
   <code>Bundle.start()</code> will force the bundle to be started when Eclipse is restarted.
   In general this is considered a bad practice because it will cause unnecessary bundles to
   be activated each time Eclipse is started.  In some cases it can cause unexpected results
   such as <a href=https://bugs.eclipse.org/bugs/show_bug.cgi?id=134412>bug 134412</a>.
 </p>
 <p><strong>Action required:</strong> Clients of <code>Bundle.start()</code> need to evaluate
   if their intention is to persistently activate the bundle for every restart.  If that is
   not the intention then clients should find another way to activate the bundle.  In most
   cases calls <code>Bundle.start()</code> can be avoided by simply allowing the target bundle
   to be lazily activated when classes are loaded from them.  There are rare scenarios that
   require a lazy start bundle to be agressively activated, but not persistenly marked for
   activation on a restart.  These types of scenarios should use <code>Bundle.loadClass()</code>
   to load a class from the bundle which needs to be activated instead of calling
   <code>Bundle.start()</code>.
 </p>
 <!-- ############################################## -->
 <h2>5. <a name="pluginVersion"></a>Underscore no longer replaced by hyphen in plug-in version numbers</h2>
 <p>
 In Eclipse 3.0, the use of an underscore ('_') character in the qualifier segment of a version identifier
 was not supported, but also was not enforced. If a plug-in version identifier contained an underscore in the qualifier,
 then this character was transformed to a hyphen ('-') when exporting the plug-in to the file-system and also when installing the plug-in from an update site.
 <br>
 In Eclipse 3.1 the rules for characters allowed in qualifiers was relaxed to include the underscore character, so
 when an offending plug-in was exported or installed the qualifier was not modified from its original state.
 This subtle change was accidently left out from the migration guide for 3.0 to 3.1.

 The story going forward (and for Eclipse 3.2) is that we are maintaining compatibility with Eclipse 3.1
 and plug-ins who use underscore characters in their version qualifiers, should be aware of the aforementioned changes when
 dealing with old plug-in versions (both when exporting and when they exist on update sites). This means, for instance,
 that plug-in providers who have old versions of their plug-in on an update site should ensure that the name in the file-system matches the name of the plug-in.
 </p>
 <!-- ############################################## -->
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	<html>

	<head>

	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >

	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<meta http-equiv="Content-Style-Type" content="text/css">
	<link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1" type="text/css">
	<title>Incompatibilities between Eclipse 3.1 and 3.2</title>
	</head>

	<body>

	<h1>Incompatibilities between Eclipse 3.1 and 3.2</h1>

	<p> Eclipse changed in incompatible ways between 3.1 and 3.2 in ways that affect
	plug-ins. The following entries describe the areas that changed and provide
	instructions for migrating 3.1 plug-ins to 3.2. Note that you only need to look
	here if you are experiencing problems running your 3.1 plug-in on 3.2.</p>
	<ol>
	<li><a href="#nonLocalResources">Resources are no longer necessarily in the local file system</a></li>
	<li><a href="#MultiPageEditorSiteProgress">API changes to MultiPageEditorSite</a></li>
	<li><a href="#configIni">Content changes in config.ini</a></li>
	<li><a href="#jwsConfigIni">Content changes in jnlp deployed applications</a></li>
	<li><a href="#bundleStart">Explicit calls to Bundle.start() force the bundle to be activated on next restart</a></li>
	<li><a href="#pluginVersion">Underscore no longer replaced by hyphen in plug-ins version numbers</a></li>
	</ol>
	<hr>

	<!-- ############################################## -->
	<h2>1. <a name="nonLocalResources"></a>Resources are no longer necessarily in
	the local file system</h2>
	<p><strong>What is affected:</strong>Clients of the <code>IWorkspace</code> API
	that assume resources are stored in the local file system.</p>
	<p><strong>Description:</strong>
	Prior to Eclipse 3.2, each existing <code>IResource</code> had a corresponding
	file or directory in a file system accessible by <code>java.io.File</code>. In
	Eclipse 3.2, support was added for creating resources whose contents are stored
	in an arbitrary backing file system. Resources using this support can no longer
	be represented directly as a <tt>java.io.File</tt>.
	</p>
	<p><strong>Action required:</strong>
	The old method <tt>IResource.getLocation()</tt> returns the local file
	system path of a resource. This method returns null for resources
	that are not stored in the local file system. Most callers of <tt>getLocation()</tt>
	did so in order to obtain an instance of <tt>java.io.File</tt>, which can
	no longer be used for resources that are not stored in the local file system.
	</p>
	<p>
	The new <tt>org.eclipse.core.filesystem</tt> plug-in provides a generic file
	system API that can be used in place of <tt>java.io.File</tt>. In particular,
	an instance of <tt>org.eclipse.core.filesystem.IFileStore</tt> provides most
	of the same methods that are available on <tt>java.io.File</tt>. The following
	snippet of code obtains an instance of <tt>IFileStore</tt> for a given resource:</p>
	<pre>
	IResource resource = ...;//some resource
	IFileStore store = EFS.getStore(resource.getLocationURI());
	</pre>
	<p>
	The following table provides equivalent methods on <tt>IFileStore</tt>
	for operations usually done with <tt>java.io.File</tt>:
	</p>
	<table border=1>
	<tr>
	<th align=left>java.io.File</th><th align=left>IFileStore</th>
	</tr>
	<tr><td>delete</td><td>delete</td></tr>
	<tr><td>getName</td><td>getName</td></tr>
	<tr><td>getParent</td><td>getParent</td></tr>
	<tr><td>list</td><td>childNames</td></tr>
	<tr><td>mkdir</td><td>mkdir(EFS.SHALLOW, null)</td></tr>
	<tr><td>mkdirs</td><td>mkdir(EFS.NONE, null)</td></tr>
	<tr><td>renameTo</td><td>move</td></tr>
	<tr><td>new FileInputStream(file)</td><td>openInputStream</td></tr>
	<tr><td>new FileOutputStream(file)</td><td>openOutputStream</td></tr>
	</table>
	<p>
	In the <tt>IFileStore</tt> API, most information about a file is stored in a
	structure called <tt>IFileInfo</tt>, obtained by calling <tt>IFileStore.fetchInfo()</tt>.
	This design allows for greater optimization over code using <tt>java.io.File</tt>,
	because many attributes about a file can often be obtained with a single file system
	call. Note that the information in an <tt>IFileInfo</tt> will become stale
	if the underlying file is changed, so instances should only be held onto
	as long as they are needed. Here are some methods on <tt>java.io.File</tt>
	that have equivalent methods on <tt>IFileInfo</tt>:
	</p>
	<table border=1>
	<tr><th align=left>java.io.File</th><th align=left>IFileInfo</th></tr>
	<tr><td>canWrite</td><td>getAttribute(EFS.ATTRIBUTE_READ_ONLY)</td></tr>
	<tr><td>exists</td><td>exists()</td></tr>
	<tr><td>getName</td><td>getName()</td></tr>
	<tr><td>isDirectory</td><td>isDirectory()</td></tr>
	<tr><td>isFile</td><td>!isDirectory()</td></tr>
	<tr><td>isHidden</td><td>getAttribute(EFS.ATTRIBUTE_HIDDEN)</td></tr>
	<tr><td>lastModified</td><td>getLastModified()</td></tr>
	<tr><td>length</td><td>getLength()</td></tr>
	<tr><td>setLastModified</td><td>setLastModified(long)</td></tr>
	<tr><td>setReadOnly</td><td>setAttribute(EFS.ATTRIBUTE_READ_ONLY, true)</td></tr>
	</table>
	<p>
	As a concrete example, code that was previously calling <tt>java.io.File.exists()</tt>
	can now call <tt>IFileStore.fetchInfo().exists()</tt>. When a <tt>IFileInfo</tt>
	is modified, the result needs to be stored back using the <tt>IFileStore.putInfo</tt>
	method. For example, this snippet flips the read only attribute on a file
	</p>
	<pre>
	IFileStore store = ...;//some file store
	IFileInfo info = store.fetchInfo();
	boolean readOnly = info.getAttribute(EFS.ATTRIBUTE_READ_ONLY);
	info.setAttribute(EFS.ATTRIBUTE_READ_ONLY, !readOnly);
	store.putInfo(info, EFS.SET_ATTRIBUTES, null);
	</pre>
	<h4>IProjectDescription.getLocation()</h4>
	<p>
	As with the <tt>getLocation()</tt> method, the project description's location
	may no longer be in the local file system. The method
	<tt>IProjectDescription.getLocationURI()</tt> can be used to obtain the location
	of a resource in an arbitrary file system.
	</p>
	<h4>Local caching</h4>
	<p>
	Some clients absolutely must have a local representation of a file. For example,
	they may be launching a native tool against that file, or using non Eclipse-aware
	libraries that can only handle file system resources (such as <tt>java.util.zip.ZipFile</tt>).
	In these cases, you can ask an IFileStore to return a cached local copy of its contents:
	</p>
	<pre>
	IFileStore store = ...;//some file store
	//see if it can directly be represented as a local file
	java.io.File local = store.toLocalFile(EFS.NONE, null);
	//if not, ask for a cached local copy of the file
	if (local == null)
	local = store.toLocalFile(EFS.CACHE, null);
	</pre>
	<p>
	Note that once a cached copy of a file is obtained, it does not remain in sync with
	the actual file system it came from. Modifying the cached copy will not cause the
	underlying file to be modified.
	</p>
	<h4>Graceful failure</h4>
	<p>
	Clients that cannot handle resources outside the local file system may still
	want to adapt their code to fail more gracefully. Clients can check if a resource
	is in the local file system, and either ignore the resource or alert the user when
	they encouter a resource they cannot handle. To determine if a resource is
	in the local file system, you need to find out its file system <i>scheme</i>.
	This can be obtained from a resource as follows:
	</p>
	<pre>
	IResource resource = ...;//some resource
	URI uri = resource.getLocationURI();
	if (uri != null && EFS.SCHEME_LOCAL.equals(uri.getScheme())) {
	//file is in local file system
	} else {
	//file is not in the local file system
	}
	</pre>
	<p>
	If you have an <tt>IFileStore</tt> instance in hand, you can obtain the scheme
	as follows:
	</p>
	<pre>
	IFileStore store = ...;//a file store
	store.getFileSystem().getScheme();
	</pre>

	<!-- ############################################## -->
	<h2>2. <a name="MultiPageEditorSiteProgress"></a>API changes to MultiPageEditorSite</h2>
	<p><strong>What is affected:</strong> Clients that call <code>MultiPageEditorSite.progressStart()</code> or <code>MultiPageEditorSite.progressEnd()</code>.</p>
	<p><strong>Description:</strong> During Eclipse 3.0 development, these
	methods were added as part of the progress support work. Before the 3.0
	release, the way in which progress was handled was changed, and this method
	was no longer necessary. Through programmer error, these public methods were
	left in for the 3.0 release. These two methods have never served any function
	in an Eclipse release, and so have been deleted.</p>
	<p><strong>Action required:</strong> Clients calling
	<code>MultiPageEditorSite.progressStart()</code> or
	<code>MultiPageEditorSite.progressEnd()</code> should switch to using
	<code>IWorkbenchSiteProgressService</code> instead.</p>

	<!-- ############################################## -->

	<!-- ############################################## -->
	<h2>3. <a name="configIni"></a>Content changes in config.ini</h2>
	<p><strong>What is affected:</strong> Clients who have a custom a config.ini and are moving their application to 3.2.
	</p>
	<p><strong>Description:</strong> Prior to 3.2, the typical value for osgi.bundles contained in the config.ini was <code>org.eclipse.core.runtime@2:start, org.eclipse.update.configurator@3:start</code>.
	Because of the <a href="recommended.html#runtimeSplit">runtime refactoring</a>, this value needs to be updated for the application to successfully start.
	</p>
	<p><strong>Action required:</strong>Change the value of osgi.bundles to includes <code>org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@3:start,
	org.eclipse.core.runtime@start.</code>
	</p>
	<!-- ############################################## -->


	<!-- ############################################## -->
	<h2>4. <a name="jwsConfigIni"></a>Content changes in jnlp deployed applications</h2>
	<p><strong>What is affected:</strong> Clients deploying RCP applications and specified a value to osgi.bundles.
	</p>
	<p><strong>Description:</strong> Prior to 3.2, the typical value for osgi.bundles contained in the main jnlp file was <code>org.eclipse.core.runtime@2:start, org.eclipse.update.configurator@3:start</code>.
	Because of the <a href="recommended.html#runtimeSplit">runtime refactoring</a>, this value needs to be updated otherwise <code>NullPointerException</code>s could be thrown preventing the application to start.
	</p>
	<p><strong>Action required:</strong>Change the value of osgi.bundles to includes <code>org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@3:start,
	org.eclipse.core.runtime@start.</code>
	</p>
	<!-- ############################################## -->

	<!-- ############################################## -->
	<h2>5. <a name="bundleStart"></a>Explicit calls to Bundle.start() force the bundle
	to be activated on next restart</h2>
	<p><strong>What is affected:</strong> Clients that call <code>Bundle.start()</code>.
	</p>
	<p><strong>Description:</strong>
	In Eclipse a bundle is specified to be a lazy start bundle
	by using the <code>Eclipse-LazyStart</code> header (or the deprecated
	<code>Eclipse-AutoStart</code> header). In Eclipse 3.1, the method
	<code>org.osgi.framework.Bundle.start()</code> did not mark lazy start bundles as
	persistently started. Since lazy start bundles never got marked as persistently
	started they would not be automatically started when eclipse was restarted. The
	javadoc for <code>Bundle.start()</code> states that the following must occur when the method is called:
	</p>
	<p>
	"Persistently record that this bundle has been started. When the Framework is restarted, this bundle must be automatically started."
	</p>
	<p>
	In Eclipse 3.2 the <code>Bundle.start()</code> method has been fixed to properly mark
	the bundle as persistently started even if the bundle is a lazy start bundle. This fix
	was required to comply with the OSGi Framework specification. As a result callers of
	<code>Bundle.start()</code> will force the bundle to be started when Eclipse is restarted.
	In general this is considered a bad practice because it will cause unnecessary bundles to
	be activated each time Eclipse is started. In some cases it can cause unexpected results
	such as <a href=https://bugs.eclipse.org/bugs/show_bug.cgi?id=134412>bug 134412</a>.
	</p>
	<p><strong>Action required:</strong> Clients of <code>Bundle.start()</code> need to evaluate
	if their intention is to persistently activate the bundle for every restart. If that is
	not the intention then clients should find another way to activate the bundle. In most
	cases calls <code>Bundle.start()</code> can be avoided by simply allowing the target bundle
	to be lazily activated when classes are loaded from them. There are rare scenarios that
	require a lazy start bundle to be agressively activated, but not persistenly marked for
	activation on a restart. These types of scenarios should use <code>Bundle.loadClass()</code>
	to load a class from the bundle which needs to be activated instead of calling
	<code>Bundle.start()</code>.
	</p>
	<!-- ############################################## -->
	<h2>5. <a name="pluginVersion"></a>Underscore no longer replaced by hyphen in plug-in version numbers</h2>
	<p>
	In Eclipse 3.0, the use of an underscore ('_') character in the qualifier segment of a version identifier
	was not supported, but also was not enforced. If a plug-in version identifier contained an underscore in the qualifier,
	then this character was transformed to a hyphen ('-') when exporting the plug-in to the file-system and also when installing the plug-in from an update site.
	<br>
	In Eclipse 3.1 the rules for characters allowed in qualifiers was relaxed to include the underscore character, so
	when an offending plug-in was exported or installed the qualifier was not modified from its original state.
	This subtle change was accidently left out from the migration guide for 3.0 to 3.1.

	The story going forward (and for Eclipse 3.2) is that we are maintaining compatibility with Eclipse 3.1
	and plug-ins who use underscore characters in their version qualifiers, should be aware of the aforementioned changes when
	dealing with old plug-in versions (both when exporting and when they exist on update sites). This means, for instance,
	that plug-in providers who have old versions of their plug-in on an update site should ensure that the name in the file-system matches the name of the plug-in.
	</p>
	<!-- ############################################## -->
	</body>
	</html>