Class URIBuilder

java.lang.Object
org.apache.hc.core5.net.URIBuilder
public class URIBuilder extends Object
Builder for URI instances.
Since:
5.0

  • Field Details

    • scheme

      private String scheme

    • encodedSchemeSpecificPart

      private String encodedSchemeSpecificPart

    • encodedAuthority

      private String encodedAuthority

    • userInfo

      private String userInfo

    • encodedUserInfo

      private String encodedUserInfo

    • host

      private String host

    • port

      private int port

    • encodedPath

      private String encodedPath

    • pathRootless

      private boolean pathRootless

    • pathSegments

      private List<String> pathSegments

    • encodedQuery

      private String encodedQuery

    • queryParams

      private List<NameValuePair> queryParams

    • query

      private String query

    • charset

      private Charset charset

    • fragment

      private String fragment

    • encodedFragment

      private String encodedFragment

    • encodingPolicy

      private URIBuilder.EncodingPolicy encodingPolicy

    • plusAsBlank

      private boolean plusAsBlank

    • QUERY_PARAM_SEPARATOR

      private static final char QUERY_PARAM_SEPARATOR
      See Also:

    • PARAM_VALUE_SEPARATOR

      private static final char PARAM_VALUE_SEPARATOR
      See Also:

    • PATH_SEPARATOR

      private static final char PATH_SEPARATOR
      See Also:

    • QUERY_PARAM_SEPARATORS

      private static final Tokenizer.Delimiter QUERY_PARAM_SEPARATORS

    • QUERY_VALUE_SEPARATORS

      private static final Tokenizer.Delimiter QUERY_VALUE_SEPARATORS

  • Constructor Details

    • URIBuilder

      public URIBuilder()
      Constructs an empty instance.

    • URIBuilder

      public URIBuilder(String uriString) throws URISyntaxException
      Constructs an instance from the string which must be a valid URI.
      Parameters:
      uriString - a valid URI in string form.
      Throws:
      URISyntaxException - if the input is not a valid URI.

    • URIBuilder

      public URIBuilder(URI uri)
      Constructs an instance from the provided URI.
      Parameters:
      uri - a URI.

    • URIBuilder

      public URIBuilder(String uriString, Charset charset) throws URISyntaxException
      Constructs an instance from the string which must be a valid URI.
      Parameters:
      uriString - a valid URI in string form.
      Throws:
      URISyntaxException - if the input is not a valid URI

    • URIBuilder

      public URIBuilder(URI uri, Charset charset)
      Constructs an instance from the provided URI.
      Parameters:
      uri - a URI.

  • Method Details

    • localhost

      public static URIBuilder localhost() throws UnknownHostException
      Creates a new builder for the host InetAddress.getLocalHost().
      Returns:
      a new builder.
      Throws:
      UnknownHostException - if the local host name could not be resolved into an address.

    • loopbackAddress

      public static URIBuilder loopbackAddress()
      Creates a new builder for the host InetAddress.getLoopbackAddress().

    • setAuthority

      public URIBuilder setAuthority(NamedEndpoint authority)
      Sets the authority.
      Parameters:
      authority - the authority.
      Returns:
      this instance.
      Since:
      5.2

    • setAuthority

      public URIBuilder setAuthority(URIAuthority authority)
      Sets the authority.
      Parameters:
      authority - the authority.
      Returns:
      this instance.
      Since:
      5.2

    • setCharset

      public URIBuilder setCharset(Charset charset)
      Sets the Charset.
      Parameters:
      charset - the Charset.
      Returns:
      this instance.

    • setEncodingPolicy

      public URIBuilder setEncodingPolicy(URIBuilder.EncodingPolicy encodingPolicy)
      Sets the encoding policy for this URIBuilder. The encoding policy determines how URI components (e.g., query, fragment) are percent-encoded when building the URI string. If not set, the default policy is URIBuilder.EncodingPolicy.RFC_3986.
      Parameters:
      encodingPolicy - the encoding policy to apply, or null to reset to the default (URIBuilder.EncodingPolicy.ALL_RESERVED)
      Returns:
      this URIBuilder instance for method chaining
      Since:
      5.4

    • getAuthority

      public URIAuthority getAuthority()
      Gets the authority.
      Returns:
      the authority.
      Since:
      5.2

    • getCharset

      public Charset getCharset()
      Gets the Charset.
      Returns:
      the Charset.

    • setPlusAsBlank

      public URIBuilder setPlusAsBlank(boolean plusAsBlank)
      Sets whether the plus sign ('+') should be interpreted as a blank space (' ') when parsing the query parameters of the URI.

      In HTTP URLs, query strings may contain spaces encoded as '+' characters or as '%20'. This flag controls whether '+' is interpreted as a space or remains as a plus sign.

      If the query string was already set, calling this method will re-parse the query using the updated flag. This ensures that the query parameters are processed correctly based on the specified interpretation of the '+' character.

      Parameters:
      plusAsBlank - true to interpret '+' as a space, false to keep '+' as a literal plus sign.
      Returns:
      this URIBuilder instance for method chaining.
      Since:
      5.4

    • parseQuery

      static List<NameValuePair> parseQuery(CharSequence s, Charset charset, boolean plusAsBlank)

    • splitPath

      static List<String> splitPath(CharSequence s)

    • parsePath

      static List<String> parsePath(CharSequence s, Charset charset)

    • formatPath

      static void formatPath(StringBuilder buf, Iterable<String> segments, boolean rootless, Charset charset, BitSet safechars)

    • formatPath

      static void formatPath(StringBuilder buf, Iterable<String> segments, boolean rootless, Charset charset)

    • formatQuery

      static void formatQuery(StringBuilder buf, Iterable<? extends NameValuePair> params, Charset charset, BitSet safechars, boolean blankAsPlus)

    • formatQuery

      static void formatQuery(StringBuilder buf, Iterable<? extends NameValuePair> params, Charset charset, boolean blankAsPlus)

    • build

      public URI build() throws URISyntaxException
      Builds a URI instance.
      Throws:
      URISyntaxException

    • buildString

      private String buildString()

    • digestURI

      private void digestURI(URI uri, Charset charset)

    • setScheme

      public URIBuilder setScheme(String scheme)
      Sets URI scheme.
      Returns:
      this instance.

    • setSchemeSpecificPart

      public URIBuilder setSchemeSpecificPart(String schemeSpecificPart)
      Sets the URI scheme specific part.
      Parameters:
      schemeSpecificPart -
      Returns:
      this instance.
      Since:
      5.1

    • setSchemeSpecificPart

      public URIBuilder setSchemeSpecificPart(String schemeSpecificPart, NameValuePair... nvps)
      Sets the URI scheme specific part and append a variable arguments list of NameValuePair instance(s) to this part.
      Parameters:
      schemeSpecificPart -
      nvps - Optional, can be null. Variable arguments list of NameValuePair query parameters to be reused by the specific scheme part
      Returns:
      this instance.
      Since:
      5.1

    • setSchemeSpecificPart

      public URIBuilder setSchemeSpecificPart(String schemeSpecificPart, List<NameValuePair> nvps)
      Sets the URI scheme specific part and append a list of NameValuePair to this part.
      Parameters:
      schemeSpecificPart -
      nvps - Optional, can be null. List of query parameters to be reused by the specific scheme part
      Returns:
      this instance.
      Since:
      5.1

    • setUserInfo

      public URIBuilder setUserInfo(String userInfo)
      Sets URI user info. The value is expected to be unescaped and may contain non ASCII characters.
      Returns:
      this instance.

    • setUserInfo

      @Deprecated public URIBuilder setUserInfo(String username, String password)
      Deprecated.
      The use of clear-text passwords in URIs has been deprecated and is strongly discouraged.
      Sets URI user info as a combination of username and password. These values are expected to be unescaped and may contain non ASCII characters.
      Returns:
      this instance.

    • setHost

      public URIBuilder setHost(InetAddress host)
      Sets URI host.
      Returns:
      this instance.

    • setHost

      public URIBuilder setHost(String host)
      Sets URI host. The input value must not already be URI encoded, for example ::1 is valid however [::1] is not. It is dangerous to call uriBuilder.setHost(uri.getHost()) due to URI.getHost() returning URI encoded values.
      Returns:
      this instance.

    • setHttpHost

      public URIBuilder setHttpHost(HttpHost httpHost)
      Sets the scheme, host name, and port.
      Parameters:
      httpHost - the scheme, host name, and port.
      Returns:
      this instance.

    • setPort

      public URIBuilder setPort(int port)
      Sets URI port.
      Returns:
      this instance.

    • setPath

      public URIBuilder setPath(String path)
      Sets URI path. The value is expected to be unescaped and may contain non ASCII characters.
      Returns:
      this instance.

    • appendPath

      public URIBuilder appendPath(String path)
      Appends path to URI. The value is expected to be unescaped and may contain non ASCII characters.
      Returns:
      this instance.

    • setPathSegments

      public URIBuilder setPathSegments(String... pathSegments)
      Sets URI path. The value is expected to be unescaped and may contain non ASCII characters.
      Returns:
      this instance.

    • appendPathSegments

      public URIBuilder appendPathSegments(String... pathSegments)
      Appends segments URI path. The value is expected to be unescaped and may contain non ASCII characters.
      Returns:
      this instance.

    • setPathSegmentsRootless

      public URIBuilder setPathSegmentsRootless(String... pathSegments)
      Sets rootless URI path (the first segment does not start with a /). The value is expected to be unescaped and may contain non ASCII characters.
      Returns:
      this instance.
      Since:
      5.1

    • setPathSegments

      public URIBuilder setPathSegments(List<String> pathSegments)
      Sets URI path. The value is expected to be unescaped and may contain non ASCII characters.
      Returns:
      this instance.

    • appendPathSegments

      public URIBuilder appendPathSegments(List<String> pathSegments)
      Appends segments to URI path. The value is expected to be unescaped and may contain non ASCII characters.
      Returns:
      this instance.

    • setPathSegmentsRootless

      public URIBuilder setPathSegmentsRootless(List<String> pathSegments)
      Sets rootless URI path (the first segment does not start with a /). The value is expected to be unescaped and may contain non ASCII characters.
      Returns:
      this instance.
      Since:
      5.1

    • removeQuery

      public URIBuilder removeQuery()
      Removes URI query.
      Returns:
      this instance.

    • setParameters

      public URIBuilder setParameters(List<NameValuePair> nameValuePairs)
      Sets URI query parameters. The parameter name / values are expected to be unescaped and may contain non ASCII characters.

      Please note query parameters and custom query component are mutually exclusive. This method will remove custom query if present.

      Returns:
      this instance.

    • addParameters

      public URIBuilder addParameters(List<NameValuePair> nameValuePairs)
      Adds URI query parameters. The parameter name / values are expected to be unescaped and may contain non ASCII characters.

      Please note query parameters and custom query component are mutually exclusive. This method will remove custom query if present.

      Returns:
      this instance.

    • setParameters

      public URIBuilder setParameters(NameValuePair... nameValuePairs)
      Sets URI query parameters. The parameter name / values are expected to be unescaped and may contain non ASCII characters.

      Please note query parameters and custom query component are mutually exclusive. This method will remove custom query if present.

      Returns:
      this instance.

    • addParameter

      public URIBuilder addParameter(String param, String value)
      Adds parameter to URI query. The parameter name and value are expected to be unescaped and may contain non ASCII characters.

      Please note query parameters and custom query component are mutually exclusive. This method will remove custom query if present.

      Returns:
      this instance.

    • addParameter

      public URIBuilder addParameter(NameValuePair nameValuePair)
      Adds parameter to URI query. The parameter name and value are expected to be unescaped and may contain non ASCII characters.

      Please note query parameters and custom query component are mutually exclusive. This method will remove custom query if present.

      Returns:
      this instance.
      Since:
      5.2

    • removeParameter

      public URIBuilder removeParameter(String param)
      Removes parameter of URI query if set. The parameter name is expected to be unescaped and may contain non ASCII characters.

      Please note query parameters and custom query component are mutually exclusive. This method will remove custom query if present, even when no parameter was actually removed.

      Returns:
      this instance.
      Since:
      5.2

    • setParameter

      public URIBuilder setParameter(String param, String value)
      Sets parameter of URI query overriding existing value if set. The parameter name and value are expected to be unescaped and may contain non ASCII characters.

      Please note query parameters and custom query component are mutually exclusive. This method will remove custom query if present.

      Returns:
      this instance.

    • clearParameters

      public URIBuilder clearParameters()
      Clears URI query parameters.
      Returns:
      this instance.

    • setCustomQuery

      public URIBuilder setCustomQuery(String query)
      Sets custom URI query. The value is expected to be unescaped and may contain non ASCII characters.

      Please note query parameters and custom query component are mutually exclusive. This method will remove query parameters if present.

      Returns:
      this instance.

    • setFragment

      public URIBuilder setFragment(String fragment)
      Sets URI fragment. The value is expected to be unescaped and may contain non ASCII characters.
      Returns:
      this instance.

    • isAbsolute

      public boolean isAbsolute()
      Tests whether the URI is absolute.
      Returns:
      whether the URI is absolute.

    • isOpaque

      public boolean isOpaque()
      Tests whether the URI is opaque.
      Returns:
      whether the URI is opaque.

    • getScheme

      public String getScheme()
      Gets the scheme.
      Returns:
      the scheme.

    • getSchemeSpecificPart

      public String getSchemeSpecificPart()
      Gets the scheme specific part.
      Returns:
      String
      Since:
      5.1

    • getUserInfo

      public String getUserInfo()
      Gets the user info.
      Returns:
      the user info.

    • getHost

      public String getHost()
      Gets the host portion of the URI. This method returns unencoded IPv6 addresses (without brackets). This behavior differs from values returned by URI.getHost().
      Returns:
      The host portion of the URI.

    • getPort

      public int getPort()
      Gets the port.
      Returns:
      the port.

    • isPathEmpty

      public boolean isPathEmpty()
      Tests whether the path is empty.
      Returns:
      whether the path is empty.

    • getPathSegments

      public List<String> getPathSegments()
      Gets the path segments.
      Returns:
      the path segments.

    • getPath

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

    • isQueryEmpty

      public boolean isQueryEmpty()
      Tests whether the query is empty.
      Returns:
      whether the query is empty.

    • getQueryParams

      public List<NameValuePair> getQueryParams()
      Gets the query parameters as a List.
      Returns:
      the query parameters as a List.

    • getFirstQueryParam

      public NameValuePair getFirstQueryParam(String name)
      Gets the first NameValuePair for a given name.
      Parameters:
      name - the name
      Returns:
      the first named NameValuePair or null if not found.
      Since:
      5.2

    • getFragment

      public String getFragment()
      Gets the fragments.
      Returns:
      the fragments.

    • normalizeSyntax

      @Deprecated public URIBuilder normalizeSyntax()
      Deprecated.
      do not use this method.
      See Also:

    • optimize

      public URIBuilder optimize()
      Optimizes URI components if the URI is considered non-opaque (the path component has a root):
      • characters of scheme and host components are converted to lower case
      • dot segments of the path component are removed if the path has a root
      • percent encoding of all components is re-applied

      Please note some URI consumers may consider the optimized URI components produced by this method as semantically different from the original ones.

      Since:
      5.3

    • toString

      public String toString()
      Converts this instance to a URI string.
      Overrides:
      toString in class Object
      Returns:
      this instance to a URI string.