org.apache.tapestry
Interface IMarkupWriter

All Known Subinterfaces:

NestedMarkupWriter

All Known Implementing Classes:

MarkupWriterImpl, NestedMarkupWriterImpl, NullWriter

public interface IMarkupWriter

Defines an object that can write markup (XML, HTML, XHTML) style output. A IMarkupWriter handles translation from unicode to the markup language (escaping characters such as '<' and '>' to their entity equivalents, '&lt;' and '&gt;') as well as assisting with nested elements, closing tags, etc.

Author:

Howard Ship, David Solis

Method Summary

void	appendAttribute(String name, boolean value) Appends a boolean attribute into the currently open tag.
void	appendAttribute(String name, int value) Appends an integer attribute to the current attribute with a matching name key, if one exists.
void	appendAttribute(String name, String value) Appends an attribute into the most recently opened tag.
void	appendAttributeRaw(String name, String value) Similar to attribute(String, String) but no escaping of invalid elements is done for the value.
void	attribute(String name, boolean value) Writes a boolean attribute into the currently open tag.
void	attribute(String name, int value) Writes an integer attribute into the currently open tag.
void	attribute(String name, String value) Writes an attribute into the most recently opened tag.
void	attributeRaw(String name, String value) Similar to attribute(String, String)but no escaping of invalid elements is done for the value.
void	begin(String name) Closes any existing tag then starts a new element.
void	beginEmpty(String name) Starts an element that will not later be matched with an end() call.
boolean	checkError() Invokes checkError() on the PrintWriter used to format output.
void	clearAttributes() Removes all current attributes on the open tag, if any.
void	close() Closes this IMarkupWriter.
void	closeTag() Closes the most recently opened element by writing the '>' that ends it.
void	comment(String value) Writes an XML/HTML comment.
void	end() Ends the element most recently started by begin(String).
void	end(String name) Ends the most recently started element with the given name.
void	flush() Forwards flush() to this IMarkupWriter's PrintWriter.
Attribute	getAttribute(String name) Gets the attribute matching name from the current open tag, if it exists.
String	getContentType() Returns the type of content generated by this response writer, as a MIME type.
NestedMarkupWriter	getNestedWriter() Returns a nested writer, one that accumulates its changes in a buffer.
boolean	hasAttribute(String name) Checks if the current tag has an attribute keyed off of name.
void	print(char value) Prints a single character, or its equivalent entity.
void	print(char[] data, int offset, int length) Version of print(char[], int, int, boolean) that assumes filter is enabled.
void	print(char[] data, int offset, int length, boolean raw) The primary print() method, used by most other methods.
void	print(int value) Prints an integer.
void	print(String value) As with print(char[], int, int, boolean), but the data to print is defined by the String.
void	print(String value, boolean raw) As with print(char[], int, int, boolean), but the data to print is defined by the String.
void	println() Closes the open tag (if any), then prints a line seperator to the output stream.
void	printRaw(char[] buffer, int offset, int length) Version of print(char[], int, int, boolean)that assumes filter is enabled.
void	printRaw(String value) As with print(char[], int, int, boolean), but the data to print is defined by the String.
Attribute	removeAttribute(String name) Removes the attribute specified with a matching name if one exists.

Method Detail

attribute

void attribute(String name,
               int value)

Writes an integer attribute into the currently open tag.

Throws:

IllegalStateException - if there is no open tag.

attribute

void attribute(String name,
               boolean value)

Writes a boolean attribute into the currently open tag.

Throws:

IllegalStateException - if there is no open tag.

Since:

3.0

attribute

void attribute(String name,
               String value)

Writes an attribute into the most recently opened tag. This must be called after begin(String)and before any other kind of writing (which closes the tag).

The value may be null.

Throws:

IllegalStateException - if there is no open tag.

attributeRaw

void attributeRaw(String name,
                  String value)

Similar to attribute(String, String)but no escaping of invalid elements is done for the value.

Throws:

IllegalStateException - if there is no open tag.

Since:

3.0

appendAttribute

void appendAttribute(String name,
                     int value)

Appends an integer attribute to the current attribute with a matching name key, if one exists.

Throws:

IllegalStateException - if there is no open tag.

appendAttribute

void appendAttribute(String name,
                     boolean value)

Appends a boolean attribute into the currently open tag.

Throws:

IllegalStateException - if there is no open tag.

Since:

3.0

appendAttribute

void appendAttribute(String name,
                     String value)

Appends an attribute into the most recently opened tag. This must be called after begin(String) and before any other kind of writing (which closes the tag).

The value may be null.

Throws:

IllegalStateException - if there is no open tag.

appendAttributeRaw

void appendAttributeRaw(String name,
                        String value)

Similar to attribute(String, String) but no escaping of invalid elements is done for the value.

Throws:

IllegalStateException - if there is no open tag.

Since:

3.0

hasAttribute

boolean hasAttribute(String name)

Checks if the current tag has an attribute keyed off of name.

Parameters:

name - The name of the attribute to check for existance of.

Returns:

True if the attribute exists, false otherwise.

Throws:

IllegalStateException - If there is no open tag.

getAttribute

Attribute getAttribute(String name)

Gets the attribute matching name from the current open tag, if it exists.

Parameters:

name - The attribute to get the value of by name.

Returns:

The attribute value, or null if it doesn't exist.

Throws:

IllegalStateException - If there is no open tag.

removeAttribute

Attribute removeAttribute(String name)

Removes the attribute specified with a matching name if one exists.

Parameters:

name - The attribute to remove.

Returns:

The removed attribute, null if one didn't exist.

Throws:

IllegalStateException - If there is no open tag.

clearAttributes

void clearAttributes()

Removes all current attributes on the open tag, if any.

Throws:

IllegalStateException - If there is no open tag.

begin

void begin(String name)

Closes any existing tag then starts a new element. The new element is pushed onto the active element stack.

beginEmpty

void beginEmpty(String name)

Starts an element that will not later be matched with an end() call. This is useful for elements that do not need closing tags.

checkError

boolean checkError()

Invokes checkError() on the PrintWriter used to format output.

close

void close()

Closes this IMarkupWriter. Close tags are written for any active elements. The PrintWriter is then sent close(). A nested writer will commit its buffer to its containing writer.

closeTag

void closeTag()

Closes the most recently opened element by writing the '>' that ends it. Once this is invoked, the attribute() methods may not be used until a new element is opened with begin(String)or or beginEmpty(String).

comment

void comment(String value)

Writes an XML/HTML comment. Any open tag is first closed. The method takes care of providing the <!-- and -->, and provides a blank line after the close of the comment.

Most characters are valid inside a comment, so no check of the contents is made (much like printRaw(String).

end

void end()

Ends the element most recently started by begin(String). The name of the tag is popped off of the active element stack and used to form an HTML close tag.

end

void end(String name)

Ends the most recently started element with the given name. This will also end any other intermediate elements. This is very useful for easily ending a table or even an entire page.

flush

void flush()

Forwards flush() to this IMarkupWriter's PrintWriter.

getNestedWriter

NestedMarkupWriter getNestedWriter()

Returns a nested writer, one that accumulates its changes in a buffer. When the nested writer is closed, it writes its buffer of markup into its containing IMarkupWriter using printRaw(String).

print

void print(char[] data,
           int offset,
           int length)

Version of print(char[], int, int, boolean) that assumes filter is enabled.

print

void print(char[] data,
           int offset,
           int length,
           boolean raw)

The primary print() method, used by most other methods.

Prints the character array, first closing any open tag. Problematic characters ('<', '>' and '&') are converted to appropriate entities.

Does nothing if data is null.

Closes any open tag.

Parameters:

data - contains the characters to print, or null to not print anything

offset - offset into the array to start printing from

length - number of characters to print

raw - if true, filtering is disabled

Since:

4.0

print

void print(char value)

Prints a single character, or its equivalent entity.

Closes any open tag.

print

void print(int value)

Prints an integer.

Closes any open tag.

print

void print(String value)

As with print(char[], int, int, boolean), but the data to print is defined by the String. Assumes filtering is enabled.

print

void print(String value,
           boolean raw)

As with print(char[], int, int, boolean), but the data to print is defined by the String.

println

void println()

Closes the open tag (if any), then prints a line seperator to the output stream.

printRaw

void printRaw(char[] buffer,
              int offset,
              int length)

Version of print(char[], int, int, boolean)that assumes filter is enabled.

printRaw

void printRaw(String value)

As with print(char[], int, int, boolean), but the data to print is defined by the String. Assumes filtering is disabled.

getContentType

String getContentType()

Returns the type of content generated by this response writer, as a MIME type.