Package com.google.api.pathtemplate (2.15.1)

Represents a path template.

Templates use the syntax of the API platform; see the protobuf of HttpRule for details. A template consists of a sequence of literals, wildcards, and variable bindings, where each binding can have a sub-path. A string representation can be parsed into an instance of PathTemplate, which can then be used to perform matching and instantiation.

Matching and instantiation deals with unescaping and escaping using URL encoding rules. For example, if a template variable for a single segment is instantiated with a string like "a/b", the slash will be escaped to "%2f". (Note that slash will not be escaped for a multiple-segment variable, but other characters will). The literals in the template itself are not escaped automatically, and must be already URL encoded.

Here is an example for a template using simple variables:

 PathTemplate template = PathTemplate.create("v1/shelves/{shelf}/books/{book}");
 assert template.matches("v2/shelves") == false;
 Map<String, String> values = template.match("v1/shelves/s1/books/b1");
 Map<String, String> expectedValues = new HashMap<>();
 expectedValues.put("shelf", "s1");
 expectedValues.put("book", "b1");
 assert values.equals(expectedValues);
 assert template.instantiate(values).equals("v1/shelves/s1/books/b1");
 

Templates can use variables which match sub-paths. Example:

 PathTemplate template = PathTemplate.create("v1/{name=shelves/*/books/*}";
 assert template.match("v1/shelves/books/b1") == null;
 Map<String, String> expectedValues = new HashMap<>();
 expectedValues.put("name", "shelves/s1/books/b1");
 assert template.match("v1/shelves/s1/books/b1").equals(expectedValues);
 }

Path templates can also be used with only wildcards. Each wildcard is associated with an implicit variable $n, where n is the zero-based position of the wildcard. Example:

 PathTemplate template = PathTemplate.create("shelves/*/books/*";
 assert template.match("shelves/books/b1") == null;
 Map<String, String> values = template.match("v1/shelves/s1/books/b1");
 Map<String, String> expectedValues = new HashMap<>();
 expectedValues.put("$0", s1");
 expectedValues.put("$1", "b1");
 assert values.equals(expectedValues);
 }

Paths input to matching can use URL relative syntax to indicate a host name by prefixing the host name, as in //somewhere.io/some/path. The host name is matched into the special variable #HOSTNAME_VAR. Patterns are agnostic about host names, and the same pattern can be used for URL relative syntax and simple path syntax:

 PathTemplate template = PathTemplate.create("shelves/*";
 Map<String, String> expectedValues = new HashMap<>();
 expectedValues.put(PathTemplate.HOSTNAME_VAR, "//somewhere.io");
 expectedValues.put("$0", s1");
 assert template.match("//somewhere.io/shelves/s1").equals(expectedValues);
 expectedValues.clear();
 expectedValues.put("$0", s1");
 assert template.match("shelves/s1").equals(expectedValues);
 }

For the representation of a resource name see TemplatedResourceName, which is based on path templates.

Class for representing and working with resource names.

A resource name is represented by PathTemplate, an assignment to variables in the template, and an optional endpoint. The ResourceName class implements the map interface (unmodifiable) to work with the variable assignments, and has methods to reproduce the string representation of the name, to construct new names, and to dereference names into resources.

As a resource name essentially represents a match of a path template against a string, it can be also used for other purposes than naming resources. However, not all provided methods may make sense in all applications.

Usage examples:

 PathTemplate template = PathTemplate.create("shelves/*/books/*");
 TemplatedResourceName resourceName = TemplatedResourceName.create(template, "shelves/s1/books/b1");
 assert resourceName.get("$1").equals("b1");
 assert resourceName.parentName().toString().equals("shelves/s1/books");
 

Represents a resource name resolver which can be registered with this class.

Exception thrown if there is a validation problem with a path template, http config, or related framework methods. Comes as an illegal argument exception subclass. Allows to globally set a thread-local validation context description which each exception inherits.