Eclipse/UNC Paths

This page documents issues in the Eclipse project related to Universal Naming Convention (UNC) paths. This page describes how to setup an environment for testing UNC paths, and some tips on how to handle UNC paths in your code.

Setting up for UNC path testing

For testing purposes you can setup your machine to have a "local" UNC path. Here is how to set this up on Windows XP:

1. From File Explorer select a folder you would like to use as your UNC path. Right-Click this folder and bring up the Properties dialog.
2. Select the "Sharing" tab and then select the "Share this folder" option. Note that you can change the name under which you share this folder
3. If you are going to test the ability to write to the UNC path then you must also click the "Permissions" button on the "Sharing" tab.
4. For "Group or user names" there should be the user "Everyone". If not then click "Add..." and enter the name "Everyone" (you can click the "Check Names" to ensure the user exists on your system). Then click OK.
5. For the Everyone user check the "Full Control" permission under the "Allow" column. Click OK until the folder properties dialog exits.

To test your local UNC path do the following:

1. Find out the host name of your machine (from a dos prompt execute "hostname")
2. In File Explorer enter in your UNC path \\<hostname>\<share folder name>
3. This should allow you to browse to the shared location. Ensure you can modify the folder if you set it up to be fully controlled by Everyone.

Now you should be able to use this UNC path locally to test Eclipse.

Known Issues

Look at the bugzilla query below to see what issues related to UNC paths have been detected in the Eclipse Platform recently, such that you can avoid running into the same issues again.

• Bugzilla: All recent bugs with word "UNC" in the summary, filed after 20-Jan-2009, including resolved ones
• Bugzilla: All Open with word "UNC" in the summary

Test Scenarios

1. Installation and Upgrade
   1. Launch eclipse and point it to the UNC path for a workspace location. Then you can test the self-hosting scenario from comment 1.
   2. Extract an eclipse build to the UNC path and then launch it using the UNC path to ensure eclipse can launch.
   3. Attempt to do a build to build upgrade of Eclipse while launched from the UNC path to ensure p2 can provision to a UNC path.
   4. Special Cases
      1. Use one of the implicit predefined UNC Paths, e.g. "\\127.0.0.1\C$" == C:\
      2. Use special characters in the UNC Path which need URI quoting e.g. Share As : "My @! Folder" and install in there / use workspace in there
         Note: Characters :%#<>" are invalid for Java already as per bug 3109 and the Eclipse README
2. Usage
   1. Workspace portability: Access the physically same workspace with -data D:\ws or -data //myhost/ws
   2. Create Linked Resources pointing to UNC paths.
   3. Import Projects from UNC paths (with or without "Copy to Worksace").
   4. Export / Import or use external files from UNC: Preferences, SSH keys, .keyring, .secure_ring, -configuration, ...
   5. Component Owners: especially tests scenarios where you know that URL or URI is used for local files!
3. Windows X Unix interoperability (advanced, gives extra credits :-)
   1. Use Samba to export some Linux folder as an SMB share (//mylinuxhost/myshare) and create a symlink to it in the local FS (/mylinuxhost/myshare)
   2. On Windows: create workspace on //mylinuxhost/myshare/ws . Import project from //mylinuxhost/myshare/proj1 . Create linked resources to UNC outside or inside WS.
   3. Open the workspace on Linux, is everything there?
   4. Modify project with linked resources on Linux, after re-opening on Windows does it still work as expected?

Programming with UNC paths

IPath

IPath supports UNC paths naturally. The "UNC-ness" of the path is stored in a separate field so that arbitrary path manipulations will not affect the path's interpretation as a UNC path

java.net.URL

java.net.URL does not handle UNC paths well. To construct a URL representing a local UNC path, you must do the following:

 String spec = ...;//String representation of a URL
 if (spec.startsWith("file:"))
    // need to do this for UNC paths
    return new File(spec.substring(5)).toURL();

In general, org.eclipse.core.runtime.URIUtil.fromString(), URIUtil.toURI() and URIUtil.toURL() should be used.

conversion URL <-> File

File aFile = URIUtil.toFile(URIUtil.toURI(aURL));
URL bURL = URIUtil.toURL(bFile.toURI());
URL cURL = URIUtil.toURL(URIUtil.fromString(cString));

See for example bug 289322 and bug 311789

java.net.URI

The URI class handles UNC paths reasonably well, but has some problems. In the Java class libraries, the string representation of a UNC path is as follows:

  new File("//SERVER/some/path").toURI().toString() -> "file:////SERVER/some/path

In other words, the URI stores the entire UNC path in the path component of the URI, and leaves the server/authority component empty. As long as you consistently use this string representation you will be able to interact successfully with java.net.URI -- therefore this is also the representation recommended for use throughout the Eclipse SDK and used by the org.eclipse.core.runtime.URIUtil class.

In general, you should use the convenience methods on org.eclipse.core.runtime.URIUtil when manipulating the path portion of URIs to ensure UNC paths are correctly preserved.

normalize

The method java.net.URI#normalize alters the representation of a URI by collapsing empty segments. This "destroys" UNC paths by converting them to standard file system paths. This method should be avoided when dealing with any URI that may contain a UNC path. For more details see Sun bug 4723726.

conversion through URL

Converting a URI to URL and back to URI again also destroys UNC paths by removing leading slashes. This bug exists in Java 5, but has been fixed in Java 6. The workaround is to use the URL<->URI conversion methods on org.eclipse.core.runtime.URIUtil. This is Sun bug 5086147.

Resources

• bug 207103 - Eclipse project 3.4/3.5 release bug discussing UNC path support
• File URIs in Windows - Microsoft reference on working with UNC paths

• bug 3109 -- Very old bug with a useful comment by Markus Keller @ 2013-01-03 06:00:54 PST discussing this.
• bug 339422 -- URIUtil is not actually fully a good idea. See this bug for details.