A URI is a uniform resource identifier while a URL is a uniform resource locator. Hence every URL is a URI, abstractly speaking, but not every URI is a URL. This is because there is another subcategory of URIs, uniform resource names (URNs), which name resources but do not specify how to locate them. The mailto, news, and isbn URIs … are examples of URNs.

The conceptual distinction between URIs and URLs is reflected in the differences between this class and the URL class.

An instance of this class represents a URI reference in the syntactic sense defined by RFC 2396. A URI may be either absolute or relative. A URI string is parsed according to the generic syntax without regard to the scheme, if any, that it specifies. No lookup of the host, if any, is performed, and no scheme-dependent stream handler is constructed. Equality, hashing, and comparison are defined strictly in terms of the character content of the instance. In other words, a URI instance is little more than a structured string that supports the syntactic, scheme-independent operations of comparison, normalization, resolution, and relativization.

An instance of the URL class, by contrast, represents the syntactic components of a URL together with some of the information required to access the resource that it describes. A URL must be absolute, that is, it must always specify a scheme. A URL string is parsed according to its scheme. A stream handler is always established for a URL, and in fact it is impossible to create a URL instance for a scheme for which no handler is available. Equality and hashing depend upon both the scheme and the Internet address of the host, if any; comparison is not defined. In other words, a URL is a structured string that supports the syntactic operation of resolution as well as the network I/O operations of looking up the host and opening a connection to the specified resource.

Consequences

What does all of this mean? It means that when the ADF schema calls something a URL, it is probably lying, because the editor generally accepts URNs for these values, too. That means that these are not URLs; they are URIs. It is hard to come up with a good way to reconcile all of that confusion in this library without doing something that looks strange in Java or risks breaking compatibility with the ADF editor code. For that reason, this library takes the following relatively lax attitude towards these values:

The builders accept any of String, URL, or URI arguments for these values.
The builders verify that String and URL arguments form valid URIs and throw an exception if they cannot be parsed.
The library holds them as String values internally, regardless of how they are supplied.
The parser and renderer do not validate these values, so otherwise invalid URIs will survive a round trip through the library, even though you can’t supply such values yourself.
Accessors like url() and operations like fold(ifUrl, ifData) use the raw String.

So if you were expecting url() to return a URL, well, now you know why it doesn’t.

This same general pattern of using the string representation of values while allowing them to also be specified using more concrete representations has been used for several other data types as well. For example, the date node can accept its value as an Instant, Date, long (representing millis since 1970-01-01 00:00:00 UTC), or just as a String.