org.apache.click.util
Class HtmlStringBuffer

java.lang.Object
  org.apache.click.util.HtmlStringBuffer

public class HtmlStringBuffer
extends Object

Provides a HTML element StringBuffer for rendering, automatically escaping string values. HtmlStringBuffer is used by Click controls for HTML rendering.

For example the following code:

 public String toString() {
     HtmlStringBuffer buffer = new HtmlStringBuffer();

     buffer.elementStart("input");
     buffer.appendAttribute("type", "text");
     buffer.appendAttribute("name", getName());
     buffer.appendAttribute("value", getValue());
     buffer.elementEnd();

     return buffer.toString();
 } 

Would render:

 <input type="text" name="address" value="23 Holt's Street"/> 

Synchronization

To improve performance in Click's thread safe environment this class does not synchronize append operations. Internally this class uses a character buffer adapted from the JDK 1.5 AbstractStringBuilder.

Field Summary

protected char[]	characters The character storage array.
protected int	count The count is the number of characters used.

Constructor Summary

HtmlStringBuffer()
Create a new HTML StringBuffer with an initial capacity of 128 characters.

HtmlStringBuffer(int length)
Create a new HTML StringBuffer with the specified initial capacity.

Method Summary

HtmlStringBuffer	append(char value) Append the char value to the buffer.
HtmlStringBuffer	append(double value) Append the double value to the buffer.
HtmlStringBuffer	append(int value) Append the integer value to the buffer.
HtmlStringBuffer	append(long value) Append the long value to the buffer.
HtmlStringBuffer	append(Object value) Append the raw object value of the given object to the buffer.
HtmlStringBuffer	append(String value) Append the raw string value of the given object to the buffer.
HtmlStringBuffer	appendAttribute(String name, int value) Append the given HTML attribute name and value to the string buffer.
HtmlStringBuffer	appendAttribute(String name, Object value) Append the given HTML attribute name and value to the string buffer, and do not escape the attribute value.
HtmlStringBuffer	appendAttributeDisabled() Append the HTML "disabled" attribute to the string buffer.
HtmlStringBuffer	appendAttributeEscaped(String name, Object value) Append the given attribute name and value to the buffer, if the value is not null.
HtmlStringBuffer	appendAttributeReadonly() Append the HTML "readonly" attribute to the string buffer.
HtmlStringBuffer	appendAttributes(Map<String,String> attributes) Append the given map of attribute names and values to the string buffer.
HtmlStringBuffer	appendEscaped(Object value) Append the given value to the buffer and escape its value.
HtmlStringBuffer	appendStyleAttributes(Map<String,String> attributes) Append the given map of CSS style name and value pairs as a style attribute to the string buffer.
HtmlStringBuffer	closeTag() Append a HTML element end to the string buffer.
HtmlStringBuffer	elementEnd() Append a HTML element end to the string buffer.
HtmlStringBuffer	elementEnd(String name) Append a HTML element end to the string buffer.
HtmlStringBuffer	elementStart(String name) Append a HTML element start to the string buffer.
protected void	expandCapacity(int minimumCapacity) Ensures that the capacity is at least equal to the specified minimum.
boolean	isJavaScriptAttribute(String name) Return true if the given attribute name is a JavaScript attribute, or false otherwise.
int	length() Return the length of the string buffer.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

characters

protected char[] characters

The character storage array.

count

protected int count

The count is the number of characters used.

Constructor Detail

HtmlStringBuffer

public HtmlStringBuffer(int length)

Create a new HTML StringBuffer with the specified initial capacity.

Parameters:

length - the initial capacity

HtmlStringBuffer

public HtmlStringBuffer()

Create a new HTML StringBuffer with an initial capacity of 128 characters.

Method Detail

append

public HtmlStringBuffer append(double value)

Append the double value to the buffer.

Parameters:

value - the double value to append

Returns:

a reference to this HtmlStringBuffer object

append

public HtmlStringBuffer append(char value)

Append the char value to the buffer.

Parameters:

value - the char value to append

Returns:

a reference to this HtmlStringBuffer object

append

public HtmlStringBuffer append(int value)

Append the integer value to the buffer.

Parameters:

value - the integer value to append

Returns:

a reference to this HtmlStringBuffer object

append

public HtmlStringBuffer append(long value)

Append the long value to the buffer.

Parameters:

value - the long value to append

Returns:

a reference to this HtmlStringBuffer object

append

public HtmlStringBuffer append(Object value)

Append the raw object value of the given object to the buffer.

Parameters:

value - the object value to append

Returns:

a reference to this HtmlStringBuffer object

append

public HtmlStringBuffer append(String value)

Append the raw string value of the given object to the buffer.

Parameters:

value - the string value to append

Returns:

a reference to this HtmlStringBuffer object

appendEscaped

public HtmlStringBuffer appendEscaped(Object value)

Append the given value to the buffer and escape its value. The following characters are escaped: <, >, ", ', &.

Parameters:

value - the object value to append

Returns:

a reference to this HtmlStringBuffer object

Throws:

IllegalArgumentException - if the value is null

appendAttribute

public HtmlStringBuffer appendAttribute(String name,
                                        Object value)

Append the given HTML attribute name and value to the string buffer, and do not escape the attribute value.

For example:

    appendAttribute("size", 10)  ->  size="10" 

Parameters:

name - the HTML attribute name

value - the HTML attribute value

Returns:

a reference to this HtmlStringBuffer object

Throws:

IllegalArgumentException - if name is null

appendAttributeEscaped

public HtmlStringBuffer appendAttributeEscaped(String name,
                                               Object value)

Append the given attribute name and value to the buffer, if the value is not null.

For example:

    appendAttribute("class", "required")  ->  class="required" 

The attribute value will be escaped. The following characters are escaped: <, >, ", ', &.

If the attribute name is a JavaScript event handler the value will not be escaped.

Parameters:

name - the HTML attribute name

value - the object value to append

Returns:

a reference to this HtmlStringBuffer object

Throws:

IllegalArgumentException - if name is null

appendAttribute

public HtmlStringBuffer appendAttribute(String name,
                                        int value)

Append the given HTML attribute name and value to the string buffer.

For example:

    appendAttribute("size", 10)  ->  size="10" 

Parameters:

name - the HTML attribute name

value - the HTML attribute value

Returns:

a reference to this HtmlStringBuffer object

Throws:

IllegalArgumentException - if name is null

appendAttributeDisabled

public HtmlStringBuffer appendAttributeDisabled()

Append the HTML "disabled" attribute to the string buffer.

For example:

    appendAttributeDisabled()  ->  disabled="disabled" 

Returns:

a reference to this HtmlStringBuffer object

appendAttributeReadonly

public HtmlStringBuffer appendAttributeReadonly()

Append the HTML "readonly" attribute to the string buffer.

For example:

    appendAttributeReadonly()  ->  readonly="readonly" 

Returns:

a reference to this HtmlStringBuffer object

appendAttributes

public HtmlStringBuffer appendAttributes(Map<String,String> attributes)

Append the given map of attribute names and values to the string buffer.

Parameters:

attributes - the map of attribute names and values

Returns:

a reference to this HtmlStringBuffer object

Throws:

IllegalArgumentException - if attributes is null

appendStyleAttributes

public HtmlStringBuffer appendStyleAttributes(Map<String,String> attributes)

Append the given map of CSS style name and value pairs as a style attribute to the string buffer.

Parameters:

attributes - the map of CSS style names and values

Returns:

a reference to this HtmlStringBuffer object

Throws:

IllegalArgumentException - if attributes is null

elementEnd

public HtmlStringBuffer elementEnd(String name)

Append a HTML element end to the string buffer.

For example:

    elementEnd("textarea")  ->  </textarea> 

Parameters:

name - the HTML element name to end

Returns:

a reference to this HtmlStringBuffer object

Throws:

IllegalArgumentException - if name is null

closeTag

public HtmlStringBuffer closeTag()

Append a HTML element end to the string buffer.

For example:

    closeTag()  ->  > 

Returns:

a reference to this HtmlStringBuffer object

elementEnd

public HtmlStringBuffer elementEnd()

Append a HTML element end to the string buffer.

For example:

    elementEnd()  ->  /> 

Returns:

a reference to this HtmlStringBuffer object

elementStart

public HtmlStringBuffer elementStart(String name)

Append a HTML element start to the string buffer.

For example:

    elementStart("input")  ->  <input 

Parameters:

name - the HTML element name to start

Returns:

a reference to this HtmlStringBuffer object

isJavaScriptAttribute

public boolean isJavaScriptAttribute(String name)

Return true if the given attribute name is a JavaScript attribute, or false otherwise.

Parameters:

name - the HTML attribute name to test

Returns:

true if the HTML attribute is a JavaScript attribute

length

public int length()

Return the length of the string buffer.

Returns:

the length of the string buffer

toString

public String toString()

Overrides:

toString in class Object

Returns:

a string representation of the string buffer

See Also:

Object.toString()

expandCapacity

protected void expandCapacity(int minimumCapacity)

Ensures that the capacity is at least equal to the specified minimum. If the current capacity is less than the argument, then a new internal array is allocated with greater capacity. The new capacity is the larger of:

• The minimumCapacity argument.
• Twice the old capacity, plus 2.

If the minimumCapacity argument is non-positive, this method takes no action and simply returns.

Parameters:

minimumCapacity - the minimum desired capacity