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