com.google.gwt.safecss.shared.SafeStylesBuilder Maven / Gradle / Ivy
/*
* Copyright 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.gwt.safecss.shared;
/**
* A builder that facilitates the building up of XSS-safe CSS attribute strings
* from {@link SafeStyles}. It is used essentially like a {@link StringBuilder},
* but access {@link SafeStyles} instead of Strings.
*
*
* The accumulated XSS-safe {@link SafeStyles} can be obtained in the form of a
* {@link SafeStyles} via the {@link #toSafeStyles()} method.
*
*
* This class is not thread-safe.
*/
public final class SafeStylesBuilder {
private final StringBuilder sb = new StringBuilder();
/**
* Constructs an empty {@link SafeStylesBuilder}.
*/
public SafeStylesBuilder() {
}
/**
* Appends the contents of another {@link SafeStyles} object, without applying
* any escaping or sanitization to it.
*
* @param styles the {@link SafeStyles} to append
* @return a reference to this object
*/
public SafeStylesBuilder append(SafeStyles styles) {
sb.append(styles.asString());
return this;
}
/**
*
* Appends {@link SafeStyles} constructed from a trusted string, i.e., without
* escaping the string. Only minimal checks are performed. The calling code
* should be carefully reviewed to ensure the argument meets the
* {@link SafeStyles} contract.
*
*
* Generally, {@link SafeStyles} should be of the form
* {@code cssPropertyName:value;}, where neither the name nor the value
* contain malicious scripts.
*
*
* {@link SafeStyles} may never contain literal angle brackets. Otherwise, it
* could be unsafe to place a {@link SafeStyles} into a <style> tag
* (where it can't be HTML escaped). For example, if the {@link SafeStyles}
* containing "
* font: 'foo <style><script>evil</script>'" is
* used in a style sheet in a <style> tag, this could then break out of
* the style context into HTML.
*
*
* The following example values comply with this type's contract:
*
* width: 1em;height:1em;width: 1em;height: 1em;background:url('http://url');
* In addition, the empty string is safe for use in a CSS attribute.
*
*
* The following example values do not comply with this type's contract:
*
* background: red (missing a trailing semi-colon)background: (missing a value and a trailing semi-colon)1em (missing an attribute name, which provides context for the value)
*
* @param styles the input String
* @return a {@link SafeStyles} instance
*/
public SafeStylesBuilder appendTrustedString(String styles) {
SafeStylesUtils.verifySafeStylesConstraints(styles);
sb.append(styles);
return this;
}
/**
* Returns the safe CSS properties accumulated in the builder as a
* {@link SafeStyles}.
*
* @return a {@link SafeStyles} instance
*/
public SafeStyles toSafeStyles() {
return new SafeStylesString(sb.toString());
}
}