Eclipse Platform Core RFC 0001
Case Variant Collisions During Resource Creation.
The Eclipse workspace is always case-sensitive, but some filesystems are not. This causes
a problem when trying to create a file using the Core API, in the case where
a file already exists at the target location that differs only in case from the file being created.
This document discusses the problem and evaluates various approaches to solving it.
By John Arthorne, OTI.
Created: November 26, 2001
Last Modified: January 4, 2002
Let us define three resource handles:
IProject project = ResourcesPlugin.getWorkspace().getRoot().getProject("Project");
IFile abc = project.getFile("abc.txt");
IFile ABC = project.getFile("ABC.txt");
The initial state of the problem is when project and abc already exist.
If a Core API method is used to create ABC (using either create, copy,
or move API methods), an exception is thrown. The exception
detail states that the file could not be created because it already exists. The contradiction
is that ABC.exists()will return false, since the case sensitive workspace does not
recognize the collision with abc. Likewise, lookup methods such as
project.findMember("ABC.txt") will also fail to locate the existing file abc,
leading the API user to believe that it is ok to go ahead and create ABC.
Note that this is not quite the same as when a case variant already exists in the file system,
but not in the workspace. Following the above example, say a local file "abc.txt" does not
exist in the workspace, but is created externally in the filesystem. In this case, the current
behaviour when a client calls ABC.create() is consistent; it throws an exception
stating that the workspace is out of sync with the local filesystem.
It should be noted that this problem arises from the fact that the platform case sensitivity
does not always match the case sensitivity of the underlying filesystem. In most cases,
this inconsistency can be handled by the platform core without requiring special handling
by callers of core API. However, this situation represents one rare corner case that cannot be
resolved silently. This is because "under the covers" resolution would require core to
delete files from the filesystem without user awareness.
The proposal is to add a new core status code, IResourceStatus.CASE_VARIANT_EXISTS.
This status code would be included in exceptions from all create, copy,
or move API methods in the IResource hierarchy, when a case variant already exists
at the target location. The exception will also include an appropriate error message
describing why the creation couldn't continue.
- This solution allows clients to recognize the situation and act accordingly. Core cannot determine
the appropriate behaviour for all cases when this problem occurs, so the decision must
be left to the caller. For example, say a resource "/Project/abc/myfile.txt" already exists.
A client wants to create a file called "/Project/ABC/anotherfile.txt". When they attempt to
create folder ABC, a failure occurs because of the case variant collision. In this situation,
the caller may know that the case of the folder isn't important, and they'll just go ahead and create
"/Project/abc/anotherfile.txt". In another situation, the caller may decide it is better
to delete the existing "abc" folder, and create the new "ABC" folder in its place. In a third situation,
the client may decide to defer the question to the user.
- Minimal impact on downstream clients. This fix requires no breaking API changes, and the
new behaviour is similar to the old behaviour. In both new and old approaches, an exception is
thrown -- the only thing that has changed is the status code.
Feedback: Each project can be associated with a different repository
and the versioning abilities of that project are governed by the target repository (adapter).
It seems strange that we would not argue that a project's case sensitive behavior wouldn't
be based on the target file system it was stored on.
- Status codes are fuzzy API. API methods do not formally guarantee what status
codes will be returned for a given error condition. The status codes could theoretically
change at any time without warnings or deprecations.
New comment: while the status codes returned by a particular
method are technically fuzzy, we strive to avoid changing return status codes without a
very compelling reason and sufficient advance notice. The code constant and value are API
and will not change.
- Feedback: There is still an inconsistency between the behaviour
of exists and create.
Response: Yes, you could argue that this approach would give a more
consistent user experience. However, this would unfortunately require a radical redesign
and a major overhaul of large amounts of platform code. What this solution proposes
is the best we could come up with under the constraints of the existing architecture.
This section describes proposed alternative solutions, and some comments on them.
More alternative solutions will be added as they are raised during discussion. Please
feel free to add to or dispute any pros and cons already listed.
Make the Workspace Case-Sensitivity Match the Filesystem
With this approach, when the Eclipse workspace is run on a case-insensitive operating
system, the workspace would never be case-sensitive. On case-sensitive operating
systems, the workspace would always be case-sensitive.
- Behaviour is consistent with the underlying filesystem
- Core API methods are always consistent with each other. If there is a failure
to create because the target already exists, then exists and findMember
methods will also find the target in all cases.
- Performance. This approach would have a huge performance cost. The critical
performance path for the workspace is lookups in the resource tree. This lookup
is based on a high performance binary search in the resource tree. This search cannot
be performed as efficiently when ignoring case.
- Inconsistency gets pushed up to higher layers. In many cases this approach
merely moves the file-system inconsistency problems up to other plugins. Callers of
Core API can currently rely on it always being case-sensitive, and can act accordingly.
Core is able to handle some of these inconsistent situations without involving client
Feedback: You could argue that providing a case sensitive workspace
in the absence of a case sensitive file system is also pushing up an inconsistency to layers
above that may also need to deal with external tools?
- Inconsistencies still possible when workspace spans filesystems. If the
user has a workspace where some projects are mounted on a case-sensitive
filesystem, and others are mounted on a case-insensitive filesystem, there would still be
an inconsistency. Such a setup would undoubtedly cause widespread problems for
downstream plug-ins trying to manage such an inconsistent workspace.
This proposal is has been voted on and accepted.