> The recommended way to manage the encoding and decoding of URLs is to use URI, and to convert between these two classes using toURI() and URI.toURL().
and at that point you might as well just use URI. The resource resolution functionality is basically the only thing URL offers over URI.
They quietly mention at the bottom that they recommend using URI.
I don't think it's unreasonable to ask that an API be deprecated when core functionality, like comparing the thing, is broken. The stdlib docs should provide best practices to new developers and clearly mark old, broken APIs as deprecated.
Same with Date[1]; you have to make a defensive copy every time you accept or return it or you risk your internal state being changed. You're not going to pick this up from the docs unless you have a. learned about the problems with mutability, and b. carefully scrutinize the docs and notice, oh, hey there are all these setter methods.
What's nuts is the APIs in Date that they did deprecate aren't even broken, they're just not very general! It's the Date object itself that is hilariously dangerous to use.
Actually, some of the deprecated methods on Date are broken. If you have a Date representing the wrong date and invoke the wrong sequence of deprecated methods, you can end up with Exceptions. Admittedly, the only such bug I'm aware of affects only dates before October 15th, 1582.
To be fair, more modern languages have the same problem. For instance, Go's "syscall" package is considered to be a bad idea to use (and people are pushed to use "golang.org/x/sys/unix" instead).
Just avoid it entirely.