Package dev.enola.common.io.iri

Class URL

java.lang.Object
dev.enola.common.io.iri.URL
All Implemented Interfaces:
Comparable<URL>
public final class URL extends Object implements Comparable<URL>
URL is WHATWG URL Living Standard inspired implementation. That standard is the de-facto successor of RFC 3987 & RFC 3986, which were the successors that obsoleted the original RFCs 2396 (with more minor RFC RF 2732 in between them).

This class is intentionally named the same as URL, because that class anyway should never ever be used anymore in modern Java (because its equals() and hashCode() methods use blocking outgoing internet connections).

This class strictly speaking represents an URL Reference, not just an URL; meaning that it can either an absolute with a scheme:, or relative.

This class is logically (but not technically, for efficiency) immutable. It has a URL.Builder to programmatically configure instances of it. You can also just construct it from a String with parseUnencoded(String). To modify, use newBuilder(), set what you need, and URL.Builder.build() it.

This class never throws any runtime exceptions for supposedly "invalid" input. It allows e.g. "http://example.org/~{username}" (e.g. URI Templates à la RFC 6570, or other similar syntaxes) or (Glob-like) "**.{txt,json,yaml}" or "?.txt" or "[a-c].txt", etc. It may however not always parse a String input as you intended... ;-) Jokes apart, if you must validate, you can - with validate(); this may throw an an exception. (The toURI() method is the only other one which throws - naturally.)

This class leaves parsing (decoding) its authority() to host/IPv4 & IPv6/port, and IDNA for host, up to others. E.g. Guava's HostAndPort and InternetDomainName and InetAddresses may be useful; they are used by validate().

This class never ever by itself changes an URL you construct based on a String input.

This class can normalize()! But equals(Object) does *NOT* normalize! (This makes it suitable for use in RDF-like applications; see e.g. Wikipedia for background reading.) You can use equalsNormalized(URL), if you must.

This class does not yet directly support Windows Drive Letter scheme; you're welcome to add support for that, if you need it.

TODO TBC How does this class deal with escaping? AVOID URI's getRawXYZ() methods!

This class accepts International Domain Names (IDN) in the host part of an authority, but it does not yet have RFC 3490 Puny Code conversion support; as in, it cannot (itself) transform e.g. "https://☃.net" (a Snowman!) to "https://xn--n3h.net/" in normalize(); you're welcome to add support for that, if you need it.

This class if null-safe. Its accessor methods never return null, but empty Strings instead.

This class never makes any network access! (Yes, looking at you, URL.equals(Object) - OMG!)

This class does not know about any specific schemes, and doesn't treat e.g. http: different from any other scheme. There are no hard-coded default ports or anything like that here. (TODO except to normalize() e.g. ports, maybe?) TODO Re-read and re-think about if this really makes sense, and is Spec compliant? This may not really work?

This class is performance efficient, and parses lazily, not (possibly unnecessarily) ahead of time.

This class is memory efficient, and uses as little Java heap space as possible.

This class is intentionally final and not extensible.

This class has no dependencies on any other framework, and could be single-file copy/pasted! TODO For realz?! ;-) Or do depend on (just) Guava? It's handy e.g. for Multimap...