Module io.inverno.mod.base
Package io.inverno.mod.base.net

Interface URIBuilder

All Superinterfaces:
Cloneable
public interface URIBuilder extends Cloneable

A URI builder is used for creating URIs as defined by RFC 3986.

The URI components provided to the builder can be parameterized with parameters of the form {<name>[:<pattern>]} when the component allows it. It allows to create URI templates used to generate contextual URIs or create URI patterns to match particular URIs.

The following is a complete example of parameterized URI:


 {scheme}://{userinfo}@{host}:{port}/a/{segment}?parameter={parameter}#{fragment}
Since:
1.0
Author:
Jeremy Kuhn
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    default URI
    build(Object... values)
    Builds the URI from the builder's URI components after replacing the parameters with the string representation of the specified values escaping slash in the path segment components.
    default URI
    build(List<Object> values)
    Builds the URI from the builder's URI components after replacing the parameters with the string representation of the specified values escaping slash in the path segment components.
    URI
    build(List<Object> values, boolean escapeSlash)
    Builds the URI from the builder's URI components after replacing the parameters with the string representation of the specified values escaping or not slash in the path segment components.
    default URI
    build(Map<String,?> values)
    Builds the URI from the builder's URI components after replacing the parameters with the string representation of the specified values.
    URI
    build(Map<String,?> values, boolean escapeSlash)
    Builds the URI from the builder's URI components after replacing the parameters with the string representation of the specified values escaping or not slash in the path segment components.
    default String
    buildPath(Object... values)
    Builds the path component string from the builder's URI path segment components after replacing the parameters with the string representation of the specified values escaping slash in path segment components.
    default String
    buildPath(List<Object> values)
    Builds the path component string from the builder's URI path segment components after replacing the parameters with the string representation of the specified values escaping slash in path segment components.
    String
    buildPath(List<Object> values, boolean escapeSlash)
    Builds the path component string from the builder's URI path segment components after replacing the parameters with the string representation of the specified values escaping or not slash in the path segment components.
    String
    buildPath(Map<String,?> values)
    Builds the path component string from the builder's URI path segment components after replacing the parameters with the string representation of the specified values escaping slash in path segment components.
    String
    buildPath(Map<String,?> values, boolean escapeSlash)
    Builds the path component string from the builder's URI path segment components after replacing the parameters with the string representation of the specified values escaping or not slash in the path segment components.
    default URIPattern
    buildPathPattern()
    Builds a URI pattern to exactly match builder's URI path component.
    URIPattern
    buildPathPattern(boolean matchTrailingSlash)
    Builds a URI pattern to match builder's URI path component including trailing slash or not.
    default URIPattern
    buildPattern()
    Builds a URI pattern to exactly match builder's URI.
    URIPattern
    buildPattern(boolean matchTrailingSlash)
    Builds a URI pattern to match builder's URI including trailing slash or not.
    default String
    buildQuery(Object... values)
    Builds the query component string from the builder's URI query parameter components after replacing the parameters with the string representation of the specified values.
    String
    buildQuery(List<Object> values)
    Builds the query component string from the builder's URI query parameter components after replacing the parameters with the string representation of the specified values.
    String
    buildQuery(Map<String,?> values)
    Builds the query component string from the builder's URI query parameter components after replacing the parameters with the string representation of the specified values.
    String
    buildRawPath()
    Builds the path component raw string from the builder's path segment components.
    String
    buildRawQuery()
    Builds the query component raw string from the builder's query parameter components.
    String
    buildRawString()
    Builds the raw string representation of the URI from the builder's URI components.
    default String
    buildString(Object... values)
    Builds the string representation of the URI from the builder's URI components after replacing the parameters with the string representation of the specified values escaping slash in path segment components.
    default String
    buildString(List<Object> values)
    Builds the string representation of the URI from the builder's URI components after replacing the parameters with the string representation of the specified values escaping slash in path segment components.
    String
    buildString(List<Object> values, boolean escapeSlash)
    Builds the string representation of the URI from the builder's URI components after replacing the parameters with the string representation of the specified values escaping or not slash in the path segment components.
    default String
    buildString(Map<String,?> values)
    Builds the string representation of the URI from the builder's URI components after replacing the parameters with the string representation of the specified values escaping slash in path segment components.
    String
    buildString(Map<String,?> values, boolean escapeSlash)
    Builds the string representation of the URI from the builder's URI components after replacing the parameters with the string representation of the specified values escaping or not slash in the path segment components.
    URIBuilder
    clearPath()
    Clears the path component.
    URIBuilder
    clearQuery()
    Clears the query component.
    URIBuilder
    clone()
    Clones the URI builder.
    URIBuilder
    fragment(String fragment)
    Sets the fragment component as defined by RFC 3986 Section 3.5.
    List<String>
    getParameterNames()
    Returns the list of parameters specified in all builder's URI components.
    List<String>
    getPathParameterNames()
    Returns the list of parameters specified in the builder's path component.
    default Map<String,List<String>>
    getQueryParameters(Object... values)
    Returns a map containing the query parameters after replacing the parameters with the string representation of the specified values.
    Map<String,List<String>>
    getQueryParameters(List<Object> values)
    Returns a map containing the query parameters after replacing the parameters with the string representation of the specified values.
    Map<String,List<String>>
    getQueryParameters(Map<String,?> values)
    Returns a map containing the query parameters after replacing the parameters with the string representation of the specified values.
    Map<String,List<String>>
    getRawQueryParameters()
    Returns a map containing the raw query parameters.
    URIBuilder
    host(String host)
    Sets the host component as defined by RFC 3986 Section 3.2.2.
    default URIBuilder
    path(String path)
    Appends the specified path as defined by RFC 3986 Section 3.3 ignoring the trailing slash
    URIBuilder
    path(String path, boolean ignoreTrailingSlash)
    Appends the specified path as defined by RFC 3986 Section 3.3 ignoring or not the trailing slash.
    URIBuilder
    port(Integer port)
    Sets the port component as defined by RFC 3986 Section 3.2.3.
    URIBuilder
    port(String port)
    Sets the port component as defined by RFC 3986 Section 3.2.3.
    URIBuilder
    query(String value)
    Sets the query component as defined by RFC 3986 Section 3.4.
    URIBuilder
    queryParameter(String name, String value)
    Appends a query parameter component with specified name and value as defined by RFC 3986 Section 3.4.
    URIBuilder
    scheme(String scheme)
    Sets the scheme component as defined by RFC 3986 Section 3.1.
    URIBuilder
    segment(String segment)
    Appends the specified path segment as defined by RFC 3986 Section 3.3
    URIBuilder
    userInfo(String userInfo)
    Sets the user information component as defined by RFC 3986 Section 3.2.1.

  • Method Details

    • scheme

      URIBuilder scheme(String scheme)

      Sets the scheme component as defined by RFC 3986 Section 3.1.

      Parameters:
      scheme - the scheme to set
      Returns:
      the URI builder

    • userInfo

      URIBuilder userInfo(String userInfo)

      Sets the user information component as defined by RFC 3986 Section 3.2.1.

      Parameters:
      userInfo - the user information to set
      Returns:
      the URI builder

    • host

      URIBuilder host(String host)

      Sets the host component as defined by RFC 3986 Section 3.2.2.

      Parameters:
      host - the host to set
      Returns:
      the URI builder

    • port

      URIBuilder port(Integer port)

      Sets the port component as defined by RFC 3986 Section 3.2.3.

      Parameters:
      port - the port to set
      Returns:
      the URI builder

    • port

      URIBuilder port(String port)

      Sets the port component as defined by RFC 3986 Section 3.2.3.

      Parameters:
      port - the port to set
      Returns:
      the URI builder

    • path

      default URIBuilder path(String path)

      Appends the specified path as defined by RFC 3986 Section 3.3 ignoring the trailing slash

      Parameters:
      path - the path to append
      Returns:
      the URI builder

    • path

      URIBuilder path(String path, boolean ignoreTrailingSlash)

      Appends the specified path as defined by RFC 3986 Section 3.3 ignoring or not the trailing slash.

      Parameters:
      path - the path to append
      ignoreTrailingSlash - true to ignore the trailing slash
      Returns:
      the URI builder

    • segment

      URIBuilder segment(String segment)

      Appends the specified path segment as defined by RFC 3986 Section 3.3

      Parameters:
      segment - the path segment to append
      Returns:
      the URI builder

    • clearPath

      URIBuilder clearPath()

      Clears the path component.

      Returns:
      the URI builder

    • query

      URIBuilder query(String value)

      Sets the query component as defined by RFC 3986 Section 3.4.

      This method basically replaces previous query component value with the specified value removing query parameters if any. Implementation does not extract query parameters from the specified value which remains opaque. If you wish to provide query parameters you should use queryParameter(String, String) instead.

      Parameters:
      value - the query value
      Returns:
      the URI builder

    • queryParameter

      URIBuilder queryParameter(String name, String value)

      Appends a query parameter component with specified name and value as defined by RFC 3986 Section 3.4.

      Parameters:
      name - the query parameter name
      value - the query parameter value
      Returns:
      the URI builder

    • clearQuery

      URIBuilder clearQuery()

      Clears the query component.

      Returns:
      the URI builder

    • fragment

      URIBuilder fragment(String fragment)

      Sets the fragment component as defined by RFC 3986 Section 3.5.

      Parameters:
      fragment - the fragment to set
      Returns:
      the URI builder

    • getParameterNames

      List<String> getParameterNames()

      Returns the list of parameters specified in all builder's URI components.

      Returns:
      a list of parameter names

    • getPathParameterNames

      List<String> getPathParameterNames()

      Returns the list of parameters specified in the builder's path component.

      Returns:
      a list of parameter names

    • getQueryParameters

      default Map<String,List<String>> getQueryParameters(Object... values) throws URIBuilderException

      Returns a map containing the query parameters after replacing the parameters with the string representation of the specified values.

      Parameters:
      values - an array of values to replace the components parameters
      Returns:
      a map of query parameters grouped by name
      Throws:
      URIBuilderException - if there was an error building the query parameters

    • getQueryParameters

      Map<String,List<String>> getQueryParameters(List<Object> values) throws URIBuilderException

      Returns a map containing the query parameters after replacing the parameters with the string representation of the specified values.

      Parameters:
      values - a list of values to replace the components parameters
      Returns:
      a map of query parameters grouped by name
      Throws:
      URIBuilderException - if there was an error building the query parameters

    • getQueryParameters

      Map<String,List<String>> getQueryParameters(Map<String,?> values) throws URIBuilderException

      Returns a map containing the query parameters after replacing the parameters with the string representation of the specified values.

      Parameters:
      values - a map of values to replace the components parameters
      Returns:
      a map of query parameters grouped by name
      Throws:
      URIBuilderException - if there was an error building the query parameters

    • getRawQueryParameters

      Map<String,List<String>> getRawQueryParameters() throws URIBuilderException

      Returns a map containing the raw query parameters.

      Returns:
      a map of query parameters grouped by name
      Throws:
      URIBuilderException - if there was an error building the query parameters

    • build

      default URI build(Object... values) throws URIBuilderException

      Builds the URI from the builder's URI components after replacing the parameters with the string representation of the specified values escaping slash in the path segment components.

      Parameters:
      values - an array of values to replace the components parameters
      Returns:
      a URI
      Throws:
      URIBuilderException - if there was an error building the URI

    • build

      default URI build(List<Object> values) throws URIBuilderException

      Builds the URI from the builder's URI components after replacing the parameters with the string representation of the specified values escaping slash in the path segment components.

      Parameters:
      values - a list of values to replace the components parameters
      Returns:
      a URI
      Throws:
      URIBuilderException - if there was an error building the URI

    • build

      URI build(List<Object> values, boolean escapeSlash) throws URIBuilderException

      Builds the URI from the builder's URI components after replacing the parameters with the string representation of the specified values escaping or not slash in the path segment components.

      Parameters:
      values - a list of values to replace the components parameters
      escapeSlash - true to escape slash in the path segment components
      Returns:
      a URI
      Throws:
      URIBuilderException - if there was an error building the URI

    • build

      default URI build(Map<String,?> values) throws URIBuilderException

      Builds the URI from the builder's URI components after replacing the parameters with the string representation of the specified values.

      Parameters:
      values - a map of values to replace the components parameters
      Returns:
      a URI
      Throws:
      URIBuilderException - if there was an error building the URI

    • build

      URI build(Map<String,?> values, boolean escapeSlash) throws URIBuilderException

      Builds the URI from the builder's URI components after replacing the parameters with the string representation of the specified values escaping or not slash in the path segment components.

      Parameters:
      values - a map of values to replace the components parameters
      escapeSlash - true to escape slash in the path segment components
      Returns:
      a URI
      Throws:
      URIBuilderException - if there was an error building the URI

    • buildString

      default String buildString(Object... values) throws URIBuilderException

      Builds the string representation of the URI from the builder's URI components after replacing the parameters with the string representation of the specified values escaping slash in path segment components.

      Note that the resulting value is percent encoded as defined by RFC 3986 Section 2.1.

      Parameters:
      values - an array of values to replace the components parameters
      Returns:
      a string representation of a URI
      Throws:
      URIBuilderException - if there was an error building the URI

    • buildString

      default String buildString(List<Object> values) throws URIBuilderException

      Builds the string representation of the URI from the builder's URI components after replacing the parameters with the string representation of the specified values escaping slash in path segment components.

      Note that the resulting value is percent encoded as defined by RFC 3986 Section 2.1.

      Parameters:
      values - a list of values to replace the components parameters
      Returns:
      a string representation of a URI
      Throws:
      URIBuilderException - if there was an error building the URI

    • buildString

      String buildString(List<Object> values, boolean escapeSlash) throws URIBuilderException

      Builds the string representation of the URI from the builder's URI components after replacing the parameters with the string representation of the specified values escaping or not slash in the path segment components.

      Note that the resulting value is percent encoded as defined by RFC 3986 Section 2.1.

      Parameters:
      values - a list of values to replace the components parameters
      escapeSlash - true to escape slash in the path segment components
      Returns:
      a string representation of a URI
      Throws:
      URIBuilderException - if there was an error building the URI

    • buildString

      default String buildString(Map<String,?> values) throws URIBuilderException

      Builds the string representation of the URI from the builder's URI components after replacing the parameters with the string representation of the specified values escaping slash in path segment components.

      Note that the resulting value is percent encoded as defined by RFC 3986 Section 2.1.

      Parameters:
      values - a map of values to replace the components parameters
      Returns:
      a string representation of a URI
      Throws:
      URIBuilderException - if there was an error building the URI

    • buildString

      String buildString(Map<String,?> values, boolean escapeSlash) throws URIBuilderException

      Builds the string representation of the URI from the builder's URI components after replacing the parameters with the string representation of the specified values escaping or not slash in the path segment components.

      Note that the resulting value is percent encoded as defined by RFC 3986 Section 2.1.

      Parameters:
      values - a map of values to replace the components parameters
      escapeSlash - true to escape slash in the path segment components
      Returns:
      a string representation of a URI
      Throws:
      URIBuilderException - if there was an error building the URI

    • buildRawString

      String buildRawString() throws URIBuilderException

      Builds the raw string representation of the URI from the builder's URI components.

      Returns:
      a raw string representation of a URI
      Throws:
      URIBuilderException - if there was an error building the URI

    • buildPath

      default String buildPath(Object... values)

      Builds the path component string from the builder's URI path segment components after replacing the parameters with the string representation of the specified values escaping slash in path segment components.

      Note that the resulting value is percent encoded as defined by RFC 3986 Section 2.1.

      Parameters:
      values - an array of values to replace the path components parameters
      Returns:
      a path string
      Throws:
      URIBuilderException - if there was an error building the URI

    • buildPath

      default String buildPath(List<Object> values)

      Builds the path component string from the builder's URI path segment components after replacing the parameters with the string representation of the specified values escaping slash in path segment components.

      Note that the resulting value is percent encoded as defined by RFC 3986 Section 2.1.

      Parameters:
      values - a list of values to replace the path components parameters
      Returns:
      a path string
      Throws:
      URIBuilderException - if there was an error building the URI

    • buildPath

      String buildPath(List<Object> values, boolean escapeSlash)

      Builds the path component string from the builder's URI path segment components after replacing the parameters with the string representation of the specified values escaping or not slash in the path segment components.

      Note that the resulting value is percent encoded as defined by RFC 3986 Section 2.1.

      Parameters:
      values - an array of values to replace the path components parameters
      escapeSlash - true to escape slash in the path segment components
      Returns:
      a path string
      Throws:
      URIBuilderException - if there was an error building the URI

    • buildPath

      String buildPath(Map<String,?> values)

      Builds the path component string from the builder's URI path segment components after replacing the parameters with the string representation of the specified values escaping slash in path segment components.

      Note that the resulting value is percent encoded as defined by RFC 3986 Section 2.1.

      Parameters:
      values - a map of values to replace the components parameters
      Returns:
      a path string
      Throws:
      URIBuilderException - if there was an error building the URI

    • buildPath

      String buildPath(Map<String,?> values, boolean escapeSlash)

      Builds the path component string from the builder's URI path segment components after replacing the parameters with the string representation of the specified values escaping or not slash in the path segment components.

      Note that the resulting value is percent encoded as defined by RFC 3986 Section 2.1.

      Parameters:
      values - a map of values to replace the components parameters
      escapeSlash - true to escape slashes, false otherwise
      Returns:
      a path string
      Throws:
      URIBuilderException - if there was an error building the URI

    • buildRawPath

      String buildRawPath() throws URIBuilderException

      Builds the path component raw string from the builder's path segment components.

      Returns:
      a raw path string
      Throws:
      URIBuilderException - if there was an error building the URI

    • buildQuery

      default String buildQuery(Object... values) throws URIBuilderException

      Builds the query component string from the builder's URI query parameter components after replacing the parameters with the string representation of the specified values.

      Note that the resulting value is percent encoded as defined by RFC 3986 Section 2.1.

      Parameters:
      values - an array of values to replace the path components parameters
      Returns:
      a query string
      Throws:
      URIBuilderException - if there was an error building the URI

    • buildQuery

      String buildQuery(List<Object> values) throws URIBuilderException

      Builds the query component string from the builder's URI query parameter components after replacing the parameters with the string representation of the specified values.

      Note that the resulting value is percent encoded as defined by RFC 3986 Section 2.1.

      Parameters:
      values - a list of values to replace the path components parameters
      Returns:
      a query string
      Throws:
      URIBuilderException - if there was an error building the URI

    • buildQuery

      String buildQuery(Map<String,?> values) throws URIBuilderException

      Builds the query component string from the builder's URI query parameter components after replacing the parameters with the string representation of the specified values.

      Note that the resulting value is percent encoded as defined by RFC 3986 Section 2.1.

      Parameters:
      values - a map of values to replace the components parameters
      Returns:
      a query string
      Throws:
      URIBuilderException - if there was an error building the URI

    • buildRawQuery

      String buildRawQuery() throws URIBuilderException

      Builds the query component raw string from the builder's query parameter components.

      Returns:
      a raw query string
      Throws:
      URIBuilderException - if there was an error building the URI

    • buildPattern

      default URIPattern buildPattern()

      Builds a URI pattern to exactly match builder's URI.

      Returns:
      a URI pattern

    • buildPattern

      URIPattern buildPattern(boolean matchTrailingSlash)

      Builds a URI pattern to match builder's URI including trailing slash or not.

      Parameters:
      matchTrailingSlash - true to match trailing slash
      Returns:
      a URI pattern

    • buildPathPattern

      default URIPattern buildPathPattern()

      Builds a URI pattern to exactly match builder's URI path component.

      Returns:
      a URI pattern

    • buildPathPattern

      URIPattern buildPathPattern(boolean matchTrailingSlash)

      Builds a URI pattern to match builder's URI path component including trailing slash or not.

      Parameters:
      matchTrailingSlash - true to match trailing slash
      Returns:
      a URI pattern

    • clone

      URIBuilder clone()

      Clones the URI builder.

      Returns:
      A copy of the URI builder