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

com.google.gwt.safehtml.shared.SafeHtmlBuilder Maven / Gradle / Ivy

There is a newer version: 2.10.0
Show newest version
/*
 * Copyright 2010 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.shared;

/**
 * A builder that facilitates the building up of XSS-safe HTML from text
 * snippets. It is used essentially like a {@link StringBuilder}; unlike a
 * {@link StringBuilder}, it automatically HTML-escapes appended input where
 * necessary.
 *
 * 

* In addition, it supports methods that allow strings with HTML markup to be * appended without escaping: One can append other {@link SafeHtml} objects, and * one can append constant strings. The method that appends constant strings * ({@link #appendHtmlConstant(String)}) requires a convention of use to be * adhered to in order for this class to adhere to the contract required by * {@link SafeHtml}: The argument expression must be fully determined and known * to be safe at compile time, and the value of the argument must not contain * incomplete HTML tags. See {@link #appendHtmlConstant(String)} for details. * *

* The accumulated XSS-safe HTML can be obtained in the form of a * {@link SafeHtml} via the {@link #toSafeHtml()} method. * *

* This class is not thread-safe. */ public final class SafeHtmlBuilder { private final StringBuilder sb = new StringBuilder(); /** * Constructs an empty SafeHtmlBuilder. */ public SafeHtmlBuilder() { } /* * Boolean and numeric types converted to String are always HTML safe -- no * escaping necessary. */ /** * Appends the string representation of a boolean. * * @param b the boolean whose string representation to append * @return a reference to this object */ public SafeHtmlBuilder append(boolean b) { sb.append(b); return this; } /** * Appends the string representation of a number. * * @param num the number whose string representation to append * @return a reference to this object */ public SafeHtmlBuilder append(byte num) { sb.append(num); return this; } /** * Appends the string representation of a char. * * @param c the character whose string representation to append * @return a reference to this object * @see SafeHtmlUtils#htmlEscape(char) */ public SafeHtmlBuilder append(char c) { sb.append(SafeHtmlUtils.htmlEscape(c)); return this; } /** * Appends the string representation of a number. * * @param num the number whose string representation to append * @return a reference to this object */ public SafeHtmlBuilder append(double num) { sb.append(num); return this; } /** * Appends the string representation of a number. * * @param num the number whose string representation to append * @return a reference to this object */ public SafeHtmlBuilder append(float num) { sb.append(num); return this; } /** * Appends the string representation of a number. * * @param num the number whose string representation to append * @return a reference to this object */ public SafeHtmlBuilder append(int num) { sb.append(num); return this; } /** * Appends the string representation of a number. * * @param num the number whose string representation to append * @return a reference to this object */ public SafeHtmlBuilder append(long num) { sb.append(num); return this; } /** * Appends the contents of another {@link SafeHtml} object, without applying * HTML-escaping to it. * * @param html the {@link SafeHtml} to append * @return a reference to this object */ public SafeHtmlBuilder append(SafeHtml html) { sb.append(html.asString()); return this; } /** * Appends a string after HTML-escaping it. * * @param text the string to append * @return a reference to this object * @see SafeHtmlUtils#htmlEscape(String) */ public SafeHtmlBuilder appendEscaped(String text) { sb.append(SafeHtmlUtils.htmlEscape(text)); return this; } /** * Appends a string consisting of several newline-separated lines after * HTML-escaping it. Newlines in the original string are converted to {@code *
} tags. * * @param text the string to append * @return a reference to this object * @see SafeHtmlUtils#htmlEscape(String) */ public SafeHtmlBuilder appendEscapedLines(String text) { sb.append(SafeHtmlUtils.htmlEscape(text).replaceAll("\n", "
")); return this; } /** * Appends a compile-time-constant string, which will not be escaped. * *

* Important: For this class to be able to honor its contract as * required by {@link SafeHtml}, all uses of this method must satisfy the * following constraints: * *

    * *
  1. The argument expression must be fully determined at compile time. * *
  2. The value of the argument must end in "inner HTML" context and not * contain incomplete HTML tags. I.e., the following is not a correct use of * this method, because the {@code } tag is incomplete: * *
       * {@code shb.appendHtmlConstant("


© 2015 - 2024 Weber Informatics LLC | Privacy Policy