Module io.inverno.mod.base

Package io.inverno.mod.base.net

Class URIs

java.lang.Object

io.inverno.mod.base.net.URIs

public final class URIs
extends Object

Utility methods for URIs manipulation.

A URI can be created fluently:

 // http://localhost/foo/bar/123
 URI uri = URIs.uri()
     .scheme("http")
     .host("localhost")
     .path("/foo/bar/123")
     .build();
 

A URI can be automatically normalized by enabling the URIs.Option.NORMALIZED option:

 // http://localhost/123
 URI uri = URIs.uri(URIs.Option.NORMALIZED)
     .scheme("http")
     .host("localhost")
     .path("/foo/../123")
     .build();
 

URI templates can be created by enabling the URIs.Option.PARAMETERIZED option and specifying parameters of the form {<name>[:<pattern>]} in the URI components:

 URIBuilder uriTemplate = URIs.uri(URIs.Option.PARAMETERIZED)
     .scheme("{scheme}")
     .host("localhost")
     .path("/static/{custom_path}");

 // https://localhost/static/resource1
 URI uri1 = uriTemplate.build("https", "resource1");

 // http://localhost/static/resource2
 URI uri2 = uriTemplate.build("http", "resource2");
 

URI matchers can be created by enabling the URIs.Option.PARAMETERIZED and/or URIs.Option.PATH_PATTERN options and specifying unnamed parameters of the form {[:<pattern>]} and/or path patterns using ?, * and ** in the URI components:

 URIBuilder uriBuilder = URIs.uri("/static/**" + "/*.png", URIs.Option.PARAMETERIZED, URIs.Option.PATH_PATTERN);
 URIPattern uriPattern = uriBuilder.buildPathPattern(false);
 
 // true
 uriPattern.matcher("/static/path/to/image.png").matches();
 
 // false
 uriPattern.matcher("/static/image.jpg").matches();
 

Since:

1.0

Author:

Jeremy Kuhn

See Also:

• URIBuilder

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	URIs.Option	Defines the options used to create a URI builder.
static enum	URIs.RequestTargetForm	Defines the forms supported when building a URI from a request-target as defined by RFC 7230 Section 5.3.

Constructor Summary

Constructors

Constructor	Description
URIs()

Method Summary

Modifier and Type	Method	Description
static String	encodeQuery(String query, Charset charset)	Percent encodes a query string as defined by RFC 3986 Section 2.1 escaping non-query characters as defined by RFC 3986 Section 3.4.
static String	encodeQueryParameter(String name, String value, Charset charset)	Percent encodes a query parameter as defined by RFC 3986 Section 2.1 escaping non-query characters as defined by RFC 3986 Section 3.4.
static String	encodeSegment(String component, Charset charset)	Percent encodes a path segment as defined by RFC 3986 Section 2.1 escaping non-segment characters (including slash) as defined by RFC 3986 Section 3.3.
static URIBuilder	uri(URIs.Option... options)	Creates a URI builder with the specified options and default charset.
static URIBuilder	uri(String requestTarget, boolean ignoreTrailingSlash, URIs.Option... options)	Creates a URI builder from the specified URIs.RequestTargetForm.PATH_QUERY_FRAGMENT request-target ignoring or not trailing slash with the specified options and default charset.
static URIBuilder	uri(String requestTarget, boolean ignoreTrailingSlash, Charset charset, URIs.Option... options)	Creates a URI builder from the specified URIs.RequestTargetForm.PATH_QUERY_FRAGMENT request-target ignoring or not trailing slash with the specified options and default charset.
static URIBuilder	uri(String requestTarget, URIs.Option... options)	Creates a URI builder from the specified URIs.RequestTargetForm.PATH_QUERY_FRAGMENT request-target ignoring trailing slash with the specified options and default charset.
static URIBuilder	uri(String requestTarget, URIs.RequestTargetForm requestTargetForm, boolean ignoreTrailingSlash, URIs.Option... options)	Creates a URI builder from the specified request-target of the specified form ignoring or not trailing slash with the specified options and default charset.
static URIBuilder	uri(String requestTarget, URIs.RequestTargetForm requestTargetForm, boolean ignoreTrailingSlash, Charset charset, URIs.Option... options)	Creates a URI builder from the specified URIs.RequestTargetForm.PATH_QUERY_FRAGMENT request-target ignoring or not trailing slash with the specified options and default charset.
static URIBuilder	uri(String requestTarget, URIs.RequestTargetForm requestTargetForm, URIs.Option... options)	Creates a URI builder from the specified request-target of the specified form ignoring trailing slash with the specified options and default charset.
static URIBuilder	uri(URI uri, boolean ignoreTrailingSlash, URIs.Option... options)	Creates a URI builder from the specified URI ignoring or not trailing slash with the specified options and default charset.
static URIBuilder	uri(URI uri, boolean ignoreTrailingSlash, Charset charset, URIs.Option... options)	Creates a URI builder from the specified path ignoring or not trailing slash with the specified options and default charset.
static URIBuilder	uri(URI uri, URIs.Option... options)	Creates a URI builder from the specified URI ignoring trailing slash with the specified options and default charset.

Methods inherited from class java.lang.Object

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

Constructor Details

URIs

public URIs()

Method Details

uri

public static URIBuilder uri(URIs.Option... options)

Creates a URI builder with the specified options and default charset.

Parameters:

options - a list of options

Returns:

a URI builder

uri

public static URIBuilder uri(String requestTarget,
 URIs.Option... options)
                      throws URIBuilderException

Creates a URI builder from the specified URIs.RequestTargetForm.PATH_QUERY_FRAGMENT request-target ignoring trailing slash with the specified options and default charset.

The request-target corresponds to the origin form as defined by RFC 7230 Section 5.3.1 with the addition of the fragment component, as such it may contain query and/or a fragment URI components.

The origin-form request is incompatible with URIs.Option.PATH_PATTERN option since query component delimiter ? is conflicting with path pattern character ?.

Note that the different URI components composing the specified request-target are decoded individually after parsing the initial parsing of the request-target.

Parameters:

requestTarget - an extended origin-form request-target

options - a list of options

Returns:

a URI builder

Throws:

URIBuilderException - if option URIs.Option.PATH_PATTERN is specified which is incompatible with origin-form request

uri

public static URIBuilder uri(String requestTarget,
 URIs.RequestTargetForm requestTargetForm,
 URIs.Option... options)
                      throws URIBuilderException

Creates a URI builder from the specified request-target of the specified form ignoring trailing slash with the specified options and default charset.

The request-target must be of the specified form as defined by RFC 7230 Section 5.3.

The origin-form request is incompatible with URIs.Option.PATH_PATTERN option since query component delimiter ? is conflicting with path pattern character ?.

Note that the different URI components composing the specified request-target are decoded individually after parsing the initial parsing of the request-target.

Parameters:

requestTarget - a request-target

requestTargetForm - the form of the request-target

options - a list of options

Returns:

a URI builder

Throws:

URIBuilderException - if option URIs.Option.PATH_PATTERN is specified which is incompatible with origin-form request

uri

public static URIBuilder uri(String requestTarget,
 boolean ignoreTrailingSlash,
 URIs.Option... options)
                      throws URIBuilderException

Creates a URI builder from the specified URIs.RequestTargetForm.PATH_QUERY_FRAGMENT request-target ignoring or not trailing slash with the specified options and default charset.

The request-target corresponds to the origin form as defined by RFC 7230 Section 5.3.1 with the addition of the fragment component, as such it may contain query and/or a fragment URI components.

The origin-form request is incompatible with URIs.Option.PATH_PATTERN option since query component delimiter ? is conflicting with path pattern character ?.

Note that the different URI components composing the specified request-target are decoded individually after parsing the initial parsing of the request-target.

Parameters:

requestTarget - an extended origin-form request-target

ignoreTrailingSlash - true to ignore trailing slash in the path

options - a list of options

Returns:

a URI builder

Throws:

URIBuilderException - if option URIs.Option.PATH_PATTERN is specified which is incompatible with origin-form request

uri

public static URIBuilder uri(String requestTarget,
 URIs.RequestTargetForm requestTargetForm,
 boolean ignoreTrailingSlash,
 URIs.Option... options)
                      throws URIBuilderException

Creates a URI builder from the specified request-target of the specified form ignoring or not trailing slash with the specified options and default charset.

The request-target must be of the specified form as defined by RFC 7230 Section 5.3.

The origin-form request is incompatible with URIs.Option.PATH_PATTERN option since query component delimiter ? is conflicting with path pattern character ?.

Note that the different URI components composing the specified request-target are decoded individually after parsing the initial parsing of the request-target.

Parameters:

requestTarget - a request-target

requestTargetForm - the form of the request-target

ignoreTrailingSlash - true to ignore trailing slash in the path

options - a list of options

Returns:

a URI builder

Throws:

URIBuilderException - if option URIs.Option.PATH_PATTERN is specified which is incompatible with origin-form request

uri

public static URIBuilder uri(String requestTarget,
 boolean ignoreTrailingSlash,
 Charset charset,
 URIs.Option... options)
                      throws URIBuilderException

Creates a URI builder from the specified URIs.RequestTargetForm.PATH_QUERY_FRAGMENT request-target ignoring or not trailing slash with the specified options and default charset.

The request-target corresponds to the origin form as defined by RFC 7230 Section 5.3.1 with the addition of the fragment component, as such it may contain query and/or a fragment URI components.

The origin-form request is incompatible with URIs.Option.PATH_PATTERN option since query component delimiter ? is conflicting with path pattern character ?.

Note that the different URI components composing the specified request-target are decoded individually after parsing the initial parsing of the request-target.

Parameters:

requestTarget - an extended origin-form request-target

ignoreTrailingSlash - true to ignore trailing slash in the path

charset - a charset

options - a list of options

Returns:

a URI builder

Throws:

URIBuilderException - if option URIs.Option.PATH_PATTERN is specified which is incompatible with origin-form request

uri

public static URIBuilder uri(String requestTarget,
 URIs.RequestTargetForm requestTargetForm,
 boolean ignoreTrailingSlash,
 Charset charset,
 URIs.Option... options)
                      throws URIBuilderException

Creates a URI builder from the specified URIs.RequestTargetForm.PATH_QUERY_FRAGMENT request-target ignoring or not trailing slash with the specified options and default charset.

The request-target must be of the specified form as defined by RFC 7230 Section 5.3.

The origin-form request is incompatible with URIs.Option.PATH_PATTERN option since query component delimiter ? is conflicting with path pattern character ?.

Note that the different URI components composing the specified request-target are decoded individually after parsing the initial parsing of the request-target.

Parameters:

requestTarget - a request-target

requestTargetForm - the form of the request-target

ignoreTrailingSlash - true to ignore trailing slash in the path

charset - a charset

options - a list of options

Returns:

a URI builder

Throws:

URIBuilderException - if option URIs.Option.PATH_PATTERN is specified which is incompatible with origin-form request

uri

public static URIBuilder uri(URI uri,
 URIs.Option... options)

Creates a URI builder from the specified URI ignoring trailing slash with the specified options and default charset.

Parameters:

uri - a URI

options - a list of options

Returns:

a URI builder

uri

public static URIBuilder uri(URI uri,
 boolean ignoreTrailingSlash,
 URIs.Option... options)

Creates a URI builder from the specified URI ignoring or not trailing slash with the specified options and default charset.

Parameters:

uri - a URI

ignoreTrailingSlash - true to ignore trailing slash in the path

options - a list of options

Returns:

a URI builder

uri

public static URIBuilder uri(URI uri,
 boolean ignoreTrailingSlash,
 Charset charset,
 URIs.Option... options)

Creates a URI builder from the specified path ignoring or not trailing slash with the specified options and default charset.

Parameters:

uri - a URI

ignoreTrailingSlash - true to ignore trailing slash in the path

charset - a charset

options - a list of options

Returns:

a URI builder

encodeQueryParameter

public static String encodeQueryParameter(String name,
 String value,
 Charset charset)

Percent encodes a query parameter as defined by RFC 3986 Section 2.1 escaping non-query characters as defined by RFC 3986 Section 3.4.

Parameters:

name - the parameter name to encode

value - the parameter value to encode

charset - a charset

Returns:

an encoded query parameter

encodeQuery

public static String encodeQuery(String query,
 Charset charset)

Percent encodes a query string as defined by RFC 3986 Section 2.1 escaping non-query characters as defined by RFC 3986 Section 3.4.

Parameters:

query - the query to encode

charset - a charset

Returns:

an encoded query

encodeSegment

public static String encodeSegment(String component,
 Charset charset)

Percent encodes a path segment as defined by RFC 3986 Section 2.1 escaping non-segment characters (including slash) as defined by RFC 3986 Section 3.3.

Parameters:

component - the path segment to encode

charset - a charset

Returns:

an encoded path segment