Package com.google.gwt.safecss.shared

Class SafeStylesBuilder

java.lang.Object

com.google.gwt.safecss.shared.SafeStylesBuilder

public final class SafeStylesBuilder
extends java.lang.Object

A builder that facilitates the building up of XSS-safe CSS attribute strings from SafeStyles. It is used essentially like a StringBuilder, but access SafeStyles instead of Strings.

The accumulated XSS-safe SafeStyles can be obtained in the form of a SafeStyles via the toSafeStyles() method.

This class is not thread-safe.

Constructor Summary

Constructors

Constructor	Description
SafeStylesBuilder()	Constructs an empty SafeStylesBuilder.

Method Summary

Modifier and Type	Method	Description
SafeStylesBuilder	append(SafeStyles styles)	Appends the contents of another SafeStyles object, without applying any escaping or sanitization to it.
SafeStylesBuilder	appendTrustedString(java.lang.String styles)	Appends SafeStyles constructed from a trusted string, i.e., without escaping the string.
SafeStylesBuilder	backgroundImage(SafeUri uri)	Append the background-image CSS property.
SafeStylesBuilder	borderStyle(Style.BorderStyle value)	Append the border-style CSS property.
SafeStylesBuilder	borderWidth(double value, Style.Unit unit)	Append the border-width css property.
SafeStylesBuilder	bottom(double value, Style.Unit unit)	Append the bottom css property.
SafeStylesBuilder	clear(Style.Clear value)	Append the 'clear' CSS property.
SafeStylesBuilder	cursor(Style.Cursor value)	Append the cursor CSS property.
SafeStylesBuilder	display(Style.Display value)	Append the display CSS property.
SafeStylesBuilder	floatprop(Style.Float value)	Append the float css property.
SafeStylesBuilder	fontSize(double value, Style.Unit unit)	Append the font-size css property.
SafeStylesBuilder	fontStyle(Style.FontStyle value)	Append the font-style CSS property.
SafeStylesBuilder	fontWeight(Style.FontWeight value)	Append the font-weight CSS property.
SafeStylesBuilder	height(double value, Style.Unit unit)	Append the height css property.
SafeStylesBuilder	left(double value, Style.Unit unit)	Append the left css property.
SafeStylesBuilder	listStyleType(Style.ListStyleType value)	Append the list-style-type CSS property.
SafeStylesBuilder	margin(double value, Style.Unit unit)	Append the margin css property.
SafeStylesBuilder	marginBottom(double value, Style.Unit unit)	Append the margin-bottom css property.
SafeStylesBuilder	marginLeft(double value, Style.Unit unit)	Append the margin-left css property.
SafeStylesBuilder	marginRight(double value, Style.Unit unit)	Append the margin-right css property.
SafeStylesBuilder	marginTop(double value, Style.Unit unit)	Append the margin-top css property.
SafeStylesBuilder	opacity(double value)	Append the opacity css property.
SafeStylesBuilder	overflow(Style.Overflow value)	Append the overflow CSS property.
SafeStylesBuilder	overflowX(Style.Overflow value)	Append the overflow-x CSS property.
SafeStylesBuilder	overflowY(Style.Overflow value)	Append the overflow-y CSS property.
SafeStylesBuilder	padding(double value, Style.Unit unit)	Append the padding css property.
SafeStylesBuilder	paddingBottom(double value, Style.Unit unit)	Append the padding-bottom css property.
SafeStylesBuilder	paddingLeft(double value, Style.Unit unit)	Append the padding-left css property.
SafeStylesBuilder	paddingRight(double value, Style.Unit unit)	Append the padding-right css property.
SafeStylesBuilder	paddingTop(double value, Style.Unit unit)	Append the padding-top css property.
SafeStylesBuilder	position(Style.Position value)	Append the position CSS property.
SafeStylesBuilder	right(double value, Style.Unit unit)	Append the right css property.
SafeStylesBuilder	tableLayout(Style.TableLayout value)	Append the table-layout CSS property.
SafeStylesBuilder	textAlign(Style.TextAlign value)	Append the 'text-align' CSS property.
SafeStylesBuilder	textDecoration(Style.TextDecoration value)	Append the text-decoration CSS property.
SafeStylesBuilder	textIndent(double value, Style.Unit unit)	Append the 'text-indent' CSS property.
SafeStylesBuilder	textJustify(Style.TextJustify value)	Append the 'text-justify' CSS3 property.
SafeStylesBuilder	textOverflow(Style.TextOverflow value)	Append the 'text-overflow' CSS3 property.
SafeStylesBuilder	textTransform(Style.TextTransform value)	Append the 'text-transform' CSS property.
SafeStylesBuilder	top(double value, Style.Unit unit)	Append the top css property.
SafeStyles	toSafeStyles()	Returns the safe CSS properties accumulated in the builder as a SafeStyles.
SafeStylesBuilder	trustedBackgroundColor(java.lang.String value)	Append the trusted background color, i.e., without escaping the value.
SafeStylesBuilder	trustedBackgroundImage(java.lang.String value)	Append the trusted background image, i.e., without escaping the value.
SafeStylesBuilder	trustedBorderColor(java.lang.String value)	Append the trusted border color, i.e., without escaping the value.
SafeStylesBuilder	trustedColor(java.lang.String value)	Append the trusted font color, i.e., without escaping the value.
SafeStylesBuilder	trustedNameAndValue(java.lang.String name, double value, Style.Unit unit)	Append a SafeStyles constructed from a trusted name and a trusted value, i.e., without escaping the name and value.
SafeStylesBuilder	trustedNameAndValue(java.lang.String name, java.lang.String value)	Append a SafeStyles constructed from a trusted name and a trusted value, i.e., without escaping the name and value.
SafeStylesBuilder	verticalAlign(double value, Style.Unit unit)	Append the vertical-align CSS property.
SafeStylesBuilder	verticalAlign(Style.VerticalAlign value)	Append the vertical-align CSS property.
SafeStylesBuilder	visibility(Style.Visibility value)	Append the visibility CSS property.
SafeStylesBuilder	whiteSpace(Style.WhiteSpace whiteSpace)	Append the 'white-space' CSS property.
SafeStylesBuilder	width(double value, Style.Unit unit)	Append the width css property.
SafeStylesBuilder	zIndex(int value)	Append the z-index css property.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SafeStylesBuilder

public SafeStylesBuilder()

Constructs an empty SafeStylesBuilder.

Method Detail

append

public SafeStylesBuilder append(SafeStyles styles)

Appends the contents of another SafeStyles object, without applying any escaping or sanitization to it.

Parameters:

styles - the SafeStyles to append

Returns:

a reference to this object

appendTrustedString

public SafeStylesBuilder appendTrustedString(java.lang.String styles)

Appends 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 SafeStyles contract.

Generally, SafeStyles should be of the form cssPropertyName:value;, where neither the name nor the value contain malicious scripts.

SafeStyles may never contain literal angle brackets. Otherwise, it could be unsafe to place a SafeStyles into a <style> tag (where it can't be HTML escaped). For example, if the 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)

Parameters:

styles - the input String

Returns:

a SafeStyles instance

backgroundImage

public SafeStylesBuilder backgroundImage(SafeUri uri)

Append the background-image CSS property.

Parameters:

uri - the URI of the background image

See Also:

trustedBackgroundImage(String)

borderStyle

public SafeStylesBuilder borderStyle(Style.BorderStyle value)

Append the border-style CSS property.

borderWidth

public SafeStylesBuilder borderWidth(double value,
                                     Style.Unit unit)

Append the border-width css property.

bottom

public SafeStylesBuilder bottom(double value,
                                Style.Unit unit)

Append the bottom css property.

clear

public SafeStylesBuilder clear(Style.Clear value)

Append the 'clear' CSS property.

cursor

public SafeStylesBuilder cursor(Style.Cursor value)

Append the cursor CSS property.

display

public SafeStylesBuilder display(Style.Display value)

Append the display CSS property.

floatprop

public SafeStylesBuilder floatprop(Style.Float value)

Append the float css property.

Note: This method has the suffix "prop" to avoid Java compilation errors. The term "float" is a reserved word in Java representing the primitive float.

fontSize

public SafeStylesBuilder fontSize(double value,
                                  Style.Unit unit)

Append the font-size css property.

fontStyle

public SafeStylesBuilder fontStyle(Style.FontStyle value)

Append the font-style CSS property.

fontWeight

public SafeStylesBuilder fontWeight(Style.FontWeight value)

Append the font-weight CSS property.

height

public SafeStylesBuilder height(double value,
                                Style.Unit unit)

Append the height css property.

left

public SafeStylesBuilder left(double value,
                              Style.Unit unit)

Append the left css property.

listStyleType

public SafeStylesBuilder listStyleType(Style.ListStyleType value)

Append the list-style-type CSS property.

margin

public SafeStylesBuilder margin(double value,
                                Style.Unit unit)

Append the margin css property.

marginBottom

public SafeStylesBuilder marginBottom(double value,
                                      Style.Unit unit)

Append the margin-bottom css property.

marginLeft

public SafeStylesBuilder marginLeft(double value,
                                    Style.Unit unit)

Append the margin-left css property.

marginRight

public SafeStylesBuilder marginRight(double value,
                                     Style.Unit unit)

Append the margin-right css property.

marginTop

public SafeStylesBuilder marginTop(double value,
                                   Style.Unit unit)

Append the margin-top css property.

opacity

public SafeStylesBuilder opacity(double value)

Append the opacity css property.

overflow

public SafeStylesBuilder overflow(Style.Overflow value)

Append the overflow CSS property.

overflowX

public SafeStylesBuilder overflowX(Style.Overflow value)

Append the overflow-x CSS property.

overflowY

public SafeStylesBuilder overflowY(Style.Overflow value)

Append the overflow-y CSS property.

padding

public SafeStylesBuilder padding(double value,
                                 Style.Unit unit)

Append the padding css property.

paddingBottom

public SafeStylesBuilder paddingBottom(double value,
                                       Style.Unit unit)

Append the padding-bottom css property.

paddingLeft

public SafeStylesBuilder paddingLeft(double value,
                                     Style.Unit unit)

Append the padding-left css property.

paddingRight

public SafeStylesBuilder paddingRight(double value,
                                      Style.Unit unit)

Append the padding-right css property.

paddingTop

public SafeStylesBuilder paddingTop(double value,
                                    Style.Unit unit)

Append the padding-top css property.

position

public SafeStylesBuilder position(Style.Position value)

Append the position CSS property.

right

public SafeStylesBuilder right(double value,
                               Style.Unit unit)

Append the right css property.

tableLayout

public SafeStylesBuilder tableLayout(Style.TableLayout value)

Append the table-layout CSS property.

textAlign

public SafeStylesBuilder textAlign(Style.TextAlign value)

Append the 'text-align' CSS property.

textDecoration

public SafeStylesBuilder textDecoration(Style.TextDecoration value)

Append the text-decoration CSS property.

textIndent

public SafeStylesBuilder textIndent(double value,
                                    Style.Unit unit)

Append the 'text-indent' CSS property.

textJustify

public SafeStylesBuilder textJustify(Style.TextJustify value)

Append the 'text-justify' CSS3 property.

textOverflow

public SafeStylesBuilder textOverflow(Style.TextOverflow value)

Append the 'text-overflow' CSS3 property.

textTransform

public SafeStylesBuilder textTransform(Style.TextTransform value)

Append the 'text-transform' CSS property.

top

public SafeStylesBuilder top(double value,
                             Style.Unit unit)

Append the top css property.

toSafeStyles

public SafeStyles toSafeStyles()

Returns the safe CSS properties accumulated in the builder as a SafeStyles.

Returns:

a SafeStyles instance

trustedBackgroundColor

public SafeStylesBuilder trustedBackgroundColor(java.lang.String value)

Append the trusted background color, i.e., without escaping the value. No checks are performed. The calling code should be carefully reviewed to ensure the argument will satisfy the SafeStyles contract when they are composed into the form: "<name>:<value>;".

SafeStyles may never contain literal angle brackets. Otherwise, it could be unsafe to place a SafeStyles into a <style> tag (where it can't be HTML escaped). For example, if the 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.

Parameters:

value - the property value

Returns:

a SafeStyles instance

trustedBackgroundImage

public SafeStylesBuilder trustedBackgroundImage(java.lang.String value)

Append the trusted background image, i.e., without escaping the value. No checks are performed. The calling code should be carefully reviewed to ensure the argument will satisfy the SafeStyles contract when they are composed into the form: "<name>:<value>;".

SafeStyles may never contain literal angle brackets. Otherwise, it could be unsafe to place a SafeStyles into a <style> tag (where it can't be HTML escaped). For example, if the 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.

Parameters:

value - the property value

Returns:

a SafeStyles instance

See Also:

backgroundImage(SafeUri)

trustedBorderColor

public SafeStylesBuilder trustedBorderColor(java.lang.String value)

Append the trusted border color, i.e., without escaping the value. No checks are performed. The calling code should be carefully reviewed to ensure the argument will satisfy the SafeStyles contract when they are composed into the form: "<name>:<value>;".

SafeStyles may never contain literal angle brackets. Otherwise, it could be unsafe to place a SafeStyles into a <style> tag (where it can't be HTML escaped). For example, if the 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.

Parameters:

value - the property value

Returns:

a SafeStyles instance

trustedColor

public SafeStylesBuilder trustedColor(java.lang.String value)

Append the trusted font color, i.e., without escaping the value. No checks are performed. The calling code should be carefully reviewed to ensure the argument will satisfy the SafeStyles contract when they are composed into the form: "<name>:<value>;".

SafeStyles may never contain literal angle brackets. Otherwise, it could be unsafe to place a SafeStyles into a <style> tag (where it can't be HTML escaped). For example, if the 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.

Parameters:

value - the property value

Returns:

a SafeStyles instance

trustedNameAndValue

public SafeStylesBuilder trustedNameAndValue(java.lang.String name,
                                             double value,
                                             Style.Unit unit)

Append a SafeStyles constructed from a trusted name and a trusted value, i.e., without escaping the name and value. No checks are performed. The calling code should be carefully reviewed to ensure the argument will satisfy the SafeStyles contract when they are composed into the form: "<name>:<value>;".

SafeStyles may never contain literal angle brackets. Otherwise, it could be unsafe to place a SafeStyles into a <style> tag (where it can't be HTML escaped). For example, if the 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 name should be in hyphenated format, not camelCase format.

Parameters:

name - the property name

value - the property value

Returns:

a SafeStyles instance

trustedNameAndValue

public SafeStylesBuilder trustedNameAndValue(java.lang.String name,
                                             java.lang.String value)

Append a SafeStyles constructed from a trusted name and a trusted value, i.e., without escaping the name and value. No checks are performed. The calling code should be carefully reviewed to ensure the argument will satisfy the SafeStyles contract when they are composed into the form: "<name>:<value>;".

SafeStyles may never contain literal angle brackets. Otherwise, it could be unsafe to place a SafeStyles into a <style> tag (where it can't be HTML escaped). For example, if the 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 name should be in hyphenated format, not camelCase format.

Parameters:

name - the property name

value - the property value

Returns:

a SafeStyles instance

verticalAlign

public SafeStylesBuilder verticalAlign(double value,
                                       Style.Unit unit)

Append the vertical-align CSS property.

verticalAlign

public SafeStylesBuilder verticalAlign(Style.VerticalAlign value)

Append the vertical-align CSS property.

visibility

public SafeStylesBuilder visibility(Style.Visibility value)

Append the visibility CSS property.

whiteSpace

public SafeStylesBuilder whiteSpace(Style.WhiteSpace whiteSpace)

Append the 'white-space' CSS property.

width

public SafeStylesBuilder width(double value,
                               Style.Unit unit)

Append the width css property.

zIndex

public SafeStylesBuilder zIndex(int value)

Append the z-index css property.