All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.google.gwt.safehtml.rebind.SafeHtmlTemplatesImplMethodCreator Maven / Gradle / Ivy

There is a newer version: 2.10.0
Show newest version
/*
 * Copyright 2009 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.gwt.safehtml.rebind;

import com.google.gwt.core.ext.TreeLogger;
import com.google.gwt.core.ext.UnableToCompleteException;
import com.google.gwt.core.ext.typeinfo.JMethod;
import com.google.gwt.core.ext.typeinfo.JParameter;
import com.google.gwt.core.ext.typeinfo.JType;
import com.google.gwt.i18n.rebind.AbstractResource.ResourceList;
import com.google.gwt.i18n.shared.GwtLocale;
import com.google.gwt.safecss.shared.SafeStyles;
import com.google.gwt.safehtml.client.SafeHtmlTemplates.Template;
import com.google.gwt.safehtml.rebind.ParsedHtmlTemplate.HtmlContext;
import com.google.gwt.safehtml.rebind.ParsedHtmlTemplate.LiteralChunk;
import com.google.gwt.safehtml.rebind.ParsedHtmlTemplate.ParameterChunk;
import com.google.gwt.safehtml.rebind.ParsedHtmlTemplate.TemplateChunk;
import com.google.gwt.safehtml.shared.OnlyToBeUsedInGeneratedCodeStringBlessedAsSafeHtml;
import com.google.gwt.safehtml.shared.SafeHtml;
import com.google.gwt.safehtml.shared.SafeHtmlUtils;
import com.google.gwt.safehtml.shared.SafeUri;
import com.google.gwt.safehtml.shared.UriUtils;
import com.google.gwt.user.rebind.AbstractGeneratorClassCreator;
import com.google.gwt.user.rebind.AbstractMethodCreator;

/**
 * Method body code generator for implementations of
 * {@link com.google.gwt.safehtml.client.SafeHtmlTemplates}.
 */
public class SafeHtmlTemplatesImplMethodCreator extends AbstractMethodCreator {

  /**
   * Fully-qualified class name of the {@link String} class.
   */
  private static final String JAVA_LANG_STRING_FQCN = String.class.getName();

  /**
   * Simple class name of the {@link SafeUri} interface.
   */
  private static final String SAFE_URI_CN = SafeUri.class.getSimpleName();

  /**
   * Fully-qualified class name of the {@link SafeUri} interface.
   */
  private static final String SAFE_URI_FQCN = SafeUri.class.getName();

  /**
   * Simple class name of the {@link SafeStyles} interface.
   */
  private static final String SAFE_STYLES_CN = SafeStyles.class.getSimpleName();

  /**
   * Fully-qualified class name of the {@link SafeStyles} interface.
   */
  private static final String SAFE_STYLES_FQCN = SafeStyles.class.getName();

  /**
   * Simple class name of the {@link SafeHtml} interface.
   */
  private static final String SAFE_HTML_CN = SafeHtml.class.getSimpleName();

  /**
   * Fully-qualified class name of the {@link SafeHtml} interface.
   */
  private static final String SAFE_HTML_FQCN = SafeHtml.class.getName();

  /**
   * Fully-qualified class name of the StringBlessedAsSafeHtml class.
   */
  private static final String BLESSED_STRING_FQCN =
      OnlyToBeUsedInGeneratedCodeStringBlessedAsSafeHtml.class.getName();

  /**
   * Fully-qualified class name of the {@link SafeHtmlUtils} class.
   */
  private static final String SAFE_HTML_UTILS_FQCN = SafeHtmlUtils.class.getName();

  /**
   * Fully-qualified class name of the {@link UriUtils} class.
   */
  private static final String URI_UTILS_FQCN = UriUtils.class.getName();

  public SafeHtmlTemplatesImplMethodCreator(AbstractGeneratorClassCreator classCreator) {
    super(classCreator);
  }

  /**
   * {@inheritDoc}
   */
  @Override
  public void createMethodFor(TreeLogger logger, JMethod targetMethod, String key,
      ResourceList resourceList, GwtLocale locale) throws UnableToCompleteException {
    if (!targetMethod.getReturnType().getQualifiedSourceName().equals(
        SafeHtmlTemplatesImplMethodCreator.SAFE_HTML_FQCN)) {
      throw error(logger, "All methods in interfaces extending "
          + "SafeHtmlTemplates must have a return type of "
          + SafeHtmlTemplatesImplMethodCreator.SAFE_HTML_FQCN + ".");
    }
    Template templateAnnotation = targetMethod.getAnnotation(Template.class);
    if (templateAnnotation == null) {
      throw error(logger, "Required annotation @Template not present on interface method "
          + targetMethod.toString());
    }

    String template = templateAnnotation.value();
    JParameter[] params = targetMethod.getParameters();
    emitMethodBodyFromTemplate(logger, template, params);
  }

  /**
   * Emits an expression corresponding to a template variable in "attribute"
   * context.
   *
   * 

The expression emitted applies appropriate escaping and/or sanitization * to the parameter's value depending the Java type of the corresponding * template method parameter: * *

    *
  • If the parameter is of type {@link SafeStyles}, it is converted to a * string using {@link SafeStyles#asString()}. *
  • Otherwise, if the parameter is of type {@link SafeUri}, it is converted to a * string using {@link SafeUri#asString()}. *
  • Otherwise, if the parameter is not of type {@link String}, it is * first converted to {@link String}. *
  • If the template parameter occurs at the start, or as the entire value, * of a URI-valued attribute within the template, and the parameter isn't * of type {@link SafeUri}, it is sanitized to ensure that it is safe in * this context. This is done by passing the value through * {@link UriUtils#sanitizeUri(String)}. *
  • The result is then HTML-escaped by passing it through * {@link SafeHtmlUtils#htmlEscape(String)}. *
* * Note: Template method parameters of type {@link SafeHtml} are * not treated specially in an attribute context, and will be HTML- * escaped like regular strings. This is because {@link SafeHtml} values can * contain non-escaped HTML markup, which is not valid within attributes. * * @param logger the logger to log failures to * @param htmlContext the HTML context in which the corresponding template * variable occurs in * @param formalParameterName the name of the template method's formal * parameter corresponding to the expression being emitted * @param parameterType the Java type of the corresponding template method's * parameter */ private void emitAttributeContextParameterExpression(TreeLogger logger, HtmlContext htmlContext, String formalParameterName, JType parameterType) { /* * Build up the expression from the "inside out", i.e. start with the formal * parameter, convert to string if necessary, then wrap in validators if * necessary, and finally HTML-escape if necessary. */ String expression = formalParameterName; if (isSafeUri(parameterType) || isSafeStyles(parameterType)) { // SafeUri is safe in a URL context, and SafeStyles is safe in a CSS context, // so we can use their string (but we still escape it). expression = expression + ".asString()"; } else { if (!JAVA_LANG_STRING_FQCN.equals(parameterType.getQualifiedSourceName())) { // The parameter's value must be explicitly converted to String unless it // is already of that type. expression = "String.valueOf(" + expression + ")"; } if ((htmlContext.getType() == HtmlContext.Type.URL_ATTRIBUTE_START) || (htmlContext.getType() == HtmlContext.Type.URL_ATTRIBUTE_ENTIRE)) { expression = URI_UTILS_FQCN + ".sanitizeUri(" + expression + ")"; } } // TODO(xtof): Handle EscapedString subtype of SafeHtml, once it's been // introduced. expression = SAFE_HTML_UTILS_FQCN + ".htmlEscape(" + expression + ")"; print(expression); } /** * Generates code that renders the provided HTML template into an instance * of the {@link SafeHtml} type. * *

The template is parsed as a HTML template (see * {@link HtmlTemplateParser}). From the template's parsed form, code is * generated that, when executed, will emit an instantiation of the template. * The generated code appropriately escapes and/or sanitizes template * parameters such that evaluating the emitted string as HTML in a browser * will not result in script execution. * *

As such, strings emitted from generated template methods satisfy the * type contract of the {@link SafeHtml} type, and can therefore be returned * wrapped as {@link SafeHtml}. * * @param logger the logger to log failures to * @param template the (X)HTML template to generate code for * @param params the parameters of the corresponding template method * @throws UnableToCompleteException if an error occurred that prevented * code generation for the template */ private void emitMethodBodyFromTemplate(TreeLogger logger, String template, JParameter[] params) throws UnableToCompleteException { println("StringBuilder sb = new java.lang.StringBuilder();"); HtmlTemplateParser parser = new HtmlTemplateParser(logger); parser.parseTemplate(template); for (TemplateChunk chunk : parser.getParsedTemplate().getChunks()) { if (chunk.getKind() == TemplateChunk.Kind.LITERAL) { emitStringLiteral(((LiteralChunk) chunk).getLiteral()); } else if (chunk.getKind() == TemplateChunk.Kind.PARAMETER) { ParameterChunk parameterChunk = (ParameterChunk) chunk; int formalParameterIndex = parameterChunk.getParameterIndex(); if (formalParameterIndex < 0 || formalParameterIndex >= params.length) { throw error(logger, "Argument " + formalParameterIndex + " beyond range of arguments: " + template); } String formalParameterName = "arg" + formalParameterIndex; JType paramType = params[formalParameterIndex].getType(); emitParameterExpression( logger, parameterChunk.getContext(), formalParameterName, paramType); } else { throw error(logger, "Unexpected chunk kind in parsed template " + template); } } outdent(); outdent(); println("return new " + BLESSED_STRING_FQCN + "(sb.toString());"); } /** * Emits an expression corresponding to a template parameter. * *

* The expression emitted applies appropriate escaping/sanitization to the * parameter's value, depending on the parameter's HTML context, and the Java * type of the corresponding template method parameter. * * @param logger the logger to log failures to * @param htmlContext the HTML context in which the corresponding template * variable occurs in * @param formalParameterName the name of the template method's formal * parameter corresponding to the expression being emitted * @param parameterType the Java type of the corresponding template method's * parameter * @throws UnableToCompleteException if the parameterType is not valid for the * htmlContext */ private void emitParameterExpression(TreeLogger logger, HtmlContext htmlContext, String formalParameterName, JType parameterType) throws UnableToCompleteException { /* * Verify that the parameter type is used in the correct context. Safe * expressions are only safe in specific contexts. */ HtmlContext.Type contextType = htmlContext.getType(); if (isSafeHtml(parameterType) && HtmlContext.Type.TEXT != contextType) { /* * SafeHtml used in a non-text context. SafeHtml is escaped for a text * context. In a non-text context, the string is not guaranteed to be * safe. */ throw error(logger, SAFE_HTML_CN + " used in a non-text context. Did you mean to use " + JAVA_LANG_STRING_FQCN + " or " + SAFE_STYLES_CN + " instead?"); } else if (isSafeStyles(parameterType) && HtmlContext.Type.CSS_ATTRIBUTE_START != contextType) { if (HtmlContext.Type.CSS_ATTRIBUTE == contextType) { // SafeStyles can only be used at the start of a CSS attribute. throw error(logger, SAFE_STYLES_CN + " cannot be used in the middle of a CSS attribute. " + "It must be used at the start a CSS attribute."); } else { /* * SafeStyles used in a non-css attribute context. SafeStyles is only * safe in a CSS attribute context. We could treat it as a normal * parameter and escape the string value of the parameter, but it almost * definitely isn't what the developer intended to do. */ throw error(logger, SAFE_STYLES_CN + " used in a non-CSS attribute context. Did you mean to use " + JAVA_LANG_STRING_FQCN + " or " + SAFE_HTML_CN + " instead?"); } } else if (isSafeUri(parameterType) && HtmlContext.Type.URL_ATTRIBUTE_ENTIRE != contextType) { // TODO(xtof): refactor HtmlContext with isStart/isEnd/isEntire accessors and simplified type. if (HtmlContext.Type.URL_ATTRIBUTE_START == contextType) { // SafeUri can only be used as the entire value of an URL attribute. throw error(logger, SAFE_URI_CN + " cannot be used in a URL attribute if it isn't the " + "entire attribute value."); } else { /* * SafeUri outside a URL-attribute context (or in a URL-attribute, but * not at start). SafeUri is only safe if it comprises the entire URL * attribute's value. We could treat it as a normal parameter and escape * the string value of the parameter, but it almost definitely isn't * what the developer intended to do. */ throw error(logger, SAFE_URI_CN + " can only be used as the entire value of a URL " + "attribute. Did you mean to use " + JAVA_LANG_STRING_FQCN + " or " + SAFE_HTML_CN + " instead?"); } } print("sb.append("); switch (contextType) { case CSS: /* * TODO(jlabanca): Handle CSS in a text context. * * The stream parser does not parse CSS; we could however improve safety * via sub-formats that specify the in-css context. * * SafeStyles is safe in a CSS context when used inside of a CSS style * rule, but they are not always safe. We could implement SafeCssRules, * which would consist of SafeStyles inside of a CSS style rules found * in a style tag. */ logger.log(TreeLogger.WARN, "Template with variable in CSS context: " + "The template code generator cannot guarantee HTML-safety of " + "the template -- please inspect manually"); emitTextContextParameterExpression(formalParameterName, parameterType); break; case TEXT: emitTextContextParameterExpression(formalParameterName, parameterType); break; case CSS_ATTRIBUTE: case CSS_ATTRIBUTE_START: /* * We already checked if the user tried to use SafeStyles in an invalid * (non-CSS_ATTRIBUTE) context, but now we check if the user could have * used SafeStyles in the current context. */ if (!isSafeStyles(parameterType)) { // Warn against using unsafe parameters in a CSS attribute context. logger.log(TreeLogger.WARN, "Template with variable in CSS attribute context: The template code generator cannot" + " guarantee HTML-safety of the template -- please inspect manually or use " + SAFE_STYLES_CN + " to specify arguments in a CSS attribute context"); } emitAttributeContextParameterExpression(logger, htmlContext, formalParameterName, parameterType); break; case URL_ATTRIBUTE_START: case URL_ATTRIBUTE_ENTIRE: /* * We already checked if the user tried to use SafeUri in an invalid * (non-URL_ATTRIBUTE) context, but now we check if the user could have * used SafeUri in the current context. */ if (!isSafeUri(parameterType)) { // Warn against using unsafe parameters in a URL attribute context. logger.log(TreeLogger.INFO, "Template with variable in URL attribute context: The template code generator will" + " sanitize the URL. Use " + SAFE_URI_CN + " to specify arguments in a URL attribute context that should not be" + " sanitized."); } emitAttributeContextParameterExpression(logger, htmlContext, formalParameterName, parameterType); break; case ATTRIBUTE_VALUE: emitAttributeContextParameterExpression(logger, htmlContext, formalParameterName, parameterType); break; default: throw error(logger, "unknown HTML context for formal template parameter " + formalParameterName + ": " + htmlContext); } println(");"); } /** * Emits a string literal. * * @param str the {@link String} to emit as a literal */ private void emitStringLiteral(String str) { print("sb.append("); print(wrap(str)); println(");"); } /** * Emits an expression corresponding to a template variable in "inner text" * context. * *

The expression emitted applies appropriate escaping to the parameter's * value depending the Java type of the corresponding template method * parameter: * *

    *
  • If the parameter is of a primitive (e.g., numeric, boolean) type, or * of type {@link SafeHtml}, it is emitted as is, without escaping. *
  • Otherwise, an expression that passes the parameter's value through * {@link SafeHtmlUtils#htmlEscape(String)} is emitted. If the value is * of type {@link SafeUri}, it is converted to string using * {@link SafeUri#asString()}. *
* * @param formalParameterName the name of the template method's formal * parameter corresponding to the expression being emitted * @param parameterType the Java type of the corresponding template method's * parameter */ private void emitTextContextParameterExpression(String formalParameterName, JType parameterType) { boolean parameterIsPrimitiveType = (parameterType.isPrimitive() != null); boolean parameterIsNotStringTyped = !(JAVA_LANG_STRING_FQCN.equals(parameterType.getQualifiedSourceName())); if (isSafeHtml(parameterType)) { // The parameter is of type SafeHtml and its wrapped string can // therefore be emitted safely without escaping. print(formalParameterName + ".asString()"); } else if (parameterIsPrimitiveType) { // The string representations of primitive types never contain HTML // special characters and can therefore be emitted without escaping. print(formalParameterName); } else { // The parameter is of some other type, and its value must be HTML // escaped. Furthermore, unless the parameter's type is {@link String}, // it must be explicitly converted to {@link String}. String expression = formalParameterName; if (parameterIsNotStringTyped) { expression = "String.valueOf(" + expression + ")"; } print(SAFE_HTML_UTILS_FQCN + ".htmlEscape(" + expression + ")"); } } /** * Check if the specified parameter type represents a {@link SafeHtml}. * * @param parameterType the Java parameter type * @return true if the type represents a {@link SafeHtml} */ private boolean isSafeHtml(JType parameterType) { return parameterType.getQualifiedSourceName().equals(SAFE_HTML_FQCN); } /** * Check if the specified parameter type represents a {@link SafeStyles}. * * @param parameterType the Java parameter type * @return true if the type represents a {@link SafeStyles} */ private boolean isSafeStyles(JType parameterType) { return parameterType.getQualifiedSourceName().equals(SAFE_STYLES_FQCN); } /** * Check if the specified parameter type represents a {@link SafeUri}. * * @param parameterType the Java parameter type * @return true if the type represents a {@link SafeUri} */ private boolean isSafeUri(JType parameterType) { return parameterType.getQualifiedSourceName().equals(SAFE_URI_FQCN); } }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy