Package net.shibboleth.shared.net

# Class URISupport

java.lang.Object
net.shibboleth.shared.net.URISupport

public final class URISupport extends Object
Helper methods for building `URI`s and parsing some HTTP URL information.

## Constructor Summary

Constructors
Modifier
Constructor
Description
`private`
`URISupport()`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`static String`
`buildQuery(List<Pair<String,String>> parameters)`
Builds an RFC-3968 encoded URL query component from a collection of parameters.
`static Map<String,String>`
`buildQueryMap(List<Pair<String,String>> parameters)`
Builds a map from a collection of parameters.
`static Map<String,List<String>>`
`buildQueryMultiMap(List<Pair<String,String>> parameters)`
Builds a map from a collection of parameters.
`static String`
`doURLDecode(String value)`
Perform URL decoding on the given string using UTF-8 as the encoding.
`static String`
`doURLDecode(String value, Charset charset)`
Perform URL decoding on the given string.
`static String`
`doURLEncode(String value)`
Deprecated.
`static URI`
`fileURIFromAbsolutePath(String path)`
Create a file: URI from an absolute path, dealing with the Windows, non leading "/" issue.
`static String`
`getRawQueryStringParameter(String queryString, String paramName)`
Get the first raw (i.e.RFC-3968 encoded) query string component with the specified parameter name.
`static List<Pair<String,String>>`
`getRawQueryStringParameters(String queryString, String paramName)`
Get all raw (i.e.RFC-3968 encoded) query string components with the specified parameter name.
`static List<Pair<String,String>>`
`parseQueryString(String queryString)`
Parses a RFC-3968 encoded query string in to a set of name/value pairs.
`static List<Pair<String,String>>`
`parseQueryString(String queryString, boolean decodeName, boolean decodeValue)`
Same as `parseQueryString(String, boolean, boolean, Charset)` with the final parameter set to `StandardCharsets.UTF_8`.
`static List<Pair<String,String>>`
`parseQueryString(String queryString, boolean decodeName, boolean decodeValue, Charset charset)`
Parses a RFC-3968 encoded query string in to a set of name/value pairs.
`static URI`
`setFragment(URI prototype, String fragment)`
Sets the fragment of a URI.
`static URI`
`setHost(URI prototype, String host)`
Sets the host of a URI.
`static URI`
`setPath(URI prototype, String path)`
Sets the path of a URI.
`static URI`
`setPort(URI prototype, int port)`
Sets the port of a URI.
`static URI`
`setQuery(URI prototype, String query)`
Sets the query of a URI.
`static URI`
`setQuery(URI prototype, List<Pair<String,String>> parameters)`
Sets the query of a URI.
`static URI`
`setScheme(URI prototype, String scheme)`
Sets the scheme of a URI.
`static String`
`trimOrNullFragment(String fragment)`
Trims an RFC-3968 encoded URL fragment component.
`static String`
`trimOrNullPath(String path)`
Trims an RFC-3968 encoded URL path component.
`static String`
`trimOrNullQuery(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 Details

### URISupport

private URISupport()
Constructor.

## Method Details

### setFragment

@Nonnull public static URI setFragment(@Nonnull URI prototype, @Nullable 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

@Nonnull public static URI setHost(@Nonnull URI prototype, @Nullable 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

@Nonnull public static URI setPath(@Nonnull URI prototype, @Nullable 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

@Nonnull public static URI setPort(@Nonnull 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

@Nonnull public static URI setQuery(@Nonnull URI prototype, @Nullable 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

@Nonnull public static URI setQuery(@Nonnull URI prototype, @Nullable List<Pair<String,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`.

Note that while the input may not contain null elements, its actual elements may themselves contain null values (the second half of the pair).

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

@Nonnull public static URI setScheme(@Nonnull URI prototype, @Nullable 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

@Nonnull public static URI fileURIFromAbsolutePath(@Nonnull String path) throws 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:
  `URISyntaxException` - if the URI contructor fails

### buildQuery

@Nullable public static String buildQuery(@Nullable List<Pair<String,String>> parameters)
Builds an RFC-3968 encoded URL query component from a collection of parameters.

Note that while the input may not contain null elements, its actual elements may themselves contain null values (the second half of the pair).

Parameters:
  `parameters` - collection of parameters from which to build the URL query component
Returns:
  RFC-3968 encoded URL query or null if the parameter collection was null or empty

### buildQueryMap

@Nonnull @NullableElements @Unmodifiable @NotLive public static Map<String,String> buildQueryMap(@Nullable @NullableElements List<Pair<String,String>> parameters)
Builds a map from a collection of parameters.

Note that this method only properly supports parameters which have a single value. If support for parameters with multiple values is required, instead use `buildQueryMultiMap(List)`.

Parameters:
  `parameters` - collection of parameters from which to build the corresponding, may be null or empty
Returns:
  a non-null map of query parameter name-> value. Keys will be non-null. Values may be null.

### buildQueryMultiMap

@Nonnull @NullableElements @Unmodifiable @NotLive public static Map<String,List<String>> buildQueryMultiMap(@Nullable @NullableElements List<Pair<String,String>> parameters)
Builds a map from a collection of parameters.

Parameters:
  `parameters` - collection of parameters from which to build the corresponding, may be null or empty
Returns:
  a non-null map of query parameter name-> value. Keys will be non-null. List values will be non-null, but may contain null elements

### getRawQueryStringParameter

@Nullable public static String getRawQueryStringParameter(@Nullable String queryString, @Nullable 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 separated 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

### getRawQueryStringParameters

@Nonnull @Live public static List<Pair<String,String>> getRawQueryStringParameters(@Nullable String queryString, @Nullable String paramName)
Get all raw (i.e.RFC-3968 encoded) query string components with the specified parameter name. This method assumes the common query string format of one or more 'paramName=paramValue' pairs separated by '&'. Parameters without values will be represented in the returned map as a key associated with the value `null`. The parameter name match will be performed using the URL decoded forms of both the specified `paramName` and the candidate query string value.

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

@Nonnull @Live public static List<Pair<String,String>> parseQueryString(@Nullable 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

### parseQueryString

@Nonnull @Live public static List<Pair<String,String>> parseQueryString(@Nullable String queryString, boolean decodeName, boolean decodeValue, @Nonnull Charset charset)
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 '&'. URL decoding of parameter names and values is determined by the relevant arguments. Parameters without values will be represented in the returned map as a key associated with the value `null`.

Parameters:
  `queryString` - URL encoded query string
  `decodeName` - whether the parameter names should be URL decoded in the returned list
  `decodeValue` - whether the parameter values should be URL decoded in the returned list
  `charset` - character encoding
Returns:
  the parameters from the query string, never null
Since:
  9.2.0

### parseQueryString

@Nonnull @Live public static List<Pair<String,String>> parseQueryString(@Nullable String queryString, boolean decodeName, boolean decodeValue)
Same as `parseQueryString(String, boolean, boolean, Charset)` with the final parameter set to `StandardCharsets.UTF_8`.

Parameters:
  `queryString` - URL encoded query string
  `decodeName` - whether the parameter names should be URL decoded in the returned list
  `decodeValue` - whether the parameter values should be URL decoded in the returned list
Returns:
  the parameters from the query string, never null

### trimOrNullPath

@Nullable public static String trimOrNullPath(@Nullable 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

@Nullable public static String trimOrNullQuery(@Nullable 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

@Nullable public static String trimOrNullFragment(@Nullable 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

@Nullable public static String doURLDecode(@Nullable String value, @Nonnull Charset charset)
Perform URL decoding on the given string.

Parameters:
  `value` - the string to decode
  `charset` - character encoding to apply
Returns:
  the decoded string
Since:
  9.2.0

### doURLDecode

@Nullable public static String doURLDecode(@Nullable String value)
Perform URL decoding on the given string using UTF-8 as the encoding.

Parameters:
  `value` - the string to decode
Returns:
  the decoded string

### doURLEncode

@Deprecated @Nullable public static String doURLEncode(@Nullable String value)
Deprecated.
Perform URL encoding on the given string appropriate for form or query string parameters.

This method is not appropriate for the encoding of data for other parts of a URL such as a path or fragment.

Consider using Guava's UrlEscapers class for any future uses for this functionality.

Parameters:
  `value` - the string to encode
Returns:
  the encoded string