How URLs are write once?

Question

I was going through java.net package and read this:

URLs are "write-once" objects. Once you've created a URL object, you cannot change any of its attributes (protocol, host name, filename, or port number).

But, if we look into the java.net.URL we will find this:

protected void set(String protocol, String host,
                       int port, String file, String ref)

and

protected void set(String protocol, String host, int port,
                       String authority, String userInfo, String path,
                       String query, String ref)

So, I know these are protected methods but these can be accessed via

public static void setURLStreamHandlerFactory(URLStreamHandlerFactory fac)

So, my question is, if that statement I quoted on top is vague or I just misunderstood it?

Answer 1

URLs are "write-once" objects by you (who are just using URL objects). You can't modify them.

URLs have to be created and initialized internally, sometime, so someone has to modify them. Optimally this would have to be done in its constructor, but that would lose flexibility. URLs can point to a variaty of objects and the implementation to access and handle them is not restricted to the standard library, you can write implementations to handle custom protocols.

Btw, in Java 8 they are not protected, but package private which is even more restrictive (but not that it really matters since URL class is declared final anyway so you cannot subclass it).

Edit: Example

The URL class has many constructors: some allows you to specify different parts of the URL like protocol, host, port etc., and there are some which allows you to specify the URL as one String: spec.

In the latter case (if URL is specified as one String), the different parts of the URL (protocol, host, port etc.) has to be parsed from the String. This parsing is done by a URLStreamHandler which when done parsing the String in the implementation of the URLStreamHandler.parseURL() method have to use the URL.set() method to set the different parts "back" to the URL class because the fields holding these parts are private and there are no setter methods for them.

Since the parsing is done in another class (URLStreamHandler), URL provides a non-public method to receive the parsing result. This provides flexibility as you can replace/extend the URLStreamHandler but still allows URL to be declared final and be "write-once".

Answer 2

Quoting from the official documentation (net/URL.html) for the "set" methods

Sets the fields of the URL. This is not a public method so that only URLStreamHandlers can modify URL fields. URLs are otherwise constant.

The "otherwise" makes me think that only the 2 "set" methods can modify an URL object, and you cannot modify it using any other operation other than a "set" method. They are an exception ;)