Bug ID: JDK-6179468 (spec) File.toURL should be @deprecated

JDK-6179468 : (spec) File.toURL should be @deprecated

Type: Bug
Component: core-libs
Sub-Component: java.io
Affected Version: 5.0

Priority: P3
Status: Closed
Resolution: Fixed
OS: linux
CPU: x86

Submitted: 2004-10-14
Updated: 2017-05-16
Resolved: 2005-06-02

Versions (Unresolved/Resolved/Fixed)

The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.

JDK 6
6 b39Fixed

Related Reports

Relates :	JDK-4273532 - toURL() method in File class needs to escape excluded URL characters
Relates :	JDK-6243829 - Use of File.toURL in sun/jvmstat/perfdata/monitor/PerfDataBufferImpl.java
Relates :	JDK-6243824 - Use of File.toURL in com/sun/org/apache/xalan/internal/xsltc - toURL known to return invalid URLs
Relates :	JDK-6243835 - Use of File.toURL in plugin and webstart - toURL known to return invalid URLs
Relates :	JDK-6243843 - Use of File.toURL in plugin - toURL known to return invalid URLs
Relates :	JDK-6243826 - Use of File.toURL in com/sun/security/auth/PolicyFile.java - toURL known to return invalid URLs
Relates :	JDK-6243831 - Use of File.toURL in sun/tools/jstat/Arguments.java - toURL known to return invalid URLs
Relates :	JDK-6243837 - Use of File.toURL in javawebstart - toURL known to return invalid URLs
Relates :	JDK-6243815 - Use of File.toURL in com/sun/java/swing/plaf/gtk/Metacity.java - toURL known to return invalid URLs

Description

As of JDK 1.4, java.io.File.toURL is effectively deprecated. It is known to not handle special characters correctly, e.g. "/tmp/a#b" becomes "file:/tmp/a#b" which is incorrect (the '#' should have been escaped); some filenames can even produce illegal URLs. The maintainers of this class decided not to change its implementation to be correct (supposedly for "compatibility", which I will not comment on further), but the current Javadoc says

"Usage note: This method does not automatically escape characters that are illegal in URLs. It is recommended that new code convert an abstract pathname into a URL by first converting it into a URI, via the toURI method, and then converting the URI into a URL via the URI.toURL method."

Fine; this does in fact work (except for Windows UNC paths, reported separately), and achieve what File.toURL was supposed to achieve to begin with. So why is File.toURL not @deprecated? The above message is precisely what @deprecated is for, according to the Javadoc manual:

"Adds a comment indicating that this API should no longer be used (even though it may continue to work)."

New code should not use File.toURL for the documented reasons, though it continues to mostly work (i.e. as much as it ever did).

Why is this issue important? Because most developers do not read the Javadoc of every single method they call, especially if they have been calling it for a while, and are not aware of the problems with File.toURL, whereas a deprecation message is made visible to them by the compiler. For example: in developing the NetBeans IDE, we often use URLs to persist file names (for interoperability with JAR entries etc.). The aforementioned bugs in File.toURL do affect this usage sometimes, e.g. if the IDE's users have a ClearCase installation, which uses '#' in directory names (I think). To be safe, we have to use file.toURI() (perhaps followed by URI.toURL(), according to the situation). However many developers do not know this and inadvertently use File.toURL since it is more visible (and has been around longer); and the compiler does not give any hint that this is not advisable.

Note that I was inspired to enter this issue based on feedback from a developer not working on NetBeans who had had the same experience:

http://www.netbeans.org/servlets/ReadMsg?msgId=743795&listName=nbdev
###@###.### 10/14/04 21:34 GMT

Comments

EVALUATION This method is not very useful as it stands. In past releases we've tried to "fix" this method and have had to revert because many things were depending on the current behaviour. Requesets for deprecation is rare and approval tends to be difficult to get. However, because use of this method is potentially harmful when the returned URL is invalid, I believe that we should attempt to get this method deprecated. ###@###.### 2005-2-25 22:15:09 GMT

25-02-2005

SUGGESTED FIX Put the entire "Usage note" from the Javadoc into a @deprecation tag. ###@###.### 10/14/04 21:34 GMT *************** *** 573,579 **** * the file denoted by this abstract pathname is a directory, then the * resulting URL will end with a slash. * ! * <p> <b>Usage note:</b> This method does not automatically escape * characters that are illegal in URLs. It is recommended that new code * convert an abstract pathname into a URL by first converting it into a * URI, via the {@link #toURI() toURI} method, and then converting the URI --- 580,586 ---- * the file denoted by this abstract pathname is a directory, then the * resulting URL will end with a slash. * ! * @deprecated This method does not automatically escape * characters that are illegal in URLs. It is recommended that new code * convert an abstract pathname into a URL by first converting it into a * URI, via the {@link #toURI() toURI} method, and then converting the URI *************** *** 590,595 **** --- 597,603 ---- * @see java.net.URL * @since 1.2 */ + @Deprecated public URL toURL() throws MalformedURLException { return new URL("file", "", slashify(getAbsolutePath(), isDirectory())); } ###@###.### 2005-2-25 22:15:09 GMT

14-10-2004