com.primix.tapestry
Class AbstractResponseWriter

java.lang.Object
  |
  +--com.primix.tapestry.AbstractResponseWriter
All Implemented Interfaces:
IResponseWriter
Direct Known Subclasses:
HTMLResponseWriter, WMLResponseWriter

public abstract class AbstractResponseWriter
extends java.lang.Object
implements IResponseWriter

Abstract base class implementing the IResponseWriter interface. This class is used to create a Generic Tag Markup Language (GTML) output. It is more sophisticated than PrintWriter in that it maintains a concept hierarchy of open GTML tags. It also supplies a number of other of the features that are useful when creating GTML. Elements are started with the begin(String) or beginEmpty(String) methods. Once they are started, attributes for the elements may be set with the various attribute() methods. The element is closed off (i.e., the closing '>' character is written) when any other method is invoked (exception: methods which do not produce output, such as flush()). The end() methods end an element, writing an GTML close tag to the output.

TBD:

This class is derived from the original class com.primix.servlet.HTMLWriter, part of the ServletUtils framework available from The Giant Java Tree.

Since:
0.2.9
Version:
$Id: AbstractResponseWriter.java,v 1.6 2001/05/30 16:13:20 hship Exp $
Author:
Howard Ship, David Solis

Field Summary
protected  boolean openTag
          Indicates whether a tag is open or not.
protected  java.io.PrintWriter writer
          The underlying PrintWriter that output is sent to.
 
Constructor Summary
protected AbstractResponseWriter()
          Protected constructor, needed by to construct a nested response writer.
  AbstractResponseWriter(java.io.OutputStream stream)
          Sends output to the stream.
 
Method Summary
 void attribute(java.lang.String name)
          Simply prints the attribute name.
 void attribute(java.lang.String name, int value)
          Writes an integer attribute into the currently open tag.
 void attribute(java.lang.String name, java.lang.String value)
          Writes an attribute into the most recently opened tag.
 void begin(java.lang.String name)
          Closes any existing tag then starts a new element.
 void beginEmpty(java.lang.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 close()
          Closes this IResponseWriter.
 void closeTag()
          Closes the most recently opened element by writing the '>' that ends it.
 void comment(java.lang.String value)
          Writes an GTML comment.
 void end()
          Ends the element most recently started by begin(String).
 void end(java.lang.String name)
          Ends the most recently started element with the given name.
 void flush()
          Forwards flush() to this AbstractResponseWriter's PrintWriter.
abstract  java.lang.String getContentType()
          Implemented in concrete subclasses to identify the MIME content type produced by this response writer.
protected abstract  java.lang.String[] getEntities()
          Implemented in concrete subclasses to provide a mapping from characters to entities.
abstract  IResponseWriter getNestedWriter()
          Returns a nested writer, one that accumulates its changes in a buffer.
protected abstract  boolean[] getSafe()
          Implemented in concrete subclasses to provide an indication of which characters are 'safe' to insert directly into the response.
protected  java.lang.String pop()
          Removes the top element from the active element stack and returns it.
 void print(char value)
          Prints a single character.
 void print(char[] data, int offset, int length)
          The primary print() method, used by most other methods.
 void print(int value)
          Prints an integer.
 void print(java.lang.String value)
          Invokes print(char[], int, int) to print 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)
          Prints and portion of an output buffer to the stream.
 void printRaw(java.lang.String value)
          Prints output to the stream.
protected  void push(java.lang.String name)
          Adds an element to the active element stack.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

writer

protected java.io.PrintWriter writer
The underlying PrintWriter that output is sent to.

openTag

protected boolean openTag
Indicates whether a tag is open or not. A tag is opened by begin(String) or beginEmpty(String). It stays open while calls to the attribute() methods are made. It is closed (the '>' is written) when any other method is invoked.
Constructor Detail

AbstractResponseWriter

protected AbstractResponseWriter()
Protected constructor, needed by to construct a nested response writer.

Invokes getEntities() and getSafe() to determine the necessary translatons for the response writer.


AbstractResponseWriter

public AbstractResponseWriter(java.io.OutputStream stream)
Sends output to the stream. Internally, an instance of PrintWriter is created, which will be closed when the HTMLResponseWriter is closed.
Method Detail

getEntities

protected abstract java.lang.String[] getEntities()
Implemented in concrete subclasses to provide a mapping from characters to entities. The offset in the array corresponds to the character, the String is the literal text to insert into the output stream as a replacement. A value of null (which is prevalent) means no subsititution. We're using this as a fast-lookup on a single character, otherwise we might use a Map.

getSafe

protected abstract boolean[] getSafe()
Implemented in concrete subclasses to provide an indication of which characters are 'safe' to insert directly into the response. The index into the array is the character, if the value at the index is false (or the index out of range), then the character is escaped.

getContentType

public abstract java.lang.String getContentType()
Implemented in concrete subclasses to identify the MIME content type produced by this response writer.
Specified by:
getContentType in interface IResponseWriter

getNestedWriter

public abstract IResponseWriter getNestedWriter()
Description copied from interface: IResponseWriter
Returns a nested writer, one that accumulates its changes in a buffer. When the nested writer is closed, it writes its buffer into its containing IResponseWriter.
Specified by:
getNestedWriter in interface IResponseWriter

attribute

public void attribute(java.lang.String name)
Simply prints the attribute name. This is used for idempotent attributes, such as 'disabled' in an <input>.

TBD: Check that name is legal.

Specified by:
attribute in interface IResponseWriter
Throws:
java.lang.IllegalStateException - if there is no open tag.

attribute

public void attribute(java.lang.String name,
                      int value)
Writes an integer attribute into the currently open tag.

TBD: Validate that name is legal.

Specified by:
attribute in interface IResponseWriter
Throws:
java.lang.IllegalStateException - if there is no open tag.

attribute

public void attribute(java.lang.String name,
                      java.lang.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, in which case this method behaves the same as attribute(String).

Troublesome characters in the value are converted to thier GTML entities, much like a print() method, with the following exceptions:

Specified by:
attribute in interface IResponseWriter
Throws:
java.lang.IllegalStateException - if there is no open tag.

begin

public void begin(java.lang.String name)
Closes any existing tag then starts a new element. The new element is pushed onto the active element stack.
Specified by:
begin in interface IResponseWriter

beginEmpty

public void beginEmpty(java.lang.String name)
Starts an element that will not later be matched with an end() call. This is useful for elements such as <hr;> or <br> that do not need closing tags.
Specified by:
beginEmpty in interface IResponseWriter

checkError

public boolean checkError()
Invokes checkError() on the PrintWriter used to format output.
Specified by:
checkError in interface IResponseWriter

close

public void close()
Closes this IResponseWriter. Any active elements are closed. The PrintWriter is then sent PrintWriter.close().
Specified by:
close in interface IResponseWriter

closeTag

public 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).
Specified by:
closeTag in interface IResponseWriter

comment

public void comment(java.lang.String value)
Writes an GTML comment. Any open tag is first closed. The method takes care of providing the <!-- and -->, including a blank line after the close of the comment.

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

Specified by:
comment in interface IResponseWriter

end

public 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 GTML close tag.

TBD: Error checking for the open element stack empty.

Specified by:
end in interface IResponseWriter

end

public void end(java.lang.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.

TBD: Error check if the name matches nothing on the open tag stack.

Specified by:
end in interface IResponseWriter

flush

public void flush()
Forwards flush() to this AbstractResponseWriter's PrintWriter.
Specified by:
flush in interface IResponseWriter

pop

protected final java.lang.String pop()
Removes the top element from the active element stack and returns it.

print

public void print(char[] data,
                  int offset,
                  int length)
The primary print() method, used by most other methods.

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

All 'unsafe' characters are properly converted to either a named or numeric GTML entity. This can be somewhat expensive, so use printRaw(char[], int, int) if the data to print is guarenteed to be safe.

Does nothing if data is null.

Closes any open tag.

Specified by:
print in interface IResponseWriter

print

public void print(char value)
Prints a single character. If the character is not a 'safe' character, such as '<', then it's GTML entity (named or numeric) is printed instead.

Closes any open tag.

Specified by:
print in interface IResponseWriter

print

public void print(int value)
Prints an integer.

Closes any open tag.

Specified by:
print in interface IResponseWriter

print

public void print(java.lang.String value)
Invokes print(char[], int, int) to print the string. Use printRaw(String) if the character data is known to be safe.

Does nothing if value is null.

Closes any open tag.

Specified by:
print in interface IResponseWriter
See Also:
print(char[], int, int)

println

public void println()
Closes the open tag (if any), then prints a line seperator to the output stream.
Specified by:
println in interface IResponseWriter

printRaw

public void printRaw(char[] buffer,
                     int offset,
                     int length)
Prints and portion of an output buffer to the stream. No escaping of invalid GTML elements is done, which makes this more effecient than print(). Does nothing if buffer is null.

Closes any open tag.

Specified by:
printRaw in interface IResponseWriter

printRaw

public void printRaw(java.lang.String value)
Prints output to the stream. No escaping of invalid GTML elements is done, which makes this more effecient than print(). Does nothing if value is null.

Closes any open tag.

Specified by:
printRaw in interface IResponseWriter

push

protected final void push(java.lang.String name)
Adds an element to the active element stack.