Package de.kamillionlabs.hateoflux.linkbuilder

Klasse UriExpander

java.lang.Object
de.kamillionlabs.hateoflux.linkbuilder.UriExpander
public class UriExpander extends Object
Utility class for expanding URI templates. Provides methods to expand URI templates using either ordered parameters or named parameters from a map. The class handles templates indicated by placeholders enclosed in curly braces {}.

  • Methodendetails

    • expand

      public static String expand(String uriAsTemplate, Object... parameters)
      Expands the URI template using a list of anonymous parameters provided in the order they appear within the template. Placeholders for parameters follow the structure suggested by RFC6570. Given that var is a placeholder, i.e., a templated variable, the following applies:
      1. {var} is a mandatory variable.
      2. {?var} is an optional variable used specifically as a query parameter.
      3. {?var1,var2} are two optional query parameters.
      This method does not support exploded query parameters (if required use this expand() instead).

      Example usage: 

       String template = "/users/{userId}/posts{?limit,page}"
 String expanded = expand(template, 42, 10, 2);

 // Outputs: /users/42/posts?limit=10&page=2
      Parameter:
      uriAsTemplate - URI template containing placeholders
      parameters - a sequence of objects that correspond in order to the placeholders in the URI template
      Gibt zurück:
      the expanded or original URI if expansion is not applicable
      Löst aus:
      IllegalArgumentException - if template and parameters are incompatible

    • expand

      public static String expand(String uriAsTemplate, Map<String,?> parameters, boolean collectionRenderedAsComposite)
      Expands the URI template using a map of named path or query parameters. The full documentation can be found at expand(String, Map). This variation of expand() adds the ability to influence how exploded parameters are rendered when a collection is provided.

      Example usages:

      Exploded Query Parameter with Non-Composite Rendering (false) 

       var map = Map.of("keyWords", List.of("blue","active"));
 String expanded = expand("/users{?keyWords*}", map, false);
                                                     ^^^^^
 // Outputs: /users?keyWords=blue,active

      Exploded Query Parameter with Composite Rendering (true) 

       var map = Map.of("keyWords", List.of("blue","active"));
 String expanded = expand("/users{?keyWords*}", map, true);
                                                     ^^^^
 // Outputs: /users?keyWords=blue&keyWords=active
      Parameter:
      uriAsTemplate - URI template containing placeholders
      parameters - a map containing key-value pairs where keys match the placeholders' names. Values for exploded parameters can be a Collection.
      collectionRenderedAsComposite - specifies whether the collection should be rendered as composite (true) or non-composite (false)
      Gibt zurück:
      the expanded or original URI if expansion is not applicable
      Löst aus:
      IllegalArgumentException - if template and parameters are incompatible

    • expand

      public static String expand(String uriAsTemplate, Map<String,?> parameters)
      Expands the URI template using a map of named path or query parameters. If the template contains no placeholders, the original string is returned. Placeholders for parameters follow the structure suggested by RFC6570. Given that var is a placeholder, i.e., a templated variable, the following applies:
      1. {var} is a mandatory variable.
      2. {?var} is an optional variable used specifically as a query parameter.
      3. {?var1,var2} are two optional query parameters.
      4. {?var*} is an exploded query parameter, i.e., it can represent a list.
      Hints on the explode modifier ('*'):
      • A collection of values is only allowed for query parameters.
      • To accept a collection as a value, a query parameter must be marked with the explode modifier ('*' i.e., asterisk).
      • The expansion of exploded parameters is configurable via expand(String, Map, boolean). It can be expanded in a composite or non-composite way.
      • This method expands parameters in a non-composite way by default (e.g., ?var=1,2 as opposed to ?var=1&var=2).

      Example usages:
      Path and Query Parameters 

       var map = Map.of("id", 15,
                  "limit", 50,
                  "page", 2);
 String expanded = expand("/users/{id}/activity{?limit,page}", map);

 // Outputs: /users/15/activity?limit=50&page=2

      Unused Query Parameters in Template 

       var map = Map.of("id", 15);
 String expanded = expand("/users/{id}/activity{?limit,page}", map);

 // Outputs: /users/15/activity

      Exploded Query Parameter 

       var map = Map.of("keyWords", List.of("blue","active")
                                      "page", 3));
 String expanded = expand("/users{?keyWords*,page}", map);

 // Outputs: /users?keyWords=blue,active&page=3
      Parameter:
      uriAsTemplate - URI template containing placeholders
      parameters - a map containing key-value pairs, where keys match the placeholders' names. Values for exploded parameters are allowed to be a Collection
      Gibt zurück:
      the expanded or original URI if expansion is not applicable
      Löst aus:
      IllegalArgumentException - if template and parameters are incompatible

    • removePagingParameters

      public static String removePagingParameters(String inputUrl)
      Removes existing paging query parameters page, size, and sort. Any other query parameter is ignored. If as a result the URI has no query paramters anymore, the '?' is removed.
      Parameter:
      inputUrl - input URL to remove paging parameters from
      Gibt zurück:
      sanitized URL