View source for 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:

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

# Find out the host name of your machine (from a dos prompt execute "hostname")
# In File Explorer enter in your UNC path \\<hostname>\<share folder name>
# 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.

* [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwords&short_desc=unc&classification=Eclipse&classification=RT&product=Equinox&product=JDT&product=PDE&product=Platform&chfieldfrom=2009-01-20&chfieldto=Now&chfield=%5BBug+creation%5D&chfieldvalue=&cmdtype=doit Bugzilla query]: Bugs with word "unc" in the summary, filed after 20-Jan-2009

== Test Scenarios ==

# Installation and Upgrade
## Launch eclipse and point it to the UNC path for a workspace location.  Then you can test the self-hosting scenario from comment 1.
## Extract an eclipse build to the UNC path and then launch it using the UNC path to ensure eclipse can launch.
## 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.
## Special Cases
### Use one of the implicit predefined UNC Paths, e.g. "'''\\127.0.0.1\C$'''" == C:\
### 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<br/>'''<font color="red">Note:</font> Characters :%#<>" are invalid''' for Java already as per {{bug|3109}} and the Eclipse README
# Usage
## Workspace portability: Access the physically same workspace with -data D:\ws or -data //myhost/ws
## Create Linked Resources pointing to UNC paths.
## Import Projects from UNC paths (with or without "Copy to Worksace").
## Export / Import or use external files from UNC: Preferences, SSH keys, .keyring, .secure_ring, -configuration, ...
## '''Component Owners: especially tests scenarios where you know that URL or URI is used for local files!'''
# Windows X Unix interoperability (advanced, gives extra credits :-)
## 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)
## On Windows: create workspace on //mylinuxhost/myshare/ws . Import project from //mylinuxhost/myshare/proj1 . Create linked resources to UNC outside or inside WS.
## Open the workspace on Linux, is everything there?
## 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:
<source lang="java">
 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();
</source>

== 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:
<source lang="java">
  new File("//SERVER/some/path").toURI().toString() -> "file:////SERVER/some/path
</source>
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.

In general, you should use the convenience methods on <code>org.eclipse.core.runtime.URIUtil</code> 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 [http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4723726 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 <code>org.eclipse.core.runtime.URIUtil</code>. This is Sun [http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=5086147 bug 5086147].

= Resources =
* [https://bugs.eclipse.org/207103 bug 207103] - Eclipse project 3.4/3.5 release bug discussing UNC path support
* [http://blogs.msdn.com/ie/archive/2006/12/06/file-uris-in-windows.aspx File URIs in Windows] - Microsoft reference on working with UNC paths