It is similar to Guava's {@code AsyncFunction}, redeclared so that Guava can be shaded. + *
+ * It is similar to Guava's {@code AsyncFunction}, redeclared so that Guava can be shaded.
*/
public interface ApiAsyncFunction Throwing an exception from this method is equivalent to returning a failing Future.
+ *
+ * Throwing an exception from this method is equivalent to returning a failing Future.
*/
ApiFuture
* Usage guidelines:
* 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 {@link PathTemplate}, which can then be used to perform matching and instantiation.
+ *
+ * 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
+ * {@link PathTemplate}, which can then be used to perform matching and instantiation.
*
- * Matching and instantiation deals with unescaping and escaping using URL encoding rules. For
+ *
+ * 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
* {@code "a/b"}, the slash will be escaped to {@code "%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.
+ * 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:
*
- * Here is an example for a template using simple variables:
* For a variable which has no sub-path, this returns a path template with a single wildcard
+ *
+ * For a variable which has no sub-path, this returns a path template with a single wildcard
* ('*').
*
* @throws ValidationException if the variable does not exist in the template.
@@ -413,13 +420,18 @@ public void validate(String path, String exceptionMessagePrefix) {
* throws a ValidationException. The exceptionMessagePrefix parameter will be prepended to the
* ValidationException message.
*
- * If the path starts with '//', the first segment will be interpreted as a host name and
- * stored in the variable {@link #HOSTNAME_VAR}.
+ *
+ * If the path starts with '//', the first segment will be interpreted as a host name and stored
+ * in the variable {@link #HOSTNAME_VAR}.
+ *
+ *
+ * See the {@link PathTemplate} class documentation for examples.
*
- * See the {@link PathTemplate} class documentation for examples.
+ *
+ * For free wildcards in the template, the matching process creates variables named '$n', where
+ * 'n' is the wildcard's position in the template (starting at n=0). For example:
*
- * For free wildcards in the template, the matching process creates variables named '$n', where
- * 'n' is the wildcard's position in the template (starting at n=0). For example: If the path starts with '//', the first segment will be interpreted as a host name and
- * stored in the variable {@link #HOSTNAME_VAR}.
+ *
+ * If the path starts with '//', the first segment will be interpreted as a host name and stored
+ * in the variable {@link #HOSTNAME_VAR}.
+ *
+ *
+ * See the {@link PathTemplate} class documentation for examples.
*
- * See the {@link PathTemplate} class documentation for examples.
+ *
+ * For free wildcards in the template, the matching process creates variables named '$n', where
+ * 'n' is the wildcard's position in the template (starting at n=0). For example:
*
- * For free wildcards in the template, the matching process creates variables named '$n', where
- * 'n' is the wildcard's position in the template (starting at n=0). For example: Note that free wildcards in the template must have bindings of '$n' variables, where 'n' is
- * the position of the wildcard (starting at 0). See the documentation of {@link #match(String)}
- * for details.
+ *
+ * Note that free wildcards in the template must have bindings of '$n' variables, where 'n' is the
+ * position of the wildcard (starting at 0). See the documentation of {@link #match(String)} for
+ * details.
*
* @throws ValidationException if a variable occurs in the template without a binding.
*/
@@ -641,7 +661,9 @@ public String instantiate(String... keysAndValues) {
/**
* Same like {@link #instantiate(Map)} but allows for unbound variables, which are substituted
- * using their original syntax. Example: A resource name is represented by {@link PathTemplate}, an assignment to variables in the
+ *
+ * A resource name is represented by {@link PathTemplate}, an assignment to variables in the
* template, and an optional endpoint. The {@code 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
+ *
+ * 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:
+ *
+ * Usage examples:
*
*
- *
* PathTemplate template = PathTemplate.create("v1/shelves/{shelf}/books/{book}");
* assert template.matches("v2/shelves") == false;
@@ -79,6 +81,7 @@
*
*
* 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;
@@ -87,9 +90,9 @@
* 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 {@code $n}, where n is the zero-based position of the
- * wildcard. Example:
+ * Path templates can also be used with only wildcards. Each wildcard is associated with an implicit
+ * variable {@code $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;
@@ -100,10 +103,11 @@
* 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 {@code //somewhere.io/some/path}. The host name is matched into the special
- * variable {@link #HOSTNAME_VAR}. Patterns are agnostic about host names, and the same pattern
- * can be used for URL relative syntax and simple path syntax:
+ * Paths input to matching can use URL relative syntax to indicate a host name by prefixing the host
+ * name, as in {@code //somewhere.io/some/path}. The host name is matched into the special variable
+ * {@link #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<>();
@@ -115,15 +119,15 @@
* assert template.match("shelves/s1").equals(expectedValues);
*
*
- * For the representation of a resource name see {@link TemplatedResourceName}, which is based
- * on path templates.
+ * For the representation of a resource name see {@link TemplatedResourceName}, which is
+ * based on path templates.
*/
@BetaApi
public class PathTemplate {
/**
- * A constant identifying the special variable used for endpoint bindings in
- * the result of {@link #matchFromFullName(String)}.
+ * A constant identifying the special variable used for endpoint bindings in the result of
+ * {@link #matchFromFullName(String)}.
*/
public static final String HOSTNAME_VAR = "$hostname";
@@ -322,16 +326,19 @@ public PathTemplate withoutVars() {
}
/**
- * Returns a path template for the sub-path of the given variable. Example:
+ * Returns a path template for the sub-path of the given variable. Example:
+ *
+ *
* PathTemplate template = PathTemplate.create("v1/{name=shelves/*/books/*}");
* assert template.subTemplate("name").toString().equals("shelves/*/books/*");
*
*
* The returned template will never have named variables, but only wildcards, which are dealt with
- * in matching and instantiation using '$n'-variables. See the documentation of {@link
- * #match(String)} and {@link #instantiate(Map)}, respectively.
+ * in matching and instantiation using '$n'-variables. See the documentation of
+ * {@link #match(String)} and {@link #instantiate(Map)}, respectively.
*
- *
+ *
* PathTemplate template = PathTemplate.create("shelves/*/books/*");
* Map<String, String> expectedValues = new HashMap<>();
* expectedValues.put("$0", "s1");
@@ -462,13 +474,18 @@ public boolean matches(String path) {
* will be properly unescaped using URL encoding rules. If the path does not match the template,
* null is returned.
*
- *
+ *
* PathTemplate template = PathTemplate.create("shelves/*/books/*");
* Map<String, String> expectedValues = new HashMap<>();
* expectedValues.put("$0", "s1");
@@ -491,7 +508,9 @@ public Map
+ * it starts with '//' or not. Example:
+ *
+ *
* Map<String, String> expectedValues = new HashMap<>();
* expectedValues.put(HOSTNAME_VAR, "//somewhere.io");
* expectedValues.put("name", "shelves/s1");
@@ -618,9 +637,10 @@ private boolean match(
* Instantiate the template based on the given variable assignment. Performs proper URL escaping
* of variable assignments.
*
- *
+ * using their original syntax. Example:
+ *
+ *
* PathTemplate template = PathTemplate.create("v1/shelves/{shelf}/books/{book}");
* Map<String, String> partialMap = new HashMap<>();
* partialMap.put("shelf", "s1");
@@ -957,8 +979,8 @@ public String toString() {
}
/**
- * Returns a raw version of the template as a string. This renders the template in its
- * internal, normalized form.
+ * Returns a raw version of the template as a string. This renders the template in its internal,
+ * normalized form.
*/
public String toRawString() {
return toSyntax(segments, false);
diff --git a/src/main/java/com/google/api/pathtemplate/TemplatedResourceName.java b/src/main/java/com/google/api/pathtemplate/TemplatedResourceName.java
index 00395d15b..db49858d8 100644
--- a/src/main/java/com/google/api/pathtemplate/TemplatedResourceName.java
+++ b/src/main/java/com/google/api/pathtemplate/TemplatedResourceName.java
@@ -44,16 +44,19 @@
/**
* Class for representing and working with resource names.
*
- *
* PathTemplate template = PathTemplate.create("shelves/*/books/*");
@@ -91,8 +94,8 @@ public