Package org.forgerock.http.util

Class Uris

  • public final class Uris
extends Object
    Utility class for performing operations on universal resource identifiers.

    • Method Detail

      • create

        public static URI create​(String scheme,
                         String rawUserInfo,
                         String host,
                         int port,
                         String rawPath,
                         String rawQuery,
                         String rawFragment)
                  throws URISyntaxException
        Returns a hierarchical URI constructed from the given components. Differs from the URI constructor by accepting raw versions of userInfo, path, query and fragment components.

        Unlike createNonStrict(java.lang.String, java.lang.String, java.lang.String, int, java.lang.String, java.lang.String, java.lang.String), this method does not tolerate invalid characters, such as double-quotes, in the query string.

        Parameters:
        scheme - the scheme component of the URI or null if none.
        rawUserInfo - the raw user-information component of the URI or null if none.
        host - the host component of the URI or null if none.
        port - the port number of the URI or -1 if none.
        rawPath - the raw path component of the URI or null if none.
        rawQuery - the raw query component of the URI or null if none. The raw query must not contain characters that should have been percent encoded.
        rawFragment - the raw fragment component of the URI or null if none.
        Returns:
        the URI constructed from the given components.
        Throws:
        URISyntaxException - if the resulting URI would be malformed per RFC 2396.

      • create

        public static URI create​(String scheme,
                         String rawAuthority,
                         String rawPath,
                         String rawQuery,
                         String rawFragment)
                  throws URISyntaxException
        Returns a hierarchical URI constructed from the given components. Differs from the URI constructor by accepting raw versions of authority, path, query and fragment components.

        Unlike createNonStrict(java.lang.String, java.lang.String, java.lang.String, int, java.lang.String, java.lang.String, java.lang.String), this method does not tolerate invalid characters, such as double-quotes, in the query string.

        Parameters:
        scheme - the scheme component of the URI or null if none.
        rawAuthority - the raw authority component of the URI or null if none.
        rawPath - the raw path component of the URI or null if none.
        rawQuery - the raw query component of the URI or null if none. The raw query must not contain characters that should have been percent encoded.
        rawFragment - the raw fragment component of the URI or null if none.
        Returns:
        the URI constructed from the given components.
        Throws:
        URISyntaxException - if the resulting URI would be malformed per RFC 2396.

      • createNonStrict

        public static URI createNonStrict​(String scheme,
                                  String rawUserInfo,
                                  String host,
                                  int port,
                                  String rawPath,
                                  String rawQuery,
                                  String rawFragment)
                           throws URISyntaxException
        Returns a hierarchical URI constructed from the given components. Differs from the URI constructor by accepting raw versions of userInfo, path, query and fragment components.

        Unlike create(java.lang.String, java.lang.String, java.lang.String, int, java.lang.String, java.lang.String, java.lang.String), this method tolerates invalid characters, such as double-quotes, in the query string.

        Parameters:
        scheme - the scheme component of the URI or null if none.
        rawUserInfo - the raw user-information component of the URI or null if none.
        host - the host component of the URI or null if none.
        port - the port number of the URI or -1 if none.
        rawPath - the raw path component of the URI or null if none.
        rawQuery - the raw query component of the URI or null if none. The raw query may contain characters that should have been percent encoded.
        rawFragment - the raw fragment component of the URI or null if none.
        Returns:
        the URI constructed from the given components.
        Throws:
        URISyntaxException - if the resulting URI would be malformed per RFC 2396.

      • rebase

        public static URI rebase​(URI uri,
                         URI base)
        Changes the base scheme, host and port of a request to that specified in a base URI, or leaves them unchanged if the base URI is null. This implementation only uses scheme, host and port. The remaining components of the URI remain intact.
        Parameters:
        uri - the URI whose base is to be changed.
        base - the URI to base the other URI on.
        Returns:
        the the URI with the new established base.

      • withQuery

        public static URI withQuery​(URI uri,
                            Form query)
        Returns a new URI having the provided query parameters. The scheme, authority, path, and fragment remain unchanged.
        Parameters:
        uri - the URI whose query is to be changed.
        query - the form containing the query parameters.
        Returns:
        a new URI having the provided query parameters. The scheme, authority, path, and fragment remain unchanged.

      • withoutQueryAndFragment

        public static URI withoutQueryAndFragment​(URI uri)
        Returns a new URI having the same scheme, authority and path, but no query nor fragment.
        Parameters:
        uri - the URI whose query and fragments are to be removed.
        Returns:
        a new URI having the same scheme, authority and path, but no query nor fragment.

      • formDecodeParameterNameOrValue

        public static String formDecodeParameterNameOrValue​(String nameOrValue)
        Decodes the provided form encoded parameter name or value as per application/x-www-form-urlencoded.
        Parameters:
        nameOrValue - the form encoded parameter name or value, which may be null.
        Returns:
        the decoded form parameter name or value, or null if nameOrValue was null.

      • formEncodeParameterNameOrValue

        public static String formEncodeParameterNameOrValue​(String nameOrValue)
        Form encodes the provided parameter name or value as per application/x-www-form-urlencoded.
        Parameters:
        nameOrValue - the parameter name or value, which may be null.
        Returns:
        the form encoded parameter name or value, or null if nameOrValue was null.

      • urlDecodePathElement

        public static String urlDecodePathElement​(String pathElement)
        Decodes the provided URL encoded path element as per RFC 3986.
        Parameters:
        pathElement - the URL encoded path element, which may be null.
        Returns:
        the decoded path element, or null if pathElement was null.

      • urlEncodePathElement

        public static String urlEncodePathElement​(String pathElement)
        URL encodes the provided path element as per RFC 3986.
        Parameters:
        pathElement - the path element, which may be null.
        Returns:
        the URL encoded path element, or null if pathElement was null.

      • urlDecodeQueryParameterNameOrValue

        public static String urlDecodeQueryParameterNameOrValue​(String nameOrValue)
        Decodes the provided URL encoded query parameter name or value as per RFC 3986.
        Parameters:
        nameOrValue - the URL encoded query parameter name or value, which may be null.
        Returns:
        the decoded query parameter name or value, or null if nameOrValue was null.

      • urlEncodeQueryParameterNameOrValue

        public static String urlEncodeQueryParameterNameOrValue​(String nameOrValue)
        URL encodes the provided query parameter name or value as per RFC 3986. Note that this method does not adhere to the "query" production in RFC 3986, because it is intended for encoding query parameter names or values (not the whole query-string value).

        Therefore, this method will encode '&' and '=' characters (that are separators inside query-strings), and '+' (which is used for encoding white space - see w3c).

        Parameters:
        nameOrValue - the query parameter name or value, which may be null.
        Returns:
        the URL encoded query parameter name or value, or null if nameOrValue was null.

      • urlDecodeFragment

        public static String urlDecodeFragment​(String fragment)
        Decodes the provided URL encoded fragment as per RFC 3986.
        Parameters:
        fragment - the URL encoded fragment, which may be null.
        Returns:
        the decoded fragment, or null if fragment was null.

      • urlEncodeFragment

        public static String urlEncodeFragment​(String fragment)
        URL encodes the provided fragment as per RFC 3986.
        Parameters:
        fragment - the fragment, which may be null.
        Returns:
        the URL encoded fragment, or null if fragment was null.

      • urlDecodeUserInfo

        public static String urlDecodeUserInfo​(String userInfo)
        Decodes the provided URL encoded userInfo as per RFC 3986.
        Parameters:
        userInfo - the URL encoded userInfo, which may be null.
        Returns:
        the decoded userInfo, or null if userInfo was null.

      • urlEncodeUserInfo

        public static String urlEncodeUserInfo​(String userInfo)
        URL encodes the provided userInfo as per RFC 3986.
        Parameters:
        userInfo - the userInfo, which may be null.
        Returns:
        the URL encoded userInfo, or null if userInfo was null.

      • appendQuery

        public static URI appendQuery​(URI uri,
                              Form query)
        Returns a new URI with the given query parameters appended to the original ones, if any. The scheme, authority, path, and fragment remain unchanged.
        Parameters:
        uri - The URI whose query is to be changed, not null.
        query - The form containing the query parameters to add.
        Returns:
        A new URI having the provided query parameters added to the given URI. The scheme, authority, path, and fragment remain unchanged.

      • createUri

        public static URI createUri​(String scheme,
                            String rawUserInfo,
                            String hostname,
                            int port,
                            String rawPath,
                            String rawQueryString,
                            String rawFragment,
                            boolean preserveOriginalQueryString)
                     throws URISyntaxException
        Create a new URI given all provided URI components, query string can be strictly processed or not.

        If preserveOriginalQueryString set to false (the default), invalid chars are actively percent-encoded. Note that active percent-encoding has side effect: we execute a decode/encode round-trip, therefore percent-encoded chars (in the original query) may not stay untouched (if they not strictly require percent-encoding as per RFC-3986).

        If set to true, query string is preserved, but if it contains invalid characters, CHF will reject the request with a Bad Request error response.

        Parameters:
        scheme - URI scheme
        rawUserInfo - URI raw user info
        hostname - URI host name
        port - URI port (can be -1 for default port)
        rawPath - URI raw path
        rawQueryString - URI raw query string
        rawFragment - URI raw query string
        preserveOriginalQueryString - preserve query strings (strict) or tolerate invalid chars
        Returns:
        a new URI instance
        Throws:
        URISyntaxException - if the URI cannot be build (invalid chars, ...)