org.glassfish.jersey.uri

## Class UriComponent

- java.lang.Object
- - org.glassfish.jersey.uri.UriComponent

    public class UriComponent
    extends Object

Utility class for validating, encoding and decoding components of a URI.

Author:
  Paul Sandoz, Marek Potociar

### Nested Class Summary

Nested Classes
`static class` `UriComponent.Type` The URI component type.

### Method Summary

All Methods Static Methods Concrete Methods
`static String` `contextualEncode(String s, UriComponent.Type t)` Contextually encodes the characters of string that are either non-ASCII characters or are ASCII characters that must be percent-encoded using the UTF-8 encoding.
`static String` `contextualEncode(String s, UriComponent.Type t, boolean template)` Contextually encodes the characters of string that are either non-ASCII characters or are ASCII characters that must be percent-encoded using the UTF-8 encoding.
`static String` `decode(String s, UriComponent.Type t)` Decodes characters of a string that are percent-encoded octets using UTF-8 decoding (if needed).
`static jakarta.ws.rs.core.MultivaluedMap<String,String>` `decodeMatrix(String pathSegment, boolean decode)` Decode the matrix component of a URI path segment.
`static List<jakarta.ws.rs.core.PathSegment>` `decodePath(String path, boolean decode)` Decode the path component of a URI as path segments.
`static List<jakarta.ws.rs.core.PathSegment>` `decodePath(URI u, boolean decode)` Decode the path component of a URI as path segments.
`static void` `decodePathSegment(List<jakarta.ws.rs.core.PathSegment> segments, String segment, boolean decode)` Decode the path segment and add it to the list of path segments.
`static jakarta.ws.rs.core.MultivaluedMap<String,String>` `decodeQuery(String q, boolean decode)` Decode the query component of a URI.
`static jakarta.ws.rs.core.MultivaluedMap<String,String>` `decodeQuery(String q, boolean decodeNames, boolean decodeValues)` Decode the query component of a URI.
`static jakarta.ws.rs.core.MultivaluedMap<String,String>` `decodeQuery(URI u, boolean decode)` Decode the query component of a URI.
`static String` `encode(String s, UriComponent.Type t)` Encodes the characters of string that are either non-ASCII characters or are ASCII characters that must be percent-encoded using the UTF-8 encoding.
`static String` `encode(String s, UriComponent.Type t, boolean template)` Encodes the characters of string that are either non-ASCII characters or are ASCII characters that must be percent-encoded using the UTF-8 encoding.
`static String` `encodeTemplateNames(String s)` Encodes a string with template parameters names present, specifically the characters '{' and '}' will be percent-encoded.
`static String` `fullRelativeUri(URI uri)` Return the `Request-Uri` representation as defined by HTTP spec.
`static boolean` `isHexCharacter(char c)` Checks whether the character `c` is hexadecimal character.
`static boolean` `valid(String s, UriComponent.Type t)` Validates the legal characters of a percent-encoded string that represents a URI component type.
`static boolean` `valid(String s, UriComponent.Type t, boolean template)` Validates the legal characters of a percent-encoded string that represents a URI component type.
`static void` `validate(String s, UriComponent.Type t)` Validates the legal characters of a percent-encoded string that represents a URI component type.
`static void` `validate(String s, UriComponent.Type t, boolean template)` Validates the legal characters of a percent-encoded string that represents a URI component type.

### Methods inherited from class java.lang.Object

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

### Method Detail

#### validate

    public static void validate(String s,
                                UriComponent.Type t)

Validates the legal characters of a percent-encoded string that represents a URI component type.

Parameters:
  `s` - the encoded string.
  `t` - the URI component type identifying the legal characters.
Throws:
  `IllegalArgumentException` - if the encoded string contains illegal characters.

#### validate

    public static void validate(String s,
                                UriComponent.Type t,
                                boolean template)

Validates the legal characters of a percent-encoded string that represents a URI component type.

Parameters:
  `s` - the encoded string.
  `t` - the URI component type identifying the legal characters.
  `template` - true if the encoded string contains URI template variables
Throws:
  `IllegalArgumentException` - if the encoded string contains illegal characters.

#### valid

    public static boolean valid(String s,
                                UriComponent.Type t)

Validates the legal characters of a percent-encoded string that represents a URI component type.

Parameters:
  `s` - the encoded string.
  `t` - the URI component type identifying the legal characters.
Returns:
  true if the encoded string is valid, otherwise false.

#### valid

    public static boolean valid(String s,
                                UriComponent.Type t,
                                boolean template)

Validates the legal characters of a percent-encoded string that represents a URI component type.

Parameters:
  `s` - the encoded string.
  `t` - the URI component type identifying the legal characters.
  `template` - true if the encoded string contains URI template variables
Returns:
  true if the encoded string is valid, otherwise false.

#### contextualEncode

    public static String contextualEncode(String s,
                                          UriComponent.Type t)

Contextually encodes the characters of string that are either non-ASCII characters or are ASCII characters that must be percent-encoded using the UTF-8 encoding. Percent-encoded characters will be recognized and not double encoded.

Parameters:
  `s` - the string to be encoded.
  `t` - the URI component type identifying the ASCII characters that must be percent-encoded.
Returns:
  the encoded string.

#### contextualEncode

    public static String contextualEncode(String s,
                                          UriComponent.Type t,
                                          boolean template)

Contextually encodes the characters of string that are either non-ASCII characters or are ASCII characters that must be percent-encoded using the UTF-8 encoding. Percent-encoded characters will be recognized and not double encoded.

Parameters:
  `s` - the string to be encoded.
  `t` - the URI component type identifying the ASCII characters that must be percent-encoded.
  `template` - true if the encoded string contains URI template variables
Returns:
  the encoded string.

#### encode

    public static String encode(String s,
                                UriComponent.Type t)

Encodes the characters of string that are either non-ASCII characters or are ASCII characters that must be percent-encoded using the UTF-8 encoding.

Parameters:
  `s` - the string to be encoded.
  `t` - the URI component type identifying the ASCII characters that must be percent-encoded.
Returns:
  the encoded string.

#### encode

    public static String encode(String s,
                                UriComponent.Type t,
                                boolean template)

Encodes the characters of string that are either non-ASCII characters or are ASCII characters that must be percent-encoded using the UTF-8 encoding.

Parameters:
  `s` - the string to be encoded.
  `t` - the URI component type identifying the ASCII characters that must be percent-encoded.
  `template` - true if the encoded string contains URI template variables
Returns:
  the encoded string.

#### encodeTemplateNames

    public static String encodeTemplateNames(String s)

Encodes a string with template parameters names present, specifically the characters '{' and '}' will be percent-encoded.

Parameters:
  `s` - the string with zero or more template parameters names
Returns:
  the string with encoded template parameters names.

#### decode

    public static String decode(String s,
                                UriComponent.Type t)

Decodes characters of a string that are percent-encoded octets using UTF-8 decoding (if needed).

It is assumed that the string is valid according to an (unspecified) URI component type. If a sequence of contiguous percent-encoded octets is not a valid UTF-8 character then the octets are replaced with '�'.

If the URI component is of type HOST then any "%" found between "[]" is left alone. It is an IPv6 literal with a scope_id.

If the URI component is of type QUERY_PARAM then any "+" is decoded as as ' '.

Parameters:
  `s` - the string to be decoded.
  `t` - the URI component type, may be null.
Returns:
  the decoded string.
Throws:
  `IllegalArgumentException` - if a malformed percent-encoded octet is detected

#### decodeQuery

    public static jakarta.ws.rs.core.MultivaluedMap<String,String> decodeQuery(URI u,
                                                                               boolean decode)

Decode the query component of a URI.

Query parameter names in the returned map are always decoded. Decoding of query parameter values can be controlled using the `decode` parameter flag.

Parameters:
  `u` - the URI.
  `decode` - `true` if the returned query parameter values of the query component should be in decoded form.
Returns:
  the multivalued map of query parameters.

#### decodeQuery

    public static jakarta.ws.rs.core.MultivaluedMap<String,String> decodeQuery(String q,
                                                                               boolean decode)

Decode the query component of a URI.

Query parameter names in the returned map are always decoded. Decoding of query parameter values can be controlled using the `decode` parameter flag.

Parameters:
  `q` - the query component in encoded form.
  `decode` - `true` if the returned query parameter values of the query component should be in decoded form.
Returns:
  the multivalued map of query parameters.

#### decodeQuery

    public static jakarta.ws.rs.core.MultivaluedMap<String,String> decodeQuery(String q,
                                                                               boolean decodeNames,
                                                                               boolean decodeValues)

Decode the query component of a URI.

Decoding of query parameter names and values can be controlled using the `decodeNames` and `decodeValues` parameter flags.

Parameters:
  `q` - the query component in encoded form.
  `decodeNames` - `true` if the returned query parameter names of the query component should be in decoded form.
  `decodeValues` - `true` if the returned query parameter values of the query component should be in decoded form.
Returns:
  the multivalued map of query parameters.

#### decodePath

    public static List<jakarta.ws.rs.core.PathSegment> decodePath(URI u,
                                                                  boolean decode)

Decode the path component of a URI as path segments.

Parameters:
  `u` - the URI. If the path component is an absolute path component then the leading '/' is ignored and is not considered a delimiator of a path segment.
  `decode` - true if the path segments of the path component should be in decoded form.
Returns:
  the list of path segments.

#### decodePath

    public static List<jakarta.ws.rs.core.PathSegment> decodePath(String path,
                                                                  boolean decode)

Decode the path component of a URI as path segments.

Any '/' character in the path is considered to be a deliminator between two path segments. Thus if the path is '/' then the path segment list will contain two empty path segments. If the path is "//" then the path segment list will contain three empty path segments. If the path is "/a/" the path segment list will consist of the following path segments in order: "", "a" and "".

Parameters:
  `path` - the path component in encoded form.
  `decode` - true if the path segments of the path component should be in decoded form.
Returns:
  the list of path segments.

#### decodePathSegment

    public static void decodePathSegment(List<jakarta.ws.rs.core.PathSegment> segments,
                                         String segment,
                                         boolean decode)

Decode the path segment and add it to the list of path segments.

Parameters:
  `segments` - mutable list of path segments.
  `segment` - path segment to be decoded.
  `decode` - `true` if the path segment should be in a decoded form.

#### decodeMatrix

    public static jakarta.ws.rs.core.MultivaluedMap<String,String> decodeMatrix(String pathSegment,
                                                                                boolean decode)

Decode the matrix component of a URI path segment.

Parameters:
  `pathSegment` - the path segment component in encoded form.
  `decode` - true if the matrix parameters of the path segment component should be in decoded form.
Returns:
  the multivalued map of matrix parameters.

#### isHexCharacter

    public static boolean isHexCharacter(char c)

Checks whether the character `c` is hexadecimal character.

Parameters:
  `c` - Any character
Returns:
  The is `c` is a hexadecimal character (e.g. 0, 5, a, A, f, ...)

#### fullRelativeUri

    public static String fullRelativeUri(URI uri)

Return the `Request-Uri` representation as defined by HTTP spec. For example:

    <Method> <Request-URI> HTTP/<Version> (e.g. GET /auth;foo=bar/hello?foo=bar HTTP/1.1)

Parameters:
  `uri` - uri to obtain `Request-Uri` from.
Returns:
  `Request-Uri` representation or `null` if `uri` is not provided.