Eclipse/UNC Paths

From Eclipsepedia

Jump to: navigation, search



Setting up for UNC path testing



To test your local UNC path do the following:



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
    4. Special Cases
      1. Use one of the implicit predefined UNC Paths, e.g. "\\\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 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:

 if (spec.startsWith("file:"))
    // need to do this for UNC paths

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



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



conversion through URL



  • 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.