(add links to two relevant bugs, as a first stab at updating this page)

(12 intermediate revisions by 2 users not shown)

Line 1:

Line 1:

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.

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")

# 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: [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 All recent] bugs with word "UNC" in the summary, filed after 20-Jan-2009, including resolved ones

+

* Bugzilla: [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwords&short_desc=unc&classification=Eclipse&classification=RT&product=Equinox&product=Platform&product=JDT&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&product=PDE All Open] with word "UNC" in the summary

+

+

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

## Modify project with linked resources on Linux, after re-opening on Windows does it still work as expected?

= Programming with UNC paths =

= Programming with UNC paths =

Line 13:

Line 58:

return new File(spec.substring(5)).toURL();

return new File(spec.substring(5)).toURL();

</source>

</source>

+

+

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

+

+

=== conversion URL &lt;-&gt; File ===

+

<source lang="java">

+

File aFile = URIUtil.toFile(URIUtil.toURI(aURL));

+

URL bURL = URIUtil.toURL(bFile.toURI());

+

URL cURL = URIUtil.toURL(URIUtil.fromString(cString));

+

</source>

+

See for example {{bug|289322}} and {{bug|311789}}

== java.net.URI ==

== java.net.URI ==

Line 21:

Line 76:

</source>

</source>

In other words, the URI stores the entire UNC path in the path component of the URI, and leaves

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.

+

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 <code>org.eclipse.core.runtime.URIUtil</code> class.

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.

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.

Line 33:

Line 88:

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

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

# 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")

[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

+

Latest revision as of 18:04, 19 April 2013

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")

Test Scenarios

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 thereNote: 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

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.