Module bus.http
Package org.miaixz.bus.http

Class UnoUrl

java.lang.Object
org.miaixz.bus.http.UnoUrl
public final class UnoUrl extends Object
A Uniform Resource Locator (URL) for HTTP or HTTPS.

This class provides a robust and exception-free way to build, parse, and handle URLs for HTTP and HTTPS protocols. It avoids checked exceptions by returning null or throwing an IllegalArgumentException for invalid URLs. Instances are immutable and support encoding and decoding of URL components.

Since:
Java 17+
Author:
Kimi Liu

  • Field Details

    • USERNAME_ENCODE_SET

      public static final String USERNAME_ENCODE_SET
      The character set for encoding usernames.
      See Also:

    • PASSWORD_ENCODE_SET

      public static final String PASSWORD_ENCODE_SET
      The character set for encoding passwords.
      See Also:

    • PATH_SEGMENT_ENCODE_SET

      public static final String PATH_SEGMENT_ENCODE_SET
      The character set for encoding path segments.
      See Also:

    • PATH_SEGMENT_ENCODE_SET_URI

      public static final String PATH_SEGMENT_ENCODE_SET_URI
      The character set for encoding URI path segments.
      See Also:

    • QUERY_ENCODE_SET

      public static final String QUERY_ENCODE_SET
      The character set for encoding query parameters.
      See Also:

    • QUERY_COMPONENT_REENCODE_SET

      public static final String QUERY_COMPONENT_REENCODE_SET
      The character set for re-encoding query components.
      See Also:

    • QUERY_COMPONENT_ENCODE_SET

      public static final String QUERY_COMPONENT_ENCODE_SET
      The character set for encoding query components.
      See Also:

    • QUERY_COMPONENT_ENCODE_SET_URI

      public static final String QUERY_COMPONENT_ENCODE_SET_URI
      The character set for encoding URI query components.
      See Also:

    • FORM_ENCODE_SET

      public static final String FORM_ENCODE_SET
      The character set for encoding form data.
      See Also:

    • FRAGMENT_ENCODE_SET

      public static final String FRAGMENT_ENCODE_SET
      The character set for encoding fragments.
      See Also:

    • FRAGMENT_ENCODE_SET_URI

      public static final String FRAGMENT_ENCODE_SET_URI
      The character set for encoding URI fragments.
      See Also:

  • Method Details

    • defaultPort

      public static int defaultPort(String scheme)
      Returns the default port for a given scheme.

      Returns 80 for "http", 443 for "https", and -1 for other schemes.

      Parameters:
      scheme - The scheme name.
      Returns:
      The default port number.

    • parse

      public static UnoUrl parse(String url)
      Parses a URL string into a UnoUrl instance.

      Returns a UnoUrl instance if the URL is well-formed, or null otherwise.

      Parameters:
      url - The URL string.
      Returns:
      A UnoUrl instance or null.

    • get

      public static UnoUrl get(String url)
      Builds a UnoUrl instance from a URL string.

      Throws an IllegalArgumentException if the URL is not well-formed.

      Parameters:
      url - The URL string.
      Returns:
      A UnoUrl instance.
      Throws:
      IllegalArgumentException - if the URL is not well-formed.

    • get

      public static UnoUrl get(URL url)
      Builds a UnoUrl instance from a URL object.

      Only supports http and https schemes. Returns null for other schemes.

      Parameters:
      url - The URL object.
      Returns:
      A UnoUrl instance or null.

    • get

      public static UnoUrl get(URI uri)
      Builds a UnoUrl instance from a URI object.
      Parameters:
      uri - The URI object.
      Returns:
      A UnoUrl instance or null.

    • percentDecode

      public static String percentDecode(String encoded, boolean plusIsSpace)
      Decodes a percent-encoded string.
      Parameters:
      encoded - The encoded string.
      plusIsSpace - Whether to decode plus signs as spaces.
      Returns:
      The decoded string.

    • percentDecode

      public static String percentDecode(String encoded, int pos, int limit, boolean plusIsSpace)
      Decodes a percent-encoded string within a specified range.
      Parameters:
      encoded - The encoded string.
      pos - The starting position.
      limit - The ending position.
      plusIsSpace - Whether to decode plus signs as spaces.
      Returns:
      The decoded string.

    • percentDecode

      public static void percentDecode(org.miaixz.bus.core.io.buffer.Buffer out, String encoded, int pos, int limit, boolean plusIsSpace)
      Decodes a percent-encoded string into a buffer.
      Parameters:
      out - The output buffer.
      encoded - The encoded string.
      pos - The starting position.
      limit - The ending position.
      plusIsSpace - Whether to decode plus signs as spaces.

    • percentEncoded

      public static boolean percentEncoded(String encoded, int pos, int limit)
      Checks if a string is percent-encoded.
      Parameters:
      encoded - The encoded string.
      pos - The starting position.
      limit - The ending position.
      Returns:
      true if the string is percent-encoded.

    • canonicalize

      public static String canonicalize(String input, int pos, int limit, String encodeSet, boolean alreadyEncoded, boolean strict, boolean plusIsSpace, boolean asciiOnly, Charset charset)
      Canonicalizes a string by encoding characters from a given set.
      Parameters:
      input - The input string.
      pos - The starting position.
      limit - The ending position.
      encodeSet - The set of characters to encode.
      alreadyEncoded - Whether the string is already encoded.
      strict - Whether to use strict encoding.
      plusIsSpace - Whether to encode plus signs as spaces.
      asciiOnly - Whether to limit to ASCII characters.
      charset - The character set to use (null for UTF-8).
      Returns:
      The canonicalized string.

    • canonicalize

      public static void canonicalize(org.miaixz.bus.core.io.buffer.Buffer out, String input, int pos, int limit, String encodeSet, boolean alreadyEncoded, boolean strict, boolean plusIsSpace, boolean asciiOnly, Charset charset)
      Canonicalizes a string into a buffer.
      Parameters:
      out - The output buffer.
      input - The input string.
      pos - The starting position.
      limit - The ending position.
      encodeSet - The set of characters to encode.
      alreadyEncoded - Whether the string is already encoded.
      strict - Whether to use strict encoding.
      plusIsSpace - Whether to encode plus signs as spaces.
      asciiOnly - Whether to limit to ASCII characters.
      charset - The character set to use (null for UTF-8).

    • canonicalize

      public static String canonicalize(String input, String encodeSet, boolean alreadyEncoded, boolean strict, boolean plusIsSpace, boolean asciiOnly, Charset charset)
      Canonicalizes a string with default UTF-8 encoding.
      Parameters:
      input - The input string.
      encodeSet - The set of characters to encode.
      alreadyEncoded - Whether the string is already encoded.
      strict - Whether to use strict encoding.
      plusIsSpace - Whether to encode plus signs as spaces.
      asciiOnly - Whether to limit to ASCII characters.
      charset - The character set to use (null for UTF-8).
      Returns:
      The canonicalized string.

    • canonicalize

      public static String canonicalize(String input, String encodeSet, boolean alreadyEncoded, boolean strict, boolean plusIsSpace, boolean asciiOnly)
      Canonicalizes a string with default UTF-8 encoding.
      Parameters:
      input - The input string.
      encodeSet - The set of characters to encode.
      alreadyEncoded - Whether the string is already encoded.
      strict - Whether to use strict encoding.
      plusIsSpace - Whether to encode plus signs as spaces.
      asciiOnly - Whether to limit to ASCII characters.
      Returns:
      The canonicalized string.

    • url

      public URL url()
      Converts this UnoUrl to a URL object.
      Returns:
      The URL object.
      Throws:
      RuntimeException - if the URL is malformed.

    • uri

      public URI uri()
      Converts this UnoUrl to a URI object.

      Note: URI is more strict than UnoUrl and may escape or remove certain characters (like whitespace in fragments). It is recommended to avoid using URI directly to prevent differences in server interpretation.

      Returns:
      The URI object.
      Throws:
      RuntimeException - if the URI syntax is invalid.

    • scheme

      public String scheme()
      Returns the scheme of this URL.
      Returns:
      The scheme (http or https).

    • isHttps

      public boolean isHttps()
      Returns true if this URL uses the HTTPS scheme.
      Returns:
      true if the scheme is HTTPS.

    • encodedUsername

      public String encodedUsername()
      Returns the encoded username.
      Returns:
      The encoded username, or an empty string if not set.

    • username

      public String username()
      Returns the decoded username.
      Returns:
      The decoded username.

    • encodedPassword

      public String encodedPassword()
      Returns the encoded password.
      Returns:
      The encoded password, or an empty string if not set.

    • password

      public String password()
      Returns the decoded password.
      Returns:
      The decoded password.

    • host

      public String host()
      Returns the hostname.
      Returns:
      The hostname, which can be a regular hostname, an IPv4 address, an IPv6 address, or an encoded IDN.

    • port

      public int port()
      Returns the port number.
      Returns:
      The port number.

    • pathSize

      public int pathSize()
      Returns the number of path segments.
      Returns:
      The number of path segments.

    • encodedPath

      public String encodedPath()
      Returns the encoded path.
      Returns:
      The encoded path of the URL.

    • encodedPathSegments

      public List<String> encodedPathSegments()
      Returns the list of encoded path segments.
      Returns:
      The list of encoded path segments.

    • pathSegments

      public List<String> pathSegments()
      Returns the list of decoded path segments.
      Returns:
      The list of decoded path segments.

    • encodedQuery

      public String encodedQuery()
      Returns the encoded query string.
      Returns:
      The encoded query string, or null if no query is present.

    • query

      public String query()
      Returns the decoded query string.
      Returns:
      The decoded query string, or null if no query is present.

    • querySize

      public int querySize()
      Returns the number of query parameters.
      Returns:
      The number of query parameters.

    • queryParameter

      public String queryParameter(String name)
      Returns the first value for the given query parameter name.
      Parameters:
      name - The name of the query parameter.
      Returns:
      The value of the query parameter, or null if not found.

    • queryParameterNames

      public Set<String> queryParameterNames()
      Returns a set of all query parameter names.
      Returns:
      An unmodifiable set of query parameter names.

    • queryParameterValues

      public List<String> queryParameterValues(String name)
      Returns all values for the given query parameter name.
      Parameters:
      name - The name of the query parameter.
      Returns:
      An unmodifiable list of query parameter values.

    • queryParameterName

      public String queryParameterName(int index)
      Returns the name of the query parameter at the given index.
      Parameters:
      index - The index of the query parameter.
      Returns:
      The name of the query parameter.
      Throws:
      IndexOutOfBoundsException - if the index is out of range.

    • queryParameterValue

      public String queryParameterValue(int index)
      Returns the value of the query parameter at the given index.
      Parameters:
      index - The index of the query parameter.
      Returns:
      The value of the query parameter.
      Throws:
      IndexOutOfBoundsException - if the index is out of range.

    • encodedFragment

      public String encodedFragment()
      Returns the encoded fragment.
      Returns:
      The encoded fragment, or null if no fragment is present.

    • fragment

      public String fragment()
      Returns the decoded fragment.
      Returns:
      The decoded fragment, or null if no fragment is present.

    • redact

      public String redact()
      Returns a new URL with sensitive information redacted.
      Returns:
      A new URL string with the username and password removed.

    • resolve

      public UnoUrl resolve(String link)
      Resolves a relative link against this URL.
      Parameters:
      link - The relative link.
      Returns:
      The resolved UnoUrl instance, or null if the link is invalid.

    • newBuilder

      public UnoUrl.Builder newBuilder()
      Creates a new builder initialized with the components of this URL.
      Returns:
      A new builder instance.

    • newBuilder

      public UnoUrl.Builder newBuilder(String link)
      Creates a new builder for a relative link.
      Parameters:
      link - The relative link.
      Returns:
      A new builder instance, or null if the link is invalid.

    • equals

      public boolean equals(Object other)
      Compares this URL to another object for equality.
      Overrides:
      equals in class Object
      Parameters:
      other - The other object to compare against.
      Returns:
      true if the two URLs are equal.

    • hashCode

      public int hashCode()
      Computes the hash code for this URL.
      Overrides:
      hashCode in class Object
      Returns:
      The hash code value.

    • toString

      public String toString()
      Returns the string representation of this URL.
      Overrides:
      toString in class Object
      Returns:
      The URL string.