Class Url

java.lang.Object
org.refcodes.web.Url
All Implemented Interfaces:
CredentialsAccessor, IdentityAccessor, PathAccessor<String>, PortAccessor, SecretAccessor, IpAddressAccessor, FragmentAccessor, HostAccessor, QueryFieldsAccessor, SchemeAccessor
Direct Known Subclasses:
UrlBuilder
public class Url extends Object implements SchemeAccessor, HostAccessor, IpAddressAccessor, PortAccessor, PathAccessor<String>, QueryFieldsAccessor, FragmentAccessor, CredentialsAccessor

The Url class represents an immutable URL: An URL looks something like this:

"scheme://[identity[:secret]@]host[:port][/path][?query][#fragment] In contrast to the java.net URL, this URL also supports "relative" locators with neither a scheme nor a host declaration. If the relative locator starts with a "/" slash, then we assume not having a host being provided: "/path?query#fragment" When it does *not* start with a "/" slash, then we assume that the first element being the host: "[identity[:secret]@]host[:port]/path[?query][#fragment]"

  • Field Details

    • _scheme

      protected Scheme _scheme

    • _protocol

      protected String _protocol

    • _host

      protected String _host

    • _ipAddress

      protected int[] _ipAddress

    • _path

      protected String _path

    • _port

      protected int _port

    • _queryFields

      protected FormFields _queryFields

    • _identity

      protected String _identity

    • _secret

      protected String _secret

    • _fragment

      protected String _fragment

  • Constructor Details

    • Url

      protected Url()
      Default constructor. Make sure to set required attributes for a valid URL.

    • Url

      public Url(Url aUrl)
      Creates an Url from the provided Url.
      Parameters:
      aUrl - The Url from which to construct this instance.

    • Url

      public Url(String aUrl) throws MalformedURLException
      Constructs an Url from the provided URL String.
      Parameters:
      aUrl - The URL String to be parsed. The URL consists of the scheme (protocol), the identify and the secret (optional), the host as well as an optional port and the (optional) path.
      Throws:
      MalformedURLException - in case the provided URL is considered being malformed.

    • Url

      public Url(String aUrl, FormFields aQueryFields) throws MalformedURLException
      Constructs an Url from the provided URL String.
      Parameters:
      aUrl - The URL String to be parsed. The URL consists of the scheme (protocol), the identify and the secret (optional), the host as well as an optional port and the (optional) path.
      aQueryFields - The Query-Fields to be used for the HTTP Query-String.
      Throws:
      MalformedURLException - in case the provided URL is considered being malformed.

    • Url

      public Url(String aUrl, FormFields aQueryFields, String aFragment) throws MalformedURLException
      Constructs an Url from the provided URL String.
      Parameters:
      aUrl - The URL String to be parsed. The URL consists of the scheme (protocol), the identify and the secret (optional), the host as well as an optional port and the (optional) path.
      aQueryFields - The Query-Fields to be used for the HTTP Query-String.
      aFragment - The fragment to be set.
      Throws:
      MalformedURLException - in case the provided URL is considered being malformed.

    • Url

      public Url(URL aURL)
      Constructs an Url from the provided URL instance.
      Parameters:
      aURL - The URL to be used.

    • Url

      public Url(Scheme aScheme, String aHost)
      Constructs an Url with the common attributes.
      Parameters:
      aScheme - The Scheme (e.g. HTTP or HTTPS) to be used for the destination URL.
      aHost - The host to which the destination URL is to point to.

    • Url

      public Url(Scheme aScheme, String aHost, int aPort)
      Constructs an Url with the common attributes.
      Parameters:
      aScheme - The Scheme (e.g. HTTP or HTTPS) to be used for the destination URL.
      aHost - The host to which the destination URL is to point to.
      aPort - The port to be used when connecting to the host.

    • Url

      public Url(Scheme aScheme, String aHost, int aPort, String aPath)
      Constructs an Url with the common attributes.
      Parameters:
      aScheme - The Scheme (e.g. HTTP or HTTPS) to be used for the destination URL.
      aHost - The host to which the destination URL is to point to.
      aPort - The port to be used when connecting to the host.
      aPath - The path on the host to which the base destination URL is to point to.

    • Url

      public Url(Scheme aScheme, String aHost, int aPort, String aPath, FormFields aQueryFields)
      Constructs an Url with the common attributes.
      Parameters:
      aScheme - The Scheme (e.g. HTTP or HTTPS) to be used for the destination URL.
      aHost - The host to which the destination URL is to point to.
      aPort - The port to be used when connecting to the host.
      aPath - The path on the host to which the base destination URL is to point to.
      aQueryFields - The Query-Fields to be used for the HTTP Query-String.

    • Url

      public Url(Scheme aScheme, String aHost, int aPort, String aPath, FormFields aQueryFields, String aFragment)
      Constructs an Url with the common attributes.
      Parameters:
      aScheme - The Scheme (e.g. HTTP or HTTPS) to be used for the destination URL.
      aHost - The host to which the destination URL is to point to.
      aPort - The port to be used when connecting to the host.
      aPath - The path on the host to which the base destination URL is to point to.
      aQueryFields - The Query-Fields to be used for the HTTP Query-String.
      aFragment - The fragment to be set.

    • Url

      public Url(String aProtocol, String aHost)
      Constructs an Url with the common attributes.
      Parameters:
      aProtocol - The protocol String (e.g. "http://" or "https://") to be used for the destination URL.
      aHost - The host to which the destination URL is to point to.

    • Url

      public Url(String aProtocol, String aHost, int aPort)
      Constructs an Url with the common attributes.
      Parameters:
      aProtocol - The protocol String (e.g. "http://" or "https://") to be used for the destination URL.
      aHost - The host to which the destination URL is to point to.
      aPort - The port to be used when connecting to the host.

    • Url

      public Url(String aProtocol, String aHost, int aPort, String aPath)
      Constructs an Url with the common attributes.
      Parameters:
      aProtocol - The protocol String (e.g. "http://" or "https://") to be used for the destination URL.
      aHost - The host to which the destination URL is to point to.
      aPort - The port to be used when connecting to the host.
      aPath - The path on the host to which the base destination URL is to point to.

    • Url

      public Url(String aProtocol, String aHost, int aPort, String aPath, FormFields aQueryFields)
      Constructs an Url with the common attributes.
      Parameters:
      aProtocol - The protocol String (e.g. "http://" or "https://") to be used for the destination URL.
      aHost - The host to which the destination URL is to point to.
      aPort - The port to be used when connecting to the host.
      aPath - The path on the host to which the base destination URL is to point to.
      aQueryFields - The Query-Fields to be used for the HTTP Query-String.

    • Url

      public Url(String aProtocol, String aHost, int aPort, String aPath, FormFields aQueryFields, String aFragment)
      Constructs an Url with the common attributes.
      Parameters:
      aProtocol - The protocol String (e.g. "http://" or "https://") to be used for the destination URL.
      aHost - The host to which the destination URL is to point to.
      aPort - The port to be used when connecting to the host.
      aPath - The path on the host to which the base destination URL is to point to.
      aQueryFields - The Query-Fields to be used for the HTTP Query-String.
      aFragment - The fragment to be set.

    • Url

      public Url(Scheme aScheme, String aHost, String aPath)
      Constructs an Url with the common attributes.
      Parameters:
      aScheme - The Scheme (e.g. HTTP or HTTPS) to be used for the destination URL.
      aHost - The host to which the destination URL is to point to.
      aPath - The path on the host to which the base destination URL is to point to.

    • Url

      public Url(Scheme aScheme, String aHost, String aPath, FormFields aQueryFields)
      Constructs an Url with the common attributes.
      Parameters:
      aScheme - The Scheme (e.g. HTTP or HTTPS) to be used for the destination URL.
      aHost - The host to which the destination URL is to point to.
      aPath - The path on the host to which the base destination URL is to point to.
      aQueryFields - The Query-Fields to be used for the HTTP Query-String.

    • Url

      public Url(Scheme aScheme, String aHost, String aPath, FormFields aQueryFields, String aFragment)
      Constructs an Url with the common attributes.
      Parameters:
      aScheme - The Scheme (e.g. HTTP or HTTPS) to be used for the destination URL.
      aHost - The host to which the destination URL is to point to.
      aPath - The path on the host to which the base destination URL is to point to.
      aQueryFields - The Query-Fields to be used for the HTTP Query-String.
      aFragment - The fragment to be set.

    • Url

      public Url(String aProtocol, String aHost, String aPath)
      Constructs an Url with the common attributes.
      Parameters:
      aProtocol - The protocol String (e.g. "http://" or "https://") to be used for the destination URL.
      aHost - The host to which the destination URL is to point to.
      aPath - The path on the host to which the base destination URL is to point to.

    • Url

      public Url(String aProtocol, String aHost, String aPath, FormFields aQueryFields)
      Constructs an Url with the common attributes.
      Parameters:
      aProtocol - The protocol String (e.g. "http://" or "https://") to be used for the destination URL.
      aHost - The host to which the destination URL is to point to.
      aPath - The path on the host to which the base destination URL is to point to.
      aQueryFields - The Query-Fields to be used for the HTTP Query-String.

    • Url

      public Url(Url aUrl, Url aOtherUrl)
      Constructs a new Url from the given Url instances by adding the other Url's data to the first Url's data. E.g. a path from the other Url is append to the first Url's path, the query parameters are added or overwritten accordingly and so on.
      Parameters:
      aUrl - The Url which is to be enriched.
      aOtherUrl - The Url enriching the given Url.

    • Url

      public Url(String aProtocol, String aHost, String aPath, FormFields aQueryFields, String aFragment)
      Constructs an Url with the common attributes.
      Parameters:
      aProtocol - The protocol String (e.g. "http://" or "https://") to be used for the destination URL.
      aHost - The host to which the destination URL is to point to.
      aPath - The path on the host to which the base destination URL is to point to.
      aQueryFields - The Query-Fields to be used for the HTTP Query-String.
      aFragment - The fragment to be set.

    • Url

      public Url(Url aUrl, String... aPaths)
      Some Url algebra: Adds the provided path to the given Url by prepending it to the Url's path.
      Parameters:
      aUrl - The Url to which to add the path.
      aPaths - The paths to be added to the given Url.

  • Method Details

    • getFragment

      public String getFragment()
      Retrieves the fragment from the fragment property.
      Specified by:
      getFragment in interface FragmentAccessor
      Returns:
      The fragment stored by the fragment property.

    • getHost

      public String getHost()
      Retrieves the host from the host property.
      Specified by:
      getHost in interface HostAccessor
      Returns:
      The host stored by the host property.

    • getIdentity

      public String getIdentity()
      Specified by:
      getIdentity in interface IdentityAccessor

    • getIpAddress

      public int[] getIpAddress()
      Specified by:
      getIpAddress in interface IpAddressAccessor

    • getPath

      public String getPath()
      Specified by:
      getPath in interface PathAccessor<String>

    • getPort

      public int getPort()
      Specified by:
      getPort in interface PortAccessor

    • getQueryFields

      public FormFields getQueryFields()
      Retrieves the request Query-Fields from the request Query-Fields property.
      Specified by:
      getQueryFields in interface QueryFieldsAccessor
      Returns:
      The request Query-Fields stored by the request Query-Fields property.

    • getScheme

      public Scheme getScheme()
      Retrieves the UrlScheme from the URL scheme.
      Specified by:
      getScheme in interface SchemeAccessor
      Returns:
      The UrlScheme stored by the URL scheme.

    • getSecret

      public String getSecret()
      Specified by:
      getSecret in interface SecretAccessor

    • toProtocol

      public String toProtocol()
      Retrieves the protocol representation from the Scheme. In case of a scheme unknown by the Scheme enumeration, then SchemeAccessor.getScheme() might return null whilst SchemeAccessor.toProtocol() still retrieves the unknown scheme's protocol representation (as of SchemeAccessor.SchemeMutator.setProtocol(String)).
      Specified by:
      toProtocol in interface SchemeAccessor
      Returns:
      The protocol representation for the URL.

    • toHost

      public String toHost()
      Returns the "host" depending on whether an IP-Address has been provided or a host name.
      Returns:
      The determined host.

    • toHttpUrl

      public String toHttpUrl()
      Creates the complete "HTTP" URL String from the Url instance's state.
      Returns:
      The URL String for the given Url.

    • toLocator

      public String toLocator()
      Creates the locator part from the Url instance's state, excluding the fragment or the query fields.
      Returns:
      The locator for the given Url.

    • toURL

      public URL toURL() throws MalformedURLException
      Constructs an URL instance from your Url's state.
      Returns:
      The according URL instance.
      Throws:
      MalformedURLException - thrown in case the state of your Url instance cannot be used to construct a valid URL, you may be missing some properties.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • fromUrl

      protected void fromUrl(String aUrl) throws MalformedURLException
      Uses the given String to set the Url's state.
      Parameters:
      aUrl - The URL from which to determine the state.
      Throws:
      MalformedURLException - in case the provided URL is considered being malformed.

    • fromURL

      protected void fromURL(URL aUrl)

    • setScheme

      protected void setScheme(Scheme aScheme)

    • setProtocol

      protected void setProtocol(String aProtocol)

    • setHost

      protected void setHost(String aHost)

    • setIpAddress

      protected void setIpAddress(int[] aIpAddress)

    • setPort

      protected void setPort(int aPort)

    • setPath

      protected void setPath(String aPath)

    • toTruncatePathPrefix

      protected static String toTruncatePathPrefix(String aPath)
      Removes any leading path delimiters (as of Delimiter.PATH).
      Parameters:
      aPath - The path to be processed.
      Returns:
      The path without any leading path delimiters.

    • toTruncatePathSuffix

      protected static String toTruncatePathSuffix(String aPath)
      Removes any trailing path delimiters (as of Delimiter.PATH).
      Parameters:
      aPath - The path to be processed.
      Returns:
      The path without any trailing path delimiters.

    • toTruncatePath

      protected static String toTruncatePath(String aPath)
      Removes any leading and trailing path delimiters (as of Delimiter.PATH).
      Parameters:
      aPath - The path to be processed.
      Returns:
      The path with neither any leading nor any trailing path delimiters.