Eclipse/UNC Paths

From Eclipsepedia

Jump to: navigation, search

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.


Programming with UNC paths


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

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


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

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. For example:

  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.


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