Package org.apache.hc.core5.net

Class URIBuilder

  • public class URIBuilder
extends java.lang.Object
    Builder for URI instances.
    Since:
    5.0

    • Field Detail

      • scheme

        private java.lang.String scheme

      • encodedSchemeSpecificPart

        private java.lang.String encodedSchemeSpecificPart

      • encodedAuthority

        private java.lang.String encodedAuthority

      • userInfo

        private java.lang.String userInfo

      • encodedUserInfo

        private java.lang.String encodedUserInfo

      • host

        private java.lang.String host

      • port

        private int port

      • encodedPath

        private java.lang.String encodedPath

      • pathRootless

        private boolean pathRootless

      • pathSegments

        private java.util.List<java.lang.String> pathSegments

      • encodedQuery

        private java.lang.String encodedQuery

      • query

        private java.lang.String query

      • charset

        private java.nio.charset.Charset charset

      • fragment

        private java.lang.String fragment

      • encodedFragment

        private java.lang.String encodedFragment

      • QUERY_PARAM_SEPARATORS

        private static final java.util.BitSet QUERY_PARAM_SEPARATORS

      • QUERY_VALUE_SEPARATORS

        private static final java.util.BitSet QUERY_VALUE_SEPARATORS

      • PATH_SEPARATORS

        private static final java.util.BitSet PATH_SEPARATORS

    • Constructor Detail

      • URIBuilder

        public URIBuilder()
        Constructs an empty instance.

      • URIBuilder

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

      • URIBuilder

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

      • URIBuilder

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

      • URIBuilder

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

    • Method Detail

      • localhost

        public static URIBuilder localhost()
                            throws java.net.UnknownHostException
        Creates a new builder for the host InetAddress.getLocalHost().
        Returns:
        a new builder.
        Throws:
        java.net.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​(java.nio.charset.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 java.nio.charset.Charset getCharset()
        Gets the Charset.
        Returns:
        the Charset.

      • parseQuery

        static java.util.List<NameValuePair> parseQuery​(java.lang.CharSequence s,
                                                java.nio.charset.Charset charset,
                                                boolean plusAsBlank)

      • splitPath

        static java.util.List<java.lang.String> splitPath​(java.lang.CharSequence s)

      • parsePath

        static java.util.List<java.lang.String> parsePath​(java.lang.CharSequence s,
                                                  java.nio.charset.Charset charset)

      • formatPath

        static void formatPath​(java.lang.StringBuilder buf,
                       java.lang.Iterable<java.lang.String> segments,
                       boolean rootless,
                       java.nio.charset.Charset charset)

      • formatQuery

        static void formatQuery​(java.lang.StringBuilder buf,
                        java.lang.Iterable<? extends NameValuePair> params,
                        java.nio.charset.Charset charset,
                        boolean blankAsPlus)

      • build

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

      • buildString

        private java.lang.String buildString()

      • digestURI

        private void digestURI​(java.net.URI uri,
                       java.nio.charset.Charset charset)

      • setScheme

        public URIBuilder setScheme​(java.lang.String scheme)
        Sets URI scheme.
        Returns:
        this.

      • setSchemeSpecificPart

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

      • setSchemeSpecificPart

        public URIBuilder setSchemeSpecificPart​(java.lang.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​(java.lang.String schemeSpecificPart,
                                        java.util.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​(java.lang.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​(java.lang.String username,
                              java.lang.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.

      • setHost

        public URIBuilder setHost​(java.net.InetAddress host)
        Sets URI host.
        Returns:
        this.

      • setHost

        public URIBuilder setHost​(java.lang.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​(java.lang.String path)
        Sets URI path. The value is expected to be unescaped and may contain non ASCII characters.
        Returns:
        this.

      • appendPath

        public URIBuilder appendPath​(java.lang.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​(java.lang.String... pathSegments)
        Sets URI path. The value is expected to be unescaped and may contain non ASCII characters.
        Returns:
        this.

      • appendPathSegments

        public URIBuilder appendPathSegments​(java.lang.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​(java.lang.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​(java.util.List<java.lang.String> pathSegments)
        Sets URI path. The value is expected to be unescaped and may contain non ASCII characters.
        Returns:
        this.

      • appendPathSegments

        public URIBuilder appendPathSegments​(java.util.List<java.lang.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​(java.util.List<java.lang.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​(java.util.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​(java.util.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​(java.lang.String param,
                               java.lang.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​(java.lang.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​(java.lang.String param,
                               java.lang.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​(java.lang.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​(java.lang.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 java.lang.String getScheme()
        Gets the scheme.
        Returns:
        the scheme.

      • getSchemeSpecificPart

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

      • getUserInfo

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

      • getHost

        public java.lang.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 java.util.List<java.lang.String> getPathSegments()
        Gets the path segments.
        Returns:
        the path segments.

      • getPath

        public java.lang.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 java.util.List<NameValuePair> getQueryParams()
        Gets the query parameters as a List.
        Returns:
        the query parameters as a List.

      • getFirstQueryParam

        public NameValuePair getFirstQueryParam​(java.lang.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 java.lang.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 java.lang.String toString()
        Converts this instance to a URI string.
        Overrides:
        toString in class java.lang.Object
        Returns:
        this instance to a URI string.