UriTemplate.java
/*
* Copyright (c) 2011 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
* in compliance with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the License
* is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
* or implied. See the License for the specific language governing permissions and limitations under
* the License.
*/
package com.google.api.client.http;
import com.google.api.client.util.Data;
import com.google.api.client.util.FieldInfo;
import com.google.api.client.util.Preconditions;
import com.google.api.client.util.Types;
import com.google.api.client.util.escape.CharEscapers;
import com.google.common.base.Splitter;
import java.util.HashMap;
import java.util.Iterator;
import java.util.LinkedHashMap;
import java.util.ListIterator;
import java.util.Map;
/**
* Expands URI Templates.
*
* <p>This Class supports Level 1 templates and all Level 4 composite templates as described in: <a
* href="http://tools.ietf.org/html/rfc6570">RFC 6570</a>.
*
* <p>Specifically, for the variables: var := "value" list := ["red", "green", "blue"] keys :=
* [("semi", ";"),("dot", "."),("comma", ",")]
*
* <p>The following templates results in the following expansions: {var} -> value {list} ->
* red,green,blue {list*} -> red,green,blue {keys} -> semi,%3B,dot,.,comma,%2C {keys*} ->
* semi=%3B,dot=.,comma=%2C {+list} -> red,green,blue {+list*} -> red,green,blue {+keys} ->
* semi,;,dot,.,comma,, {+keys*} -> semi=;,dot=.,comma=, {#list} -> #red,green,blue {#list*} ->
* #red,green,blue {#keys} -> #semi,;,dot,.,comma,, {#keys*} -> #semi=;,dot=.,comma=, X{.list} ->
* X.red,green,blue X{.list*} -> X.red.green.blue X{.keys} -> X.semi,%3B,dot,.,comma,%2C X{.keys*}
* -> X.semi=%3B.dot=..comma=%2C {/list} -> /red,green,blue {/list*} -> /red/green/blue {/keys} ->
* /semi,%3B,dot,.,comma,%2C {/keys*} -> /semi=%3B/dot=./comma=%2C {;list} -> ;list=red,green,blue
* {;list*} -> ;list=red;list=green;list=blue {;keys} -> ;keys=semi,%3B,dot,.,comma,%2C {;keys*} ->
* ;semi=%3B;dot=.;comma=%2C {?list} -> ?list=red,green,blue {?list*} ->
* ?list=red&list=green&list=blue {?keys} -> ?keys=semi,%3B,dot,.,comma,%2C {?keys*} ->
* ?semi=%3B&dot=.&comma=%2C {&list} -> &list=red,green,blue {&list*} ->
* &list=red&list=green&list=blue {&keys} -> &keys=semi,%3B,dot,.,comma,%2C {&keys*} ->
* &semi=%3B&dot=.&comma=%2C {?var,list} -> ?var=value&list=red,green,blue
*
* @since 1.6
* @author Ravi Mistry
*/
public class UriTemplate {
private static final Map<Character, CompositeOutput> COMPOSITE_PREFIXES =
new HashMap<Character, CompositeOutput>();
static {
CompositeOutput.values();
}
private static final String COMPOSITE_NON_EXPLODE_JOINER = ",";
/** Contains information on how to output a composite value. */
private enum CompositeOutput {
/** Reserved expansion. */
PLUS('+', "", ",", false, true),
/** Fragment expansion. */
HASH('#', "#", ",", false, true),
/** Label expansion with dot-prefix. */
DOT('.', ".", ".", false, false),
/** Path segment expansion. */
FORWARD_SLASH('/', "/", "/", false, false),
/** Path segment parameter expansion. */
SEMI_COLON(';', ";", ";", true, false),
/** Form-style query expansion. */
QUERY('?', "?", "&", true, false),
/** Form-style query continuation. */
AMP('&', "&", "&", true, false),
/** Simple expansion. */
SIMPLE(null, "", ",", false, false);
private final Character propertyPrefix;
private final String outputPrefix;
private final String explodeJoiner;
private final boolean requiresVarAssignment;
private final boolean reservedExpansion;
/**
* @param propertyPrefix the prefix of a parameter or {@code null} for none. In {+var} the
* prefix is '+'
* @param outputPrefix the string that should be prefixed to the expanded template.
* @param explodeJoiner the delimiter used to join composite values.
* @param requiresVarAssignment denotes whether or not the expanded template should contain an
* assignment with the variable
* @param reservedExpansion reserved expansion allows percent-encoded triplets and characters in
* the reserved set
*/
CompositeOutput(
Character propertyPrefix,
String outputPrefix,
String explodeJoiner,
boolean requiresVarAssignment,
boolean reservedExpansion) {
this.propertyPrefix = propertyPrefix;
this.outputPrefix = Preconditions.checkNotNull(outputPrefix);
this.explodeJoiner = Preconditions.checkNotNull(explodeJoiner);
this.requiresVarAssignment = requiresVarAssignment;
this.reservedExpansion = reservedExpansion;
if (propertyPrefix != null) {
COMPOSITE_PREFIXES.put(propertyPrefix, this);
}
}
/** Returns the string that should be prefixed to the expanded template. */
String getOutputPrefix() {
return outputPrefix;
}
/** Returns the delimiter used to join composite values. */
String getExplodeJoiner() {
return explodeJoiner;
}
/**
* Returns whether or not the expanded template should contain an assignment with the variable.
*/
boolean requiresVarAssignment() {
return requiresVarAssignment;
}
/**
* Returns the start index of the var name. If the variable contains a prefix the start index
* will be 1 else it will be 0.
*/
int getVarNameStartIndex() {
return propertyPrefix == null ? 0 : 1;
}
/**
* Encodes the specified value. If reserved expansion is turned on, then percent-encoded
* triplets and characters are allowed in the reserved set.
*
* @param value the string to be encoded
* @return the encoded string
*/
private String getEncodedValue(String value) {
String encodedValue;
if (reservedExpansion) {
// Reserved expansion allows percent-encoded triplets and characters in the reserved set.
encodedValue = CharEscapers.escapeUriPathWithoutReserved(value);
} else {
encodedValue = CharEscapers.escapeUriConformant(value);
}
return encodedValue;
}
}
static CompositeOutput getCompositeOutput(String propertyName) {
CompositeOutput compositeOutput = COMPOSITE_PREFIXES.get(propertyName.charAt(0));
return compositeOutput == null ? CompositeOutput.SIMPLE : compositeOutput;
}
/**
* Constructs a new {@code Map<String, Object>} from an {@code Object}.
*
* <p>There are no null values in the returned map.
*/
private static Map<String, Object> getMap(Object obj) {
// Using a LinkedHashMap to maintain the original order of insertions. This is done to help
// with handling unused parameters and makes testing easier as well.
Map<String, Object> map = new LinkedHashMap<String, Object>();
for (Map.Entry<String, Object> entry : Data.mapOf(obj).entrySet()) {
Object value = entry.getValue();
if (value != null && !Data.isNull(value)) {
map.put(entry.getKey(), value);
}
}
return map;
}
/**
* Expands templates in a URI template that is relative to a base URL.
*
* <p>If the URI template starts with a "/" the raw path from the base URL is stripped out. If the
* URI template is a full URL then it is used instead of the base URL.
*
* <p>Supports Level 1 templates and all Level 4 composite templates as described in: <a
* href="http://tools.ietf.org/html/rfc6570">RFC 6570</a>.
*
* @param baseUrl The base URL which the URI component is relative to.
* @param uriTemplate URI component. It may contain one or more sequences of the form "{name}",
* where "name" must be a key in variableMap.
* @param parameters an object with parameters designated by Key annotations. If the template has
* no variable references, parameters may be {@code null}.
* @param addUnusedParamsAsQueryParams If true then parameters that do not match the template are
* appended to the expanded template as query parameters.
* @return The expanded template
* @since 1.7
*/
public static String expand(
String baseUrl, String uriTemplate, Object parameters, boolean addUnusedParamsAsQueryParams) {
String pathUri;
if (uriTemplate.startsWith("/")) {
// Remove the base path from the base URL.
GenericUrl url = new GenericUrl(baseUrl);
url.setRawPath(null);
pathUri = url.build() + uriTemplate;
} else if (uriTemplate.startsWith("http://") || uriTemplate.startsWith("https://")) {
pathUri = uriTemplate;
} else {
pathUri = baseUrl + uriTemplate;
}
return expand(pathUri, parameters, addUnusedParamsAsQueryParams);
}
/**
* Expands templates in a URI.
*
* <p>Supports Level 1 templates and all Level 4 composite templates as described in: <a
* href="http://tools.ietf.org/html/rfc6570">RFC 6570</a>.
*
* @param pathUri URI component. It may contain one or more sequences of the form "{name}", where
* "name" must be a key in variableMap
* @param parameters an object with parameters designated by Key annotations. If the template has
* no variable references, parameters may be {@code null}.
* @param addUnusedParamsAsQueryParams If true then parameters that do not match the template are
* appended to the expanded template as query parameters.
* @return The expanded template
* @since 1.6
*/
public static String expand(
String pathUri, Object parameters, boolean addUnusedParamsAsQueryParams) {
Map<String, Object> variableMap = getMap(parameters);
StringBuilder pathBuf = new StringBuilder();
int cur = 0;
int length = pathUri.length();
while (cur < length) {
int next = pathUri.indexOf('{', cur);
if (next == -1) {
if (cur == 0 && !addUnusedParamsAsQueryParams) {
// No expansions exist and we do not need to add any query parameters.
return pathUri;
}
pathBuf.append(pathUri.substring(cur));
break;
}
pathBuf.append(pathUri.substring(cur, next));
int close = pathUri.indexOf('}', next + 2);
cur = close + 1;
String templates = pathUri.substring(next + 1, close);
CompositeOutput compositeOutput = getCompositeOutput(templates);
ListIterator<String> templateIterator =
Splitter.on(',').splitToList(templates).listIterator();
boolean isFirstParameter = true;
while (templateIterator.hasNext()) {
String template = templateIterator.next();
boolean containsExplodeModifier = template.endsWith("*");
int varNameStartIndex =
templateIterator.nextIndex() == 1 ? compositeOutput.getVarNameStartIndex() : 0;
int varNameEndIndex = template.length();
if (containsExplodeModifier) {
// The expression contains an explode modifier '*' at the end, update end index.
varNameEndIndex = varNameEndIndex - 1;
}
// Now get varName devoid of any prefixes and explode modifiers.
String varName = template.substring(varNameStartIndex, varNameEndIndex);
Object value = variableMap.remove(varName);
if (value == null) {
// The value for this variable is undefined. continue with the next template.
continue;
}
if (!isFirstParameter) {
pathBuf.append(compositeOutput.getExplodeJoiner());
} else {
pathBuf.append(compositeOutput.getOutputPrefix());
isFirstParameter = false;
}
if (value instanceof Iterator<?>) {
// Get the list property value.
Iterator<?> iterator = (Iterator<?>) value;
value = getListPropertyValue(varName, iterator, containsExplodeModifier, compositeOutput);
} else if (value instanceof Iterable<?> || value.getClass().isArray()) {
// Get the list property value.
Iterator<?> iterator = Types.iterableOf(value).iterator();
value = getListPropertyValue(varName, iterator, containsExplodeModifier, compositeOutput);
} else if (value.getClass().isEnum()) {
String name = FieldInfo.of((Enum<?>) value).getName();
value = getSimpleValue(varName, name != null ? name : value.toString(), compositeOutput);
} else if (!Data.isValueOfPrimitiveType(value)) {
// Parse the value as a key/value map.
Map<String, Object> map = getMap(value);
value = getMapPropertyValue(varName, map, containsExplodeModifier, compositeOutput);
} else {
// For everything else...
value = getSimpleValue(varName, value.toString(), compositeOutput);
}
pathBuf.append(value);
}
}
if (addUnusedParamsAsQueryParams) {
// Add the parameters remaining in the variableMap as query parameters.
GenericUrl.addQueryParams(variableMap.entrySet(), pathBuf, false);
}
return pathBuf.toString();
}
private static String getSimpleValue(String name, String value, CompositeOutput compositeOutput) {
if (compositeOutput.requiresVarAssignment()) {
return String.format("%s=%s", name, compositeOutput.getEncodedValue(value));
}
return compositeOutput.getEncodedValue(value);
}
/**
* Expand the template of a composite list property. Eg: If d := ["red", "green", "blue"] then
* {/d*} is expanded to "/red/green/blue"
*
* @param varName the name of the variable the value corresponds to. E.g. "d"
* @param iterator the iterator over list values. E.g. ["red", "green", "blue"]
* @param containsExplodeModifiersSet to true if the template contains the explode modifier "*"
* @param compositeOutput an instance of CompositeOutput. Contains information on how the
* expansion should be done
* @return the expanded list template
* @throws IllegalArgumentException if the required list path parameter is empty
*/
private static String getListPropertyValue(
String varName,
Iterator<?> iterator,
boolean containsExplodeModifier,
CompositeOutput compositeOutput) {
if (!iterator.hasNext()) {
return "";
}
StringBuilder retBuf = new StringBuilder();
String joiner;
if (containsExplodeModifier) {
joiner = compositeOutput.getExplodeJoiner();
} else {
joiner = COMPOSITE_NON_EXPLODE_JOINER;
if (compositeOutput.requiresVarAssignment()) {
retBuf.append(CharEscapers.escapeUriPath(varName));
retBuf.append("=");
}
}
while (iterator.hasNext()) {
if (containsExplodeModifier && compositeOutput.requiresVarAssignment()) {
retBuf.append(CharEscapers.escapeUriPath(varName));
retBuf.append("=");
}
retBuf.append(compositeOutput.getEncodedValue(iterator.next().toString()));
if (iterator.hasNext()) {
retBuf.append(joiner);
}
}
return retBuf.toString();
}
/**
* Expand the template of a composite map property. Eg: If d := [("semi", ";"),("dot",
* "."),("comma", ",")] then {/d*} is expanded to "/semi=%3B/dot=./comma=%2C"
*
* @param varName the name of the variable the value corresponds to. Eg: "d"
* @param map the map property value. Eg: [("semi", ";"),("dot", "."),("comma", ",")]
* @param containsExplodeModifier Set to true if the template contains the explode modifier "*"
* @param compositeOutput contains information on how the expansion should be done
* @return the expanded map template
* @throws IllegalArgumentException if the required list path parameter is map
*/
private static String getMapPropertyValue(
String varName,
Map<String, Object> map,
boolean containsExplodeModifier,
CompositeOutput compositeOutput) {
if (map.isEmpty()) {
return "";
}
StringBuilder retBuf = new StringBuilder();
String joiner;
String mapElementsJoiner;
if (containsExplodeModifier) {
joiner = compositeOutput.getExplodeJoiner();
mapElementsJoiner = "=";
} else {
joiner = COMPOSITE_NON_EXPLODE_JOINER;
mapElementsJoiner = COMPOSITE_NON_EXPLODE_JOINER;
if (compositeOutput.requiresVarAssignment()) {
retBuf.append(CharEscapers.escapeUriPath(varName));
retBuf.append("=");
}
}
for (Iterator<Map.Entry<String, Object>> mapIterator = map.entrySet().iterator();
mapIterator.hasNext(); ) {
Map.Entry<String, Object> entry = mapIterator.next();
String encodedKey = compositeOutput.getEncodedValue(entry.getKey());
String encodedValue = compositeOutput.getEncodedValue(entry.getValue().toString());
retBuf.append(encodedKey);
retBuf.append(mapElementsJoiner);
retBuf.append(encodedValue);
if (mapIterator.hasNext()) {
retBuf.append(joiner);
}
}
return retBuf.toString();
}
}