/*
* 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.
*
* <p>
* 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.
*
* <p>
* The accumulated XSS-safe HTML can be obtained in the form of a
* {@link SafeHtml} via the {@link #toSafeHtml()} method.
*
* <p>
* 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
* <br>} 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", "<br>"));
return this;
}
/**
* Appends a compile-time-constant string, which will <em>not</em> be escaped.
*
* <p>
* <b>Important</b>: 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:
*
* <ol>
*
* <li>The argument expression must be fully determined at compile time.
*
* <li>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 <a>} tag is incomplete:
*
* <pre class="code">
* {@code shb.appendConstantHtml("<a href='").append(url)}</pre>
*
* </ol>
*
* <p>
* The first constraint provides a sufficient condition that the appended
* string (and any HTML markup contained in it) originates from a trusted
* source. The second constraint ensures the composability of {@link SafeHtml}
* values.
*
* <p>
* When executing client-side in Development Mode, or server side with
* assertions enabled, the argument is HTML-parsed and validated to satisfy
* the second constraint (the server-side check can also be enabled
* programmatically, see
* {@link SafeHtmlHostedModeUtils#maybeCheckCompleteHtml(String)} for
* details). For performance reasons, this check is not performed in prod mode
* on the client, and with assertions disabled on the server.
*
* @param html the HTML snippet to be appended
* @return a reference to this object
* @throws IllegalArgumentException if not running in prod mode and {@code
* html} violates the second constraint
*/
public SafeHtmlBuilder appendHtmlConstant(String html) {
SafeHtmlHostedModeUtils.maybeCheckCompleteHtml(html);
sb.append(html);
return this;
}
/**
* Returns the safe HTML accumulated in the builder as a {@link SafeHtml}.
*
* @return a SafeHtml instance
*/
public SafeHtml toSafeHtml() {
return new SafeHtmlString(sb.toString());
}
}