Package com.norconex.commons.lang.url

# Class HttpURL

java.lang.Object
com.norconex.commons.lang.url.HttpURL

All Implemented Interfaces:
  `Serializable`

public class HttpURL extends Object implements Serializable
This class act as a mutable URL supporting a more relaxed syntax (think browser-like parsing), which could be a replacement or "wrapper" to the `URL` class. It can also be used as a safer way to build a `URL` or a `URI` instance as it will properly escape appropriate characters before creating those.

See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEFAULT_HTTP_PORT`
  Default URL HTTP Port.
  `static final int`
  `DEFAULT_HTTPS_PORT`
  Default Secure URL HTTP Port.
  `static final String`
  `PROTOCOL_HTTP`
  Constant for "http" protocol.
  `static final String`
  `PROTOCOL_HTTPS`
  Constant for "https" protocol.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `HttpURL()`
  Creates a blank HttpURL using UTF-8 for URL encoding.
  `HttpURL(String url)`
  Creates a new HttpURL from the URL string using UTF-8 for URL encoding.
  `HttpURL(String url, String encoding)`
  Creates a new HttpURL from the URL string using the provided encoding for URL encoding.
  `HttpURL(@NonNull URL url)`
  Creates a new HttpURL from the URL object using UTF-8 for URL encoding.
  `HttpURL(@NonNull URL url, String encoding)`
  Creates a new HttpURL from the URL object using the provided encoding for URL encoding.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected boolean`
  `canEqual(Object other)`
  `static String`
  `encodePath(String path)`
  URL-Encodes a URL path.
  `static String`
  `encodeQueryString(String queryString)`
  URL-Encodes the query string portion of a URL.
  `boolean`
  `equals(Object o)`
  `String`
  `getEncoding()`
  Gets the character encoding.
  `String`
  `getFragment()`
  Gets the URL fragment.
  `String`
  `getHost()`
  Gets the host portion of the URL.
  `String`
  `getLastPathSegment()`
  Gets the last URL path segment without the query string.
  `String`
  `getPath()`
  Gets the URL path.
  `int`
  `getPort()`
  Gets the URL port as explicitly provided.
  `String`
  `getProtocol()`
  Gets the protocol portion of the URL (e.g. http, https);
  `QueryString`
  `getQueryString()`
  Gets the URL query string.
  `int`
  `getResolvedPort()`
  Resolves the actual URL port.
  `String`
  `getRoot()`
  Gets the root of a URL.
  `static String`
  `getRoot(String url)`
  Gets the root of a URL.
  `int`
  `hashCode()`
  `boolean`
  `isPortDefault()`
  Whether this URL uses the default port for the protocol.
  `boolean`
  `isSecure()`
  Whether this URL is secure (e.g. https).
  `HttpURL`
  `setFragment(String fragment)`
  Sets the URL fragment.
  `HttpURL`
  `setHost(String host)`
  Sets the host portion of the URL.
  `HttpURL`
  `setPath(String path)`
  Sets the URL path.
  `HttpURL`
  `setPort(int port)`
  Sets the URL port.
  `HttpURL`
  `setProtocol(String protocol)`
  Sets the protocol portion of the URL.
  `HttpURL`
  `setQueryString(QueryString queryString)`
  Sets the URL query string, replacing this URL existing query string parameters with the ones from the supplied query string (the original query string instance is kept).
  `static String`
  `toAbsolute(String baseURL, String relativeURL)`
  Converts a relative URL to an absolute one, based on the supplied base URL.
  `String`
  `toString()`
  Returns a string representation of this URL, properly encoded.
  `URI`
  `toURI()`
  Converts this HttpURL to a `URI`, making sure appropriate characters are escaped properly.
  `static URI`
  `toURI(String url)`
  Converts the supplied URL to a `URI`, making sure appropriate characters are encoded properly using UTF-8.
  `URL`
  `toURL()`
  Converts this HttpURL to a regular `URL`, making sure appropriate characters are escaped properly.
  `static URL`
  `toURL(String url)`
  Converts the supplied URL to a `URL`, making sure appropriate characters are encoded properly using UTF-8.

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### DEFAULT_HTTP_PORT

    public static final int DEFAULT_HTTP_PORT
    Default URL HTTP Port.
    See Also:
      - Constant Field Values

  - ### DEFAULT_HTTPS_PORT

    public static final int DEFAULT_HTTPS_PORT
    Default Secure URL HTTP Port.
    See Also:
      - Constant Field Values

  - ### PROTOCOL_HTTP

    public static final String PROTOCOL_HTTP
    Constant for "http" protocol.
    See Also:
      - Constant Field Values

  - ### PROTOCOL_HTTPS

    public static final String PROTOCOL_HTTPS
    Constant for "https" protocol.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### HttpURL

    public HttpURL()
    Creates a blank HttpURL using UTF-8 for URL encoding.

  - ### HttpURL

    public HttpURL(@NonNull @NonNull URL url)
    Creates a new HttpURL from the URL object using UTF-8 for URL encoding.
    Parameters:
      `url` - a URL

  - ### HttpURL

    public HttpURL(String url)
    Creates a new HttpURL from the URL string using UTF-8 for URL encoding.
    Parameters:
      `url` - a URL

  - ### HttpURL

    public HttpURL(@NonNull @NonNull URL url, String encoding)
    Creates a new HttpURL from the URL object using the provided encoding for URL encoding.
    Parameters:
      `url` - a URL
      `encoding` - character encoding
    Since:
      1.7.0

  - ### HttpURL

    public HttpURL(String url, String encoding)
    Creates a new HttpURL from the URL string using the provided encoding for URL encoding.
    Parameters:
      `url` - a URL string
      `encoding` - character encoding
    Since:
      1.7.0

- ## Method Details

  - ### getEncoding

    public String getEncoding()
    Gets the character encoding. Default is UTF-8.
    Returns:
      character encoding
    Since:
      1.7.0

  - ### getPath

    public String getPath()
    Gets the URL path.
    Returns:
      URL path

  - ### setPath

    public HttpURL setPath(String path)
    Sets the URL path.
    Parameters:
      `path` - url path
    Returns:
      this instance

  - ### getQueryString

    public QueryString getQueryString()
    Gets the URL query string. Changes to the returned query string will be applied to this URL query string. A URL without a query string returns an empty query string.
    Returns:
      URL query string, never `null`

  - ### setQueryString

    public HttpURL setQueryString(QueryString queryString)
    Sets the URL query string, replacing this URL existing query string parameters with the ones from the supplied query string (the original query string instance is kept).
    Parameters:
      `queryString` - the query string
    Returns:
      this instance

  - ### getHost

    public String getHost()
    Gets the host portion of the URL.
    Returns:
      the host portion of the URL

  - ### setHost

    public HttpURL setHost(String host)
    Sets the host portion of the URL.
    Parameters:
      `host` - the host portion of the URL
    Returns:
      this instance

  - ### getProtocol

    public String getProtocol()
    Gets the protocol portion of the URL (e.g. http, https);
    Returns:
      the protocol portion of the URL

  - ### setProtocol

    public HttpURL setProtocol(String protocol)
    Sets the protocol portion of the URL.
    Parameters:
      `protocol` - the protocol portion of the URL
    Returns:
      this instance

  - ### isSecure

    public boolean isSecure()
    Whether this URL is secure (e.g. https).
    Returns:
      `true` if protocol is secure

  - ### getPort

    public int getPort()
    Gets the URL port as explicitly provided. If no port was provided in the URL string or set via `setPort(int)`, -1 is returned.
    Returns:
      the URL port

  - ### setPort

    public HttpURL setPort(int port)
    Sets the URL port. Use -1 to indicate no explicit port should be used.
    Parameters:
      `port` - the URL port
    Returns:
      this instance

  - ### getResolvedPort

    public int getResolvedPort()
    Resolves the actual URL port. Returns the explicit port if one was provided; otherwise, returns the default port based on the protocol (80 for http, 443 for https).
    Returns:
      resolved port

  - ### getFragment

    public String getFragment()
    Gets the URL fragment.
    Returns:
      the fragment
    Since:
      1.8.0

  - ### setFragment

    public HttpURL setFragment(String fragment)
    Sets the URL fragment.
    Parameters:
      `fragment` - the fragment to set
    Returns:
      this instance
    Since:
      1.8.0

  - ### getLastPathSegment

    public String getLastPathSegment()
    Gets the last URL path segment without the query string. If there are no segment to return, an empty string will be returned instead.
    Returns:
      the last URL path segment

  - ### toURL

    public URL toURL()
    Converts this HttpURL to a regular `URL`, making sure appropriate characters are escaped properly.
    Returns:
      a URL
    Throws:
      `UrlException` - when URL is malformed

  - ### getRoot

    public String getRoot()

    Gets the root of a URL. That is the left part of a URL up to and including the host name. If a URL is only made of the scheme and host name, it is returned unchanged. A `null` or empty string returns a `null` document root.

    Returns:
      left part of a URL up to (and including) the host name or `null`
    Throws:
      `UrlException` - when URL is malformed
    Since:
      1.8.0

  - ### toURI

    public URI toURI()
    Converts this HttpURL to a `URI`, making sure appropriate characters are escaped properly.
    Returns:
      a URI
    Throws:
      `UrlException` - when URL is malformed
    Since:
      1.7.0

  - ### toURL

    public static URL toURL(String url)

    Converts the supplied URL to a `URL`, making sure appropriate characters are encoded properly using UTF-8. This method is a short form of:
    `new HttpURL("http://example.com").toURL();`

    Parameters:
      `url` - a URL string
    Returns:
      a URL object
    Throws:
      `UrlException` - when URL is malformed
    Since:
      1.7.0

  - ### toURI

    public static URI toURI(String url)

    Converts the supplied URL to a `URI`, making sure appropriate characters are encoded properly using UTF-8. This method is a short form of:
    `new HttpURL("http://example.com").toURI();`

    Parameters:
      `url` - a URL string
    Returns:
      a URI object
    Throws:
      `UrlException` - when URL is malformed
    Since:
      1.7.0

  - ### getRoot

    public static String getRoot(String url)

    Gets the root of a URL. That is the left part of a URL up to and including the host name. If a URL is only made of the scheme and host name, it is returned unchanged. A `null` or empty string returns a `null` document root. This method is a short form of:
    `new HttpURL("http://example.com/path").getRoot();`

    Parameters:
      `url` - a URL string
    Returns:
      left part of a URL up to (and including) the host name
    Since:
      1.8.0

  - ### toString

    public String toString()
    Returns a string representation of this URL, properly encoded.
    Overrides:
      `toString` in class `Object`
    Returns:
      URL as a string

  - ### isPortDefault

    public boolean isPortDefault()
    Whether this URL uses the default port for the protocol. The default ports are 80 for "http" protocol, and 443 for "https" or -1 (resolved dynamically). Other protocols are not supported and this method will always return false for them.
    Returns:
      `true` if the URL is using the default port.
    Since:
      1.8.0

  - ### encodeQueryString

    public static String encodeQueryString(String queryString)

    URL-Encodes the query string portion of a URL. The entire string supplied is assumed to be a query string.

    Parameters:
      `queryString` - URL query string
    Returns:
      encoded path
    Since:
      1.8.0

  - ### encodePath

    public static String encodePath(String path)

    URL-Encodes a URL path. The entire string supplied is assumed to be a URL path. Unsafe characters are percent-encoded using UTF-8 (as specified by W3C standard).

    Parameters:
      `path` - path portion of a URL
    Returns:
      encoded path
    Since:
      1.7.0

  - ### toAbsolute

    public static String toAbsolute(String baseURL, String relativeURL)

    Converts a relative URL to an absolute one, based on the supplied base URL. The base URL is assumed to be a valid URL. Behavior is unexpected when base URL is invalid.

    Since 2.0.1, supplying a `null` or blank relative URL will return the base URL.

    Since 2.0.1, if the relative URL starts with a scheme, it is considered an absolute URL and is returned as is after trim. The scheme is a string starting with a letter followed by any number of letters, numbers, plus sign (+), minus sign (-) or dot (.), followed by a colon (:).

    Parameters:
      `baseURL` - URL to the reference is relative to
      `relativeURL` - the relative URL portion to transform to absolute
    Returns:
      absolute URL
    Since:
      1.8.0

  - ### equals

    public boolean equals(Object o)
    Overrides:
      `equals` in class `Object`

  - ### canEqual

    protected boolean canEqual(Object other)

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`