net.shibboleth.utilities.java.support.net

Class URISupport

java.lang.Object

net.shibboleth.utilities.java.support.net.URISupport

@Beta
public final class URISupport
extends java.lang.Object

Helper methods for building URIs and parsing some HTTP URL information.

Constructor Summary

Constructors

Modifier	Constructor and Description
private	URISupport() Constructor.

Method Summary

Modifier and Type	Method and Description
static java.lang.String	buildQuery(java.util.List<Pair<java.lang.String,java.lang.String>> parameters) Builds an RFC-3968 encoded URL query component from a collection of parameters.
static java.lang.String	doURLDecode(java.lang.String value) Perform URL decoding on the given string.
static java.lang.String	doURLEncode(java.lang.String value) Perform URL encoding on the given string.
static java.net.URI	fileURIFromAbsolutePath(java.lang.String path) Create a file: URI from an absolute path, dealing with the Windows, non leading "/" issue.
static java.lang.String	getRawQueryStringParameter(java.lang.String queryString, java.lang.String paramName) Get the first raw (i.e.RFC-3968 encoded) query string component with the specified parameter name.
static java.util.List<Pair<java.lang.String,java.lang.String>>	parseQueryString(java.lang.String queryString) Parses a RFC-3968 encoded query string in to a set of name/value pairs.
static java.net.URI	setFragment(java.net.URI prototype, java.lang.String fragment) Sets the fragment of a URI.
static java.net.URI	setHost(java.net.URI prototype, java.lang.String host) Sets the host of a URI.
static java.net.URI	setPath(java.net.URI prototype, java.lang.String path) Sets the path of a URI.
static java.net.URI	setPort(java.net.URI prototype, int port) Sets the port of a URI.
static java.net.URI	setQuery(java.net.URI prototype, java.util.List<Pair<java.lang.String,java.lang.String>> parameters) Sets the query of a URI.
static java.net.URI	setQuery(java.net.URI prototype, java.lang.String query) Sets the query of a URI.
static java.net.URI	setScheme(java.net.URI prototype, java.lang.String scheme) Sets the scheme of a URI.
static java.lang.String	trimOrNullFragment(java.lang.String fragment) Trims an RFC-3968 encoded URL fragment component.
static java.lang.String	trimOrNullPath(java.lang.String path) Trims an RFC-3968 encoded URL path component.
static java.lang.String	trimOrNullQuery(java.lang.String query) Trims an RFC-3968 encoded URL query component.

Methods inherited from class java.lang.Object

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

Constructor Detail

URISupport

private URISupport()

Constructor.

Method Detail

setFragment

public static java.net.URI setFragment(java.net.URI prototype,
                                       java.lang.String fragment)

Sets the fragment of a URI.

Parameters:

prototype - prototype URI that provides information other than the fragment

fragment - fragment for the new URI

Returns:

new URI built from the prototype URI and the given fragment

setHost

public static java.net.URI setHost(java.net.URI prototype,
                                   java.lang.String host)

Sets the host of a URI.

Parameters:

prototype - prototype URI that provides information other than the host

host - host for the new URI

Returns:

new URI built from the prototype URI and the given host

setPath

public static java.net.URI setPath(java.net.URI prototype,
                                   java.lang.String path)

Sets the path of a URI.

Parameters:

prototype - prototype URI that provides information other than the path

path - path for the new URI

Returns:

new URI built from the prototype URI and the given path

setPort

public static java.net.URI setPort(java.net.URI prototype,
                                   int port)

Sets the port of a URI.

Parameters:

prototype - prototype URI that provides information other than the port

port - port for the new URI

Returns:

new URI built from the prototype URI and the given port

setQuery

public static java.net.URI setQuery(java.net.URI prototype,
                                    java.lang.String query)

Sets the query of a URI.

WARNING: If the supplied query parameter names and/or values contain '%' characters (for example because they are already Base64-encoded), then the approach of using URI instances to work with the URI/URL may not be appropriate. Per its documentation, the URI constructors always encode '%' characters, which can lead to cases of double-encoding. For an alternative way of manipulating URL's see URLBuilder.

Parameters:

prototype - prototype URI that provides information other than the query

query - query for the new URI

Returns:

new URI built from the prototype URI and the given query

setQuery

public static java.net.URI setQuery(java.net.URI prototype,
                                    java.util.List<Pair<java.lang.String,java.lang.String>> parameters)

Sets the query of a URI.

WARNING: If the supplied query parameter names and/or values contain '%' characters (for example because they are already Base64-encoded), then the approach of using URI instances to work with the URI/URL may not be appropriate. Per its documentation, the URI constructors always encode '%' characters, which can lead to cases of double-encoding. For an alternative way of manipulating URL's see URLBuilder.

Parameters:

prototype - prototype URI that provides information other than the query

parameters - query parameters for the new URI

Returns:

new URI built from the prototype URI and the given query

setScheme

public static java.net.URI setScheme(java.net.URI prototype,
                                     java.lang.String scheme)

Sets the scheme of a URI.

Parameters:

prototype - prototype URI that provides information other than the scheme

scheme - scheme for the new URI

Returns:

new URI built from the prototype URI and the given scheme

fileURIFromAbsolutePath

public static java.net.URI fileURIFromAbsolutePath(java.lang.String path)
                                            throws java.net.URISyntaxException

Create a file: URI from an absolute path, dealing with the Windows, non leading "/" issue.
Windows absolute paths have a habit of starting with a "DosDeviceName" (such as C:\absolute\path if we blindly convert that to a file URI by prepending "file://", then we end up with a URI which has "C:" as the network segment. So if we need to have an absolute file path based URI (JAAS is the example) we call this method which hides the hideous implementation

Parameters:

path - the absolute file path to convert

Returns:

a suitable URI

Throws:

java.net.URISyntaxException - if the URI contructor fails

buildQuery

public static java.lang.String buildQuery(java.util.List<Pair<java.lang.String,java.lang.String>> parameters)

Builds an RFC-3968 encoded URL query component from a collection of parameters.

Parameters:

parameters - collection of parameters from which to build the URL query component, may be null or empty

Returns:

RFC-3968 encoded URL query or null if the parameter collection was null or empty

getRawQueryStringParameter

@Nullable
public static java.lang.String getRawQueryStringParameter(@Nullable
                                                                    java.lang.String queryString,
                                                                    @Nullable
                                                                    java.lang.String paramName)

Get the first raw (i.e.RFC-3968 encoded) query string component with the specified parameter name. This method assumes the common query string format of one or more 'paramName=paramValue' pairs separate by '&'. The component will be returned as a string in the form 'paramName=paramValue' (minus the quotes).

Parameters:

queryString - the URL encoded HTTP URL query string

paramName - the URL decoded name of the parameter to find

Returns:

the found component, or null if query string or param name is null/empty or the parameter is not found

parseQueryString

public static java.util.List<Pair<java.lang.String,java.lang.String>> parseQueryString(java.lang.String queryString)

Parses a RFC-3968 encoded query string in to a set of name/value pairs. This method assumes the common query string format of one or more 'paramName=paramValue' pairs separate by '&'. Both parameter names and values will be URL decoded. Parameters without values will be represented in the returned map as a key associated with the value null.

Parameters:

queryString - URL encoded query string

Returns:

the parameters from the query string, never null

trimOrNullPath

public static java.lang.String trimOrNullPath(java.lang.String path)

Trims an RFC-3968 encoded URL path component. If the given path is null or empty then null is returned. If the given path ends with '?' then it is removed. If the given path ends with '#' then it is removed.

Parameters:

path - path to trim

Returns:

the trimmed path or null

trimOrNullQuery

public static java.lang.String trimOrNullQuery(java.lang.String query)

Trims an RFC-3968 encoded URL query component. If the given query is null or empty then null is returned. If the given query starts with '?' then it is removed. If the given query ends with '#' then it is removed.

Parameters:

query - query to trim

Returns:

the trimmed query or null

trimOrNullFragment

public static java.lang.String trimOrNullFragment(java.lang.String fragment)

Trims an RFC-3968 encoded URL fragment component. If the given fragment is null or empty then null is returned. If the given fragment starts with '#' then it is removed.

Parameters:

fragment - fragment to trim

Returns:

the trimmed fragment or null

doURLDecode

public static java.lang.String doURLDecode(java.lang.String value)

Perform URL decoding on the given string.

Parameters:

value - the string to decode

Returns:

the decoded string

doURLEncode

public static java.lang.String doURLEncode(java.lang.String value)

Perform URL encoding on the given string.

Parameters:

value - the string to encode

Returns:

the encoded string