org.apache.click.util
Class HtmlStringBuffer

java.lang.Object
  extended by 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: If the minimumCapacity argument is non-positive, this method takes no action and simply returns.

Parameters:
minimumCapacity - the minimum desired capacity