org.progeeks.util.xml
Class XmlPrintWriter

java.lang.Object
  java.io.Writer
      java.io.PrintWriter
          org.progeeks.util.IndentPrintWriter
              org.progeeks.util.xml.XmlPrintWriter

All Implemented Interfaces:

java.io.Closeable, java.io.Flushable, java.lang.Appendable

public class XmlPrintWriter
extends IndentPrintWriter

Extends the functionality of the IndentPrintWriter to keep track of tag state and provide attribute support, etc.. Also, all output is encoded as appropriate for its context.

It is important to note that this class only keeps rudimentary state and cannot (is not designed to) validate the XML on the way out. It is a helper for programmatically generating declarative XML in a way that's often easier then constructing a full DOM hierarchy.

Version:

$Revision: 1.1 $

Author:

Paul Speed

Field Summary

Fields inherited from class java.io.PrintWriter

out

Fields inherited from class java.io.Writer

lock

Constructor Summary

XmlPrintWriter(java.io.Writer out)

Method Summary

void	clearPushedAttributes() Clears all pushed attributes.
void	close() Automatically finished writing any in-progess tags and then closes the file.
protected void	closeBlock() Closes the current tag or the current comment block depending on what block is currently open.
void	closeComment() Closes the comment block.
void	closeDataBlock() Closes a CDATA block.
void	closeDocType() Closes the open DOCTYPE element.
void	closeMarkupDeclaration() Closes any open markup declaration.
void	closeProcessingInstruction() Closes the current processing instruction block.
void	closeRawText() Closes a section of raw text output.
protected void	closeTag() Closes the current tag if open.
boolean	getSingleLineAttributes() Returns true if attributes are currently rendered on a single line.
int	getTagStackDepth() Returns the current tag stack depth.
static void	main(java.lang.String[] args) Used for testing.
void	popAllTags() Pops all current tags from this XmlPrintWriter effectively returning to the root state.
java.lang.String	popTag() Prints the closing element for the current tag and pops the indent.
void	popTag(java.lang.String tag) Prints the closing elements for the stacked tags until the specified tag is reached and popped.
void	printAttribute(java.lang.String name, java.lang.String value) Writes the specified attribute to the current tag if it is still open.
protected void	printBypass(java.lang.String s) Bypasses the automatic block termination by sending the data directly to the super class.
void	printComment(java.lang.String comment) Prints the specified string as an enclosed comment.
void	println() Resets the new line state and outputs a line separator.
protected void	printlnBypass(java.lang.String s) Bypasses the automatic block termination by sending the data directly to the super class.
void	printProcessingInstruction(java.lang.String target) Prints the specified processing instruction and opens it for additional writing with printAttribute() or free form printing.
protected void	printPushedAttributes() Iterates over the accumulated pushed attributes and prints them.
void	printRawText(java.lang.String comment) Prints the specified string as raw text without any encoding being performed.
void	printTag(java.lang.String tag) Prints the specified tag in single-element form, ie: <tag /> This is different that the normal pushTag() because if another tag or any text is written then the printed tag will automatically be closed with the &/gt; instead of nesting the tags or text.
void	pushAttribute(java.lang.String name, java.lang.String value) Adds an attribute to the set of attributes that will be automatically applied to the next rendered tag.
void	pushTag(java.lang.String tag) Prints the tag start and sets up the indent for nesting.
void	setSingleLineAttributes(boolean flag) Set to true to print each attribute on its own line.
void	startComment() Starts a comment block.
void	startDataBlock() Starts a CDATA block.
void	startDocType(java.lang.String root, java.lang.String systemLiteral, java.lang.String publicId) Prints the XML DOCTYPE declaration.
void	startMarkupDeclaration(java.lang.String markup) Starts a markup declaration such as ENTITY, ATTLIST and so on.
void	startRawText() Starts a section of raw text output.
void	write(char[] buff, int off, int len) Overridden to provide XML encoding when appropriate.
void	write(int c) Overridden to provide XML encoding when appropriate.
void	write(java.lang.String s, int off, int len) Overridden to provide XML encoding when appropriate.
protected void	writeEncoded(char[] buff, int offset, int len)
protected void	writeEncoded(int c) Writes the specified value out as an encoded string if necessary.
protected void	writeEncoded(java.lang.String s, int offset, int len)
protected void	writeInvalidChar(int c) Called to write out characters that are invalid in XML.

Methods inherited from class org.progeeks.util.IndentPrintWriter

endLine, getDefaultIndent, isNewLine, popIndent, pushIndent, pushIndent, setDefaultIndent, setOverrideIndent

Methods inherited from class java.io.PrintWriter

append, append, append, checkError, flush, format, format, print, print, print, print, print, print, print, print, print, printf, printf, println, println, println, println, println, println, println, println, println, setError, write, write

Methods inherited from class java.lang.Object

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

Constructor Detail

XmlPrintWriter

public XmlPrintWriter(java.io.Writer out)

Method Detail

setSingleLineAttributes

public void setSingleLineAttributes(boolean flag)

Set to true to print each attribute on its own line.

getSingleLineAttributes

public boolean getSingleLineAttributes()

Returns true if attributes are currently rendered on a single line.

pushTag

public void pushTag(java.lang.String tag)

Prints the tag start and sets up the indent for nesting.

printTag

public void printTag(java.lang.String tag)

Prints the specified tag in single-element form, ie: <tag /> This is different that the normal pushTag() because if another tag or any text is written then the printed tag will automatically be closed with the &/gt; instead of nesting the tags or text.

printProcessingInstruction

public void printProcessingInstruction(java.lang.String target)

Prints the specified processing instruction and opens it for additional writing with printAttribute() or free form printing. A processing instruction is of the form: <?target data ?> A standard processing instruction is the XML or xml target. <?xml version='1.0' encoding='utf-8'?> To facilitate this kind of construct the printAttribute method will use single quotes when adding to a processing instruction.

closeProcessingInstruction

public void closeProcessingInstruction()

Closes the current processing instruction block. In most cases this is called automatically when a new state is encountered but it may be necessary in some cases to close it manually.

printAttribute

public void printAttribute(java.lang.String name,
                           java.lang.String value)

Writes the specified attribute to the current tag if it is still open. Otherwise it will throw an IllegalStateException. The name will be verified for XML attribute name restrictions and the value will be encoded as necessary for attribute values.

Parameters:

name - The name of the attribute.

value - The value to be written. If the value is null then the attribute will not be written.

pushAttribute

public void pushAttribute(java.lang.String name,
                          java.lang.String value)

Adds an attribute to the set of attributes that will be automatically applied to the next rendered tag. When the next tag is started either through pushTag or printTag these accumulated attributes are rendered immediately and the attribute cache is flushed. This is useful in cases where tag rendering is going to be delegated to some secondary class but the caller still requires some attributes to be set. This is a general enough mechanism that it is convenient to put it here. Places that it comes up often are XmlPropertyRenderers that nest to other renderers but have to specify ObjectXmlReader directives for the nested object.

clearPushedAttributes

public void clearPushedAttributes()

Clears all pushed attributes. This can be used to verify that all pushed attributes have been processed after calling out to an external tag. It's a safety measure for the type of caller that would get the best use out of pushed attributes. It is not required in many cases since the tag printing will automatically clear the attributes.

printPushedAttributes

protected void printPushedAttributes()

Iterates over the accumulated pushed attributes and prints them. This is called by the various tag start methods.

popTag

public java.lang.String popTag()

Prints the closing element for the current tag and pops the indent.

popTag

public void popTag(java.lang.String tag)

Prints the closing elements for the stacked tags until the specified tag is reached and popped. If the tag is never found than an illegal state exception is thrown.

startDocType

public void startDocType(java.lang.String root,
                         java.lang.String systemLiteral,
                         java.lang.String publicId)

Prints the XML DOCTYPE declaration. The publicId and systemLiteral paramaters are optional but work together to define the external entity declaration. If the publicId and systemLiteral are specified then a PUBLIC external reference is generated. If only the systemLiteral is specified then a SYSTEM reference is generated.

  Example:
     startDocType( "root", null, null );
  Generates:
     <!DOCTYPE root>

  Example:
     startDocType( "root", "foo.dtd", null );
  Generates:
     <!DOCTYPE root
         SYSTEM "foo.dtd" >

  Example:
     startDocType( "root", "foo.dtd", "foo" );
  Generates:
     <!DOCTYPE root
         PUBLIC "foo"
         "foo.dtd" >
  

closeDocType

public void closeDocType()

Closes the open DOCTYPE element. In most cases this will be done automatically when a state change is detected. The notable exception to this is when there are nested markup declarations that are unclosed. In this case it is necessary to either close the last markup declaration or just close the doctype block. The latter of which is the easier choice and more appropriate.

startMarkupDeclaration

public void startMarkupDeclaration(java.lang.String markup)

Starts a markup declaration such as ENTITY, ATTLIST and so on. Text within a markup declaration is free-form through this API because of the myriad of markup declaration types and syntaxes. They will be properly nested within an open DOCTYPE.

closeMarkupDeclaration

public void closeMarkupDeclaration()

Closes any open markup declaration. In most cases this will be done automatically when a state change is detected.

getTagStackDepth

public int getTagStackDepth()

Returns the current tag stack depth. Useful mostly for debugging and verification purposes.

printComment

public void printComment(java.lang.String comment)

Prints the specified string as an enclosed comment.

startComment

public void startComment()

Starts a comment block.

closeComment

public void closeComment()

Closes the comment block.

startDataBlock

public void startDataBlock()

Starts a CDATA block.

closeDataBlock

public void closeDataBlock()

Closes a CDATA block.

printRawText

public void printRawText(java.lang.String comment)

Prints the specified string as raw text without any encoding being performed. Note: use with caution since this can be used to produce invalid XML.

startRawText

public void startRawText()

Starts a section of raw text output. Subsequent output will not be encoded until closeRawText() is called or some other block is opened.

closeRawText

public void closeRawText()

Closes a section of raw text output.

closeBlock

protected void closeBlock()

Closes the current tag or the current comment block depending on what block is currently open.

closeTag

protected void closeTag()

Closes the current tag if open. Otherwise this is a noop. Note this is not to be confused with popTag() which actually writes a closing tag in many cases.

popAllTags

public void popAllTags()

Pops all current tags from this XmlPrintWriter effectively returning to the root state. This is really only useful when the XmlPrintWriter is wrapping a writer that will contain multiple separate XML sections. Otherwise, close() is the appropriate call.

close

public void close()

Automatically finished writing any in-progess tags and then closes the file.

Specified by:

close in interface java.io.Closeable

Overrides:

close in class java.io.PrintWriter

write

public void write(int c)

Overridden to provide XML encoding when appropriate.

Overrides:

write in class IndentPrintWriter

println

public void println()

Description copied from class: IndentPrintWriter

Resets the new line state and outputs a line separator.

Overrides:

println in class IndentPrintWriter

write

public void write(char[] buff,
                  int off,
                  int len)

Overridden to provide XML encoding when appropriate.

Overrides:

write in class IndentPrintWriter

write

public void write(java.lang.String s,
                  int off,
                  int len)

Overridden to provide XML encoding when appropriate.

Overrides:

write in class IndentPrintWriter

printBypass

protected void printBypass(java.lang.String s)

Bypasses the automatic block termination by sending the data directly to the super class.

printlnBypass

protected void printlnBypass(java.lang.String s)

Bypasses the automatic block termination by sending the data directly to the super class.

writeEncoded

protected void writeEncoded(java.lang.String s,
                            int offset,
                            int len)

writeEncoded

protected void writeEncoded(char[] buff,
                            int offset,
                            int len)

writeInvalidChar

protected void writeInvalidChar(int c)

Called to write out characters that are invalid in XML.

writeEncoded

protected void writeEncoded(int c)

Writes the specified value out as an encoded string if necessary.

main

public static void main(java.lang.String[] args)
                 throws java.io.IOException

Used for testing. Generates example output to test various features of the writer.

Throws:

java.io.IOException