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.
What is affected: Clients that call IJavaReferenceType.getClassLoaderObject()
.
Description: In Eclipse 3.1, the method org.eclipse.jdt.debug.core.IJavaReferenceType.getClassLoaderObject()
was added to IJavaReferenceType
. The method was not specified to
return null
, but could. In Eclipse 3.2, the specification has been
updated to indicate that null
is a valid return value. The behavior
of the method has not changed, but callers should be aware that null
can be returned and should add appropriate checks.
Action required: Clients calling IJavaReferenceType.getClassLoaderObject()
should be modified to handle null
as a return value.
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 plugin 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.File | IFileStore |
---|---|
delete | delete |
getName | getName |
getParent | getParent |
list | childNames |
mkdir | mkdir(EFS.SHALLOW, null) |
mkdirs | mkdir(EFS.NONE, null) |
renameTo | move |
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.File | IFileInfo |
---|---|
canWrite | isReadOnly |
exists | exists |
getName | getName |
isDirectory | isDirectory |
isFile | !isDirectory() |
isHidden | isHidden |
lastModified | getLastModified |
length | getLength |
setLastModified | setLastModified |
setReadOnly | setAttribute(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);
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.
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.
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();
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.
(The following is a template for editing this draft)
What is affected: Describe what clients are affected.
Description: Describe the incompatible changes.
Action required: Describe the action required.