Module org.refcodes.web
Package org.refcodes.web

Class Url

  • All Implemented Interfaces:
    org.refcodes.mixin.CredentialsAccessor, org.refcodes.mixin.Dumpable, org.refcodes.mixin.IdentityAccessor, org.refcodes.mixin.PathAccessor, org.refcodes.mixin.PortAccessor, org.refcodes.mixin.SecretAccessor, org.refcodes.net.IpAddressAccessor, FragmentAccessor, HostAccessor, QueryFieldsAccessor, SchemeAccessor
    Direct Known Subclasses:
    UrlBuilder
    public class Url
extends Object
implements org.refcodes.mixin.Dumpable, SchemeAccessor, HostAccessor, org.refcodes.net.IpAddressAccessor, org.refcodes.mixin.PortAccessor, org.refcodes.mixin.PathAccessor, QueryFieldsAccessor, FragmentAccessor, org.refcodes.mixin.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 Detail

      • _scheme

        protected org.refcodes.data.Scheme _scheme

      • _protocol

        protected String _protocol

      • _host

        protected String _host

      • _ipAddress

        protected int[] _ipAddress

      • _path

        protected String _path

      • _port

        protected int _port

      • _identity

        protected String _identity

      • _secret

        protected String _secret

      • _fragment

        protected String _fragment

    • Constructor Detail

      • 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​(org.refcodes.data.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​(org.refcodes.data.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​(org.refcodes.data.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​(org.refcodes.data.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​(org.refcodes.data.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.
        aFragment - The fragment to be set.
        aQueryFields - The Query-Fields to be used for the HTTP Query-String.

      • 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.
        aFragment - The fragment to be set.
        aQueryFields - The Query-Fields to be used for the HTTP Query-String.

      • Url

        public Url​(org.refcodes.data.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​(org.refcodes.data.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​(org.refcodes.data.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 Detail

      • 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 org.refcodes.mixin.IdentityAccessor

      • getIpAddress

        public int[] getIpAddress()
        Specified by:
        getIpAddress in interface org.refcodes.net.IpAddressAccessor

      • getPath

        public String getPath()
        Specified by:
        getPath in interface org.refcodes.mixin.PathAccessor

      • getPort

        public int getPort()
        Specified by:
        getPort in interface org.refcodes.mixin.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 org.refcodes.data.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 org.refcodes.mixin.SecretAccessor

      • 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.

      • fromURL

        protected void fromURL​(URL aUrl)

      • setScheme

        protected void setScheme​(org.refcodes.data.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.