United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-6179468 : (spec) File.toURL should be @deprecated

Details
Type:
Bug
Submit Date:
2004-10-14
Status:
Closed
Updated Date:
2012-01-11
Project Name:
JDK
Resolved Date:
2005-06-02
Component:
core-libs
OS:
linux
Sub-Component:
java.io
CPU:
x86
Priority:
P3
Resolution:
Fixed
Affected Versions:
5.0
Fixed Versions:

Related Reports
Relates:
Relates:
Relates:
Relates:
Relates:
Relates:
Relates:
Relates:
Relates:

Sub Tasks

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
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
                                     
2004-10-14
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
                                     
2005-02-25



Hardware and Software, Engineered to Work Together