org.apache.hc.core5.net

## Class URIBuilder

- java.lang.Object
- - org.apache.hc.core5.net.URIBuilder

-     public class URIBuilder
      extends Object

  Builder for `URI` instances.
  Since:
    5.0

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `URIBuilder()` Constructs an empty instance.
    `URIBuilder(String uriString)` Constructs an instance from the string which must be a valid URI.
    `URIBuilder(String uriString, Charset charset)` Constructs an instance from the string which must be a valid URI.
    `URIBuilder(URI uri)` Constructs an instance from the provided URI.
    `URIBuilder(URI uri, Charset charset)` Constructs an instance from the provided URI.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `URIBuilder` | `addParameter(NameValuePair nameValuePair)` Adds parameter to URI query.
    `URIBuilder` | `addParameter(String param, String value)` Adds parameter to URI query.
    `URIBuilder` | `addParameters(List<NameValuePair> nameValuePairs)` Adds URI query parameters.
    `URIBuilder` | `appendPath(String path)` Appends path to URI.
    `URIBuilder` | `appendPathSegments(List<String> pathSegments)` Appends segments to URI path.
    `URIBuilder` | `appendPathSegments(String... pathSegments)` Appends segments URI path.
    `URI` | `build()` Builds a `URI` instance.
    `URIBuilder` | `clearParameters()` Clears URI query parameters.
    `URIAuthority` | `getAuthority()` Gets the authority.
    `Charset` | `getCharset()` Gets the Charset.
    `NameValuePair` | `getFirstQueryParam(String name)` Gets the first `NameValuePair` for a given name.
    `String` | `getFragment()` Gets the fragments.
    `String` | `getHost()` Gets the host portion of the `URI`.
    `String` | `getPath()` Gets the path.
    `List<String>` | `getPathSegments()` Gets the path segments.
    `int` | `getPort()` Gets the port.
    `List<NameValuePair>` | `getQueryParams()` Gets the query parameters as a List.
    `String` | `getScheme()` Gets the scheme.
    `String` | `getSchemeSpecificPart()` Gets the scheme specific part.
    `String` | `getUserInfo()` Gets the user info.
    `boolean` | `isAbsolute()` Tests whether the URI is absolute.
    `boolean` | `isOpaque()` Tests whether the URI is opaque.
    `boolean` | `isPathEmpty()` Tests whether the path is empty.
    `boolean` | `isQueryEmpty()` Tests whether the query is empty.
    `static URIBuilder` | `localhost()` Creates a new builder for the host `InetAddress.getLocalHost()`.
    `static URIBuilder` | `loopbackAddress()` Creates a new builder for the host `InetAddress.getLoopbackAddress()`.
    `URIBuilder` | `normalizeSyntax()` Normalizes syntax of 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 normalized
    `URIBuilder` | `removeParameter(String param)` Removes parameter of URI query if set.
    `URIBuilder` | `removeQuery()` Removes URI query.
    `URIBuilder` | `setAuthority(NamedEndpoint authority)` Sets the authority.
    `URIBuilder` | `setAuthority(URIAuthority authority)` Sets the authority.
    `URIBuilder` | `setCharset(Charset charset)` Sets the Charset.
    `URIBuilder` | `setCustomQuery(String query)` Sets custom URI query.
    `URIBuilder` | `setFragment(String fragment)` Sets URI fragment.
    `URIBuilder` | `setHost(InetAddress host)` Sets URI host.
    `URIBuilder` | `setHost(String host)` Sets URI host.
    `URIBuilder` | `setHttpHost(HttpHost httpHost)` Sets the scheme, host name, and port.
    `URIBuilder` | `setParameter(String param, String value)` Sets parameter of URI query overriding existing value if set.
    `URIBuilder` | `setParameters(List<NameValuePair> nameValuePairs)` Sets URI query parameters.
    `URIBuilder` | `setParameters(NameValuePair... nameValuePairs)` Sets URI query parameters.
    `URIBuilder` | `setPath(String path)` Sets URI path.
    `URIBuilder` | `setPathSegments(List<String> pathSegments)` Sets URI path.
    `URIBuilder` | `setPathSegments(String... pathSegments)` Sets URI path.
    `URIBuilder` | `setPathSegmentsRootless(List<String> pathSegments)` Sets rootless URI path (the first segment does not start with a /).
    `URIBuilder` | `setPathSegmentsRootless(String... pathSegments)` Sets rootless URI path (the first segment does not start with a /).
    `URIBuilder` | `setPort(int port)` Sets URI port.
    `URIBuilder` | `setScheme(String scheme)` Sets URI scheme.
    `URIBuilder` | `setSchemeSpecificPart(String schemeSpecificPart)` Sets the URI scheme specific part.
    `URIBuilder` | `setSchemeSpecificPart(String schemeSpecificPart, List<NameValuePair> nvps)` Sets the URI scheme specific part and append a list of NameValuePair to this part.
    `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.
    `URIBuilder` | `setUserInfo(String userInfo)` Sets URI user info.
    `URIBuilder` | `setUserInfo(String username, String password)` Deprecated. The use of clear-text passwords in `URI`s has been deprecated and is strongly discouraged.
    `String` | `toString()` Converts this instance to a URI string.

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

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

- - ### Constructor Detail

    - #### 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 Detail

    - #### 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.
      Since:
        5.2

    - #### setAuthority

          public URIBuilder setAuthority(URIAuthority authority)

      Sets the authority.
      Parameters:
        `authority` - the authority.
      Returns:
        this.
      Since:
        5.2

    - #### setCharset

          public URIBuilder setCharset(Charset charset)

      Sets the Charset.
      Parameters:
        `charset` - the Charset.
      Returns:
        this.

    - #### getAuthority

          public URIAuthority getAuthority()

      Gets the authority.
      Returns:
        the authority.
      Since:
        5.2

    - #### getCharset

          public Charset getCharset()

      Gets the Charset.
      Returns:
        the Charset.

    - #### build

          public URI build()
                    throws URISyntaxException

      Builds a `URI` instance.
      Throws:
        `URISyntaxException`

    - #### setScheme

          public URIBuilder setScheme(String scheme)

      Sets URI scheme.
      Returns:
        this.

    - #### setSchemeSpecificPart

          public URIBuilder setSchemeSpecificPart(String schemeSpecificPart)

      Sets the URI scheme specific part.
      Parameters:
        `schemeSpecificPart` -
      Returns:
        this.
      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.
      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.
      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.

    - #### setUserInfo

          @Deprecated
          public URIBuilder setUserInfo(String username,
                                                    String password)

      Deprecated. The use of clear-text passwords in `URI`s 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.

    - #### setHost

          public URIBuilder setHost(InetAddress host)

      Sets URI host.
      Returns:
        this.

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

    - #### setHttpHost

          public URIBuilder setHttpHost(HttpHost httpHost)

      Sets the scheme, host name, and port.
      Parameters:
        `httpHost` - the scheme, host name, and port.
      Returns:
        this.

    - #### setPort

          public URIBuilder setPort(int port)

      Sets URI port.
      Returns:
        this.

    - #### setPath

          public URIBuilder setPath(String path)

      Sets URI path. The value is expected to be unescaped and may contain non ASCII characters.
      Returns:
        this.

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

    - #### setPathSegments

          public URIBuilder setPathSegments(String... pathSegments)

      Sets URI path. The value is expected to be unescaped and may contain non ASCII characters.
      Returns:
        this.

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

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

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

    - #### 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.
      Since:
        5.1

    - #### removeQuery

          public URIBuilder removeQuery()

      Removes URI query.
      Returns:
        this.

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

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

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

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

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

    - #### clearParameters

          public URIBuilder clearParameters()

      Clears URI query parameters.
      Returns:
        this.

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

    - #### setFragment

          public URIBuilder setFragment(String fragment)

      Sets URI fragment. The value is expected to be unescaped and may contain non ASCII characters.
      Returns:
        this.

    - #### 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

          public URIBuilder normalizeSyntax()

      Normalizes syntax of 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 normalized
      Since:
        5.1

    - #### toString

          public String toString()

      Converts this instance to a URI string.
      Overrides:
        `toString` in class `Object`
      Returns:
        this instance to a URI string.

Copyright © 2005–2022 The Apache Software Foundation. All rights reserved.