org.forgerock.http.util

Class Uris

java.lang.Object

org.forgerock.http.util.Uris

public final class Uris
extends Object

Utility class for performing operations on universal resource identifiers.

Method Summary

Modifier and Type	Method and Description
static URI	appendQuery(URI uri, Form query) Returns a new URI with the given query parameters appended to the original ones, if any.
static URI	create(String scheme, String rawUserInfo, String host, int port, String rawPath, String rawQuery, String rawFragment) Returns a hierarchical URI constructed from the given components.
static URI	createNonStrict(String scheme, String rawUserInfo, String host, int port, String rawPath, String rawQuery, String rawFragment) Returns a hierarchical URI constructed from the given components.
static URI	createUri(String scheme, String rawUserInfo, String hostname, int port, String rawPath, String rawQueryString, String rawFragment, boolean preserveOriginalQueryString) Create a new URI given all provided URI components, query string can be strictly processed or not.
static String	formDecodeParameterNameOrValue(String nameOrValue) Decodes the provided form encoded parameter name or value as per application/x-www-form-urlencoded.
static String	formEncodeParameterNameOrValue(String nameOrValue) Form encodes the provided parameter name or value as per application/x-www-form-urlencoded.
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.
static String	urlDecodeFragment(String fragment) Decodes the provided URL encoded fragment as per RFC 3986.
static String	urlDecodePathElement(String pathElement) Decodes the provided URL encoded path element as per RFC 3986.
static String	urlDecodeQueryParameterNameOrValue(String nameOrValue) Decodes the provided URL encoded query parameter name or value as per RFC 3986.
static String	urlDecodeUserInfo(String userInfo) Decodes the provided URL encoded userInfo as per RFC 3986.
static String	urlEncodeFragment(String fragment) URL encodes the provided fragment as per RFC 3986.
static String	urlEncodePathElement(String pathElement) URL encodes the provided path element as per RFC 3986.
static String	urlEncodeQueryParameterNameOrValue(String nameOrValue) URL encodes the provided query parameter name or value as per RFC 3986.
static String	urlEncodeUserInfo(String userInfo) URL encodes the provided userInfo as per RFC 3986.
static URI	withoutQueryAndFragment(URI uri) Returns a new URI having the same scheme, authority and path, but no query nor fragment.
static URI	withQuery(URI uri, Form query) Returns a new URI having the provided query parameters.

Methods inherited from class java.lang.Object

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

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.

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. Therefore, this method will encode '?' and '=' characters.

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, ...)