Package com.mastfrog.url

Class URL

java.lang.Object
com.mastfrog.url.URL
All Implemented Interfaces:
URLComponent, Serializable, Comparable<URL>, org.netbeans.validation.api.Validating
public final class URL extends Object implements URLComponent, org.netbeans.validation.api.Validating, Comparable<URL>
Represents an internet URL. Unlike java.net.URL, invalid URLs can be constructed (see isValid() and getInvalidComponent() for validation).

Also, unlike java.net.URL, the equals() and hashCode() methods of this class will not attempt to make network connections. This class does attempt basic normalization of URLs - a URL representing http://FOO.com/bar.html? is equal to a URL representing http://foo.com/bar.html.

To create instances, use either URL.parse() or URLBuilder.

Author:
Tim Boudreau
See Also:

  • Method Details

    • withProtocol

      public URL withProtocol(Protocol protocol)

    • builder

      public static URLBuilder builder()

    • builder

      public static URLBuilder builder(Protocol protocol)

    • builder

      public static URLBuilder builder(URL startWith)

    • parse

      public static URL parse(String url)
      Parse a URL from a string. Note that this method will not throw any exception if the URL is invalid. Call isValid() on the result if you are parsing a URL you did not construct yourself. getInvalidComponent().getName() will indicate exactly what part is invalid.

      It is not guaranteed that all parts of the passed-in string will be preserved in the returned URL if it is invalid.

      Parameters:
      url - A URL string
      Returns:
      A URL

    • getBaseURL

      public URL getBaseURL(boolean retainPort)
      Get this URL in its typical browser-based form, omitting any query strings and username/password. I.e., if you have a URL for http://username:password@foo.com/something?bar=baz#x, you get back http://foo.com/something.
      Returns:

    • getAnchor

      public Anchor getAnchor()
      Get the anchor, if any, of this URL, as in http://foo.com/index.html#anchor
      Returns:
      An anchor or null

    • getHost

      public Host getHost()
      Get the host portion, if any, of this URL, as in http://foo.com/index.html
      Returns:
      A host or null

    • getPath

      public Path getPath()
      Get the path, if any, of this URL, as in http://foo.com:332/stuff/index.html?foo=bar;bar=baz;#anchor
      Returns:
      An anchor or null

    • getPort

      public Port getPort()
      Get the port, if any, of this URL. The port returned will either be the explicit port in this URL, as in http://foo.com:332/stuff/index.html or the default port from the protocol, if any.
      Returns:
      A port or null

    • getProtocol

      public Protocol getProtocol()
      Get the protocol, if any, of this URL, as in http://foo.com/stuff/index.html. If the protocol is null, the URL is invalid.
      Returns:
      A protocol, or null.

    • getParameters

      public Parameters getParameters()
      Get the parameters of this query, if any, as in http://foo.com/stuff/index.html?foo=bar;bar=baz&baz=boo#anchor
      Returns:
      The parameters or null if empty or unspecified

    • getUserName

      public URLComponent getUserName()
      Get the user-name portion of this URL, as in http://tim:password@foo.com/stuff/index.html
      Returns:
      The user name if specified, otherwise null

    • getPassword

      public URLComponent getPassword()
      Get the user-name portion of this URL, as in http://tim:password@foo.com/stuff/index.html
      Returns:
      The user name if specified, otherwise null

    • isKnownProtocol

      public boolean isKnownProtocol()
      Returns true if this protocol of this URL is a well-known protocol.
      Returns:
      Whether or not the protocol is a supported one, such as http, https, ftp, file

    • isProbableFileReference

      public boolean isProbableFileReference()
      Determine if this URL is inferred to refer to a file, not a folder. If false, the path portion will include a trailing / character.
      Returns:
      whether or not this is a file reference

    • isSameDomain

      public boolean isSameDomain(String domain)
      Determine if the domain is the same as the passed internet domain. For example, "foo.com" and "www.foo.com" have the same domain.
      Parameters:
      domain -
      Returns:
      True if the domain matches

    • getHostAndPort

      public HostAndPort getHostAndPort()
      Get an aggregate of the host and port.
      Returns:
      A host and port

    • appendTo

      public void appendTo(StringBuilder sb)
      Append this URL to a StringBuilder, in normalized form.
      Specified by:
      appendTo in interface URLComponent
      Parameters:
      sb - A StringBuilder to append to

    • getPathAndQuery

      public String getPathAndQuery()

    • isSecure

      public boolean isSecure()
      Returns true if the protocol is non-null, is a known protocol, and the protocol is known to use SSL.
      Returns:
      True if this is a secure URL.

    • components

      public URLComponent[] components()
      Get the components of this URL.
      Returns:
      The components

    • allComponents

      public URLComponent[] allComponents()
      Get all components of this URL, drilling into nested components and not including their parents where necessary (as in Host, Path and Parameters).
      Returns:
      An array of all low-level components of this URL.

    • getInvalidComponent

      public URLComponent getInvalidComponent()
      Get the first URLComponent which is not valid, if isValid() == false.
      Returns:
      The invalid component, or null

    • isValid

      public boolean isValid()
      Determine if this URL is a legal URL according to the relevant RFCs. Does not determine if this URL is reachable via a network, only that its syntax is correct.
      Specified by:
      isValid in interface URLComponent
      Specified by:
      isValid in interface org.netbeans.validation.api.Validating
      Returns:
      true if this URL is probably valid.

    • getComponentName

      public String getComponentName()
      Description copied from interface: URLComponent
      Get a human-readable, localized name for this part of the URL. Useful if an error message needs to be shown.
      Specified by:
      getComponentName in interface URLComponent
      Returns:
      The component name

    • toString

      public String toString()
      Get this URL in normalized form as a string.
      Overrides:
      toString in class Object
      Returns:
      This URL as a string.

    • toUnescapedForm

      public String toUnescapedForm()

    • stripAnchor

      public URL stripAnchor()
      Create a version of this URL minus its anchor.
      Returns:
      A version of this URL minus everything following the last # character.

    • stripQuery

      public URL stripQuery()
      Create a version of this URL minus its parameters.
      Returns:
      A version of this URL minus everything following the last ? character.

    • toSimpleURL

      public URL toSimpleURL()
      Creates a version of this URL minus its username, password, query and anchor.
      Returns:
      A URL with the same protocol, host, port and path as this one.

    • toURI

      public URI toURI() throws URISyntaxException
      Throws:
      URISyntaxException

    • withParameter

      public URL withParameter(String name, String value)

    • simpleEquals

      public boolean simpleEquals(URL other)
      Determine if this URL points to the same file on the same host, ignoring username/password, anchor and parameters.
      Parameters:
      other - Another URL
      Returns:
      true if the other URL points to the same file via the same protocol

    • getParentURL

      public URL getParentURL()
      Get a URL to the parent path of this URL, stripping out any parameters or anchor.
      Returns:
      A parent URL to this one, if the path is deeper than one element. Returns a path to the host with no path if the path is exactly one element deep.

    • fromFile

      public static URL fromFile(File file)
      Get a URL for a file on disk in file protocol.
      Parameters:
      file - A file
      Returns:
      A URL

    • fromJavaUrl

      public static URL fromJavaUrl(URL url)
      Convert a java.net.URL to URL.
      Parameters:
      url - A Java URL
      Returns:
      A URL

    • equals

      public boolean equals(Object obj)
      Determine if the passed object is a URL and is an exact match for this URL. Note that sometimes simpleEquals(URL) may be preferable, as it will match URLs which point to the same document but may specify a different user, password, parameters or anchor.
      Overrides:
      equals in class Object
      Parameters:
      obj - An object
      Returns:
      Whether or not the object argument is equal to this object.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • getURLEncoding

      public static Charset getURLEncoding()

    • toJavaURL

      public URL toJavaURL() throws MalformedURLException
      Throws:
      MalformedURLException

    • getProblems

      public org.netbeans.validation.api.Problems getProblems()
      Specified by:
      getProblems in interface org.netbeans.validation.api.Validating

    • compareTo

      public int compareTo(URL o)
      Specified by:
      compareTo in interface Comparable<URL>