Community
Participate
Working Groups
The API for IWorkspaceRoot#getFileForLocation(IPath) is unclear about the nature of the returned IFile. Specifically, it is hard to tell from the API if the returned file is guaranteed to exist and when null can be returned. The first sentence ends with "or null if none". It would be helpful to clarify exactly what "if none" means. Does it mean "if no file exists at the given path"? This interpretation doesn't seem correct in light of the third sentence, but the reader isn't given any clues about what else might cause a null value to be returned. What does a null return value mean? /** * Returns a handle to the file which is mapped to the given path * in the local file system, or <code>null</code> if none. * The path must be absolute; its segments need not be valid names. * The resulting file need not exist in the workspace. * <p> * Warning: This method ignores linked resources and their children. Since * linked resources may overlap other resources, a unique mapping from a * file system location to a single resource is not guaranteed. To find all * resources for a given location, including linked resources, use the method * <code>findFilesForLocation</code>. * </p> * * @param location a path in the local file system * @return the corresponding file in the workspace, * or <code>null</code> if none */ public IFile getFileForLocation(IPath location);
Would it be sufficient clarification to add the following sentence? * This method returns null when the given file system location is not under * the location of any existing project in the workspace.
The main point of confusion here (for me, at least) is the difference between the method returning null and the method returning a handle to a file that doesn't exist. Based on your addition, I can guess that the first sentence means: "Returns a handle to the file which is mapped to the given path in the local file system, or <code>null</code> if the given path does not map to a project within the workspace." So if you have a workspace with projects Foo and Bar, a path that starts with Foo or Bar will always return a file (though it might not exist), but a path starting with Baz would return null?
That's correct. If your workspace contains two projects at c:\ws\Foo and c:\ws\Bar, then getFileForLocation will have the following behaviour: c:\ws\Fred -> null c:\ws\Fred\abc.txt -> null d:\elsewhere -> null c:\ws\Foo -> null c:\ws\Foo\abc.txt -> IFile with path /Foo/abc.txt
Released clarified API javadoc
