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:

  • Field Details

    • DEFAULT_HTTP_PORT

      public static final int DEFAULT_HTTP_PORT
      Default URL HTTP Port.
      See Also:

    • DEFAULT_HTTPS_PORT

      public static final int DEFAULT_HTTPS_PORT
      Default Secure URL HTTP Port.
      See Also:

    • PROTOCOL_HTTP

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

    • PROTOCOL_HTTPS

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

  • 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