Incompatibilities between Eclipse 3.1 and 3.2

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.

  1. Resources are no longer necessarily in the local file system
  2. API changes to MultiPageEditorSite
  3. Content changes in config.ini
  4. Content changes in jnlp deployed applications
  5. Explicit calls to Bundle.start() force the bundle to be activated on next restart
  6. Underscore no longer replaced by hyphen in plug-ins version numbers

1. Resources are no longer necessarily in the local file system

What is affected:Clients of the IWorkspace API that assume resources are stored in the local file system.

Description: Prior to Eclipse 3.2, each existing IResource had a corresponding file or directory in a file system accessible by java.io.File. 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 java.io.File.

Action required: The old method IResource.getLocation() 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 getLocation() did so in order to obtain an instance of java.io.File, which can no longer be used for resources that are not stored in the local file system.

The new org.eclipse.core.filesystem plug-in provides a generic file system API that can be used in place of java.io.File. In particular, an instance of org.eclipse.core.filesystem.IFileStore provides most of the same methods that are available on java.io.File. The following snippet of code obtains an instance of IFileStore for a given resource:

   IResource resource = ...;//some resource
   IFileStore store = EFS.getStore(resource.getLocationURI());

The following table provides equivalent methods on IFileStore for operations usually done with java.io.File:

java.io.FileIFileStore
deletedelete
getNamegetName
getParentgetParent
listchildNames
mkdirmkdir(EFS.SHALLOW, null)
mkdirsmkdir(EFS.NONE, null)
renameTomove
new FileInputStream(file)openInputStream
new FileOutputStream(file)openOutputStream

In the IFileStore API, most information about a file is stored in a structure called IFileInfo, obtained by calling IFileStore.fetchInfo(). This design allows for greater optimization over code using java.io.File, because many attributes about a file can often be obtained with a single file system call. Note that the information in an IFileInfo 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 java.io.File that have equivalent methods on IFileInfo:

java.io.FileIFileInfo
canWriteisReadOnly
existsexists
getNamegetName
isDirectoryisDirectory
isFile!isDirectory()
isHiddenisHidden
lastModifiedgetLastModified
lengthgetLength
setLastModifiedsetLastModified
setReadOnlysetAttribute(EFS.ATTRIBUTE_READ_ONLY, true)

As a concrete example, code that was previously calling java.io.File.exists() can now call IFileStore.fetchInfo().exists(). When a IFileInfo is modified, the result needs to be stored back using the IFileStore.putInfo method. For example, this snippet flips the read only attribute on a file

   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);

IProjectDescription.getLocation()

As with the getLocation() method, the project description's location may no longer be in the local file system. The method IProjectDescription.getLocationURI() can be used to obtain the location of a resource in an arbitrary file system.

Local caching

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 java.util.zip.ZipFile). In these cases, you can ask an IFileStore to return a cached local copy of its contents:

   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);

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.

Graceful failure

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 scheme. This can be obtained from a resource as follows:

   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
   }

If you have an IFileStore instance in hand, you can obtain the scheme as follows:

   IFileStore store = ...;//a file store
   store.getFileSystem().getScheme();

2. API changes to MultiPageEditorSite

What is affected: Clients that call MultiPageEditorSite.progressStart() or MultiPageEditorSite.progressEnd().

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

Action required: Clients calling MultiPageEditorSite.progressStart() or MultiPageEditorSite.progressEnd() should switch to using IWorkbenchSiteProgressService instead.

3. Content changes in config.ini

What is affected: Clients who have a custom a config.ini and are moving their application to 3.2.

Description: Prior to 3.2, the typical value for osgi.bundles contained in the config.ini was org.eclipse.core.runtime@2:start, org.eclipse.update.configurator@3:start. Because of the runtime refactoring, this value needs to be updated for the application to successfully start.

Action required:Change the value of osgi.bundles to includes org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@3:start, org.eclipse.core.runtime@start.

4. Content changes in jnlp deployed applications

What is affected: Clients deploying RCP applications and specified a value to osgi.bundles.

Description: Prior to 3.2, the typical value for osgi.bundles contained in the main jnlp file was org.eclipse.core.runtime@2:start, org.eclipse.update.configurator@3:start. Because of the runtime refactoring, this value needs to be updated otherwise NullPointerExceptions could be thrown preventing the application to start.

Action required:Change the value of osgi.bundles to includes org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@3:start, org.eclipse.core.runtime@start.

5. Explicit calls to Bundle.start() force the bundle to be activated on next restart

What is affected: Clients that call Bundle.start().

Description: In Eclipse a bundle is specified to be a lazy start bundle by using the Eclipse-LazyStart header (or the deprecated Eclipse-AutoStart header). In Eclipse 3.1, the method org.osgi.framework.Bundle.start() 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 Bundle.start() states that the following must occur when the method is called:

"Persistently record that this bundle has been started. When the Framework is restarted, this bundle must be automatically started."

In Eclipse 3.2 the Bundle.start() 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 Bundle.start() 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 bug 134412.

Action required: Clients of Bundle.start() 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 Bundle.start() 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 Bundle.loadClass() to load a class from the bundle which needs to be activated instead of calling Bundle.start().

5. Underscore no longer replaced by hyphen in plug-in version numbers

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