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

Modifier and Type	Class and Description
static class	UriComponent.Type The URI component type.

Method Summary

Modifier and Type	Method and Description
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 javax.ws.rs.core.MultivaluedMap<String,String>	decodeMatrix(String pathSegment, boolean decode) Decode the matrix component of a URI path segment.
static List<javax.ws.rs.core.PathSegment>	decodePath(String path, boolean decode) Decode the path component of a URI as path segments.
static List<javax.ws.rs.core.PathSegment>	decodePath(URI u, boolean decode) Decode the path component of a URI as path segments.
static void	decodePathSegment(List<javax.ws.rs.core.PathSegment> segments, String segment, boolean decode) Decode the path segment and add it to the list of path segments.
static javax.ws.rs.core.MultivaluedMap<String,String>	decodeQuery(String q, boolean decode) Decode the query component of a URI.
static javax.ws.rs.core.MultivaluedMap<String,String>	decodeQuery(String q, boolean decodeNames, boolean decodeValues) Decode the query component of a URI.
static javax.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 javax.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 javax.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 javax.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<javax.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<javax.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<javax.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 javax.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.