Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep

org.znerd.xmlenc
Class XMLOutputter  view XMLOutputter download XMLOutputter.java

java.lang.Object
  extended byorg.znerd.xmlenc.XMLOutputter
All Implemented Interfaces:
StatefulXMLEventListener, XMLEventListener, XMLEventListenerStates

public class XMLOutputter
extends java.lang.Object
implements StatefulXMLEventListener

Stream-based XML outputter. Instances of this class are able to write XML output to Writers.

Standards compliance

This class is intended to produce output that conforms to the XML 1.0 Specification. However, not all applicable restrictions are validated. For example, it is currently not checked if names contain characters that are invalid within a Name production.

Furthermore, not all possible XML documents can be produced. The following limitations apply:

Supported encodings

The following encodings are supported:

Multi-threading

This class is not thread-safe.

Exceptions

Note that all methods check the state first and then check the arguments. This means that if the state is incorrect and the arguments are incorrect, then an java.lang.IllegalStateException will be thrown.

If any of the writing methods generates an java.io.IOException, then the state will be set to XMLEventListenerStates.ERROR_STATE 55 and no more output can be performed.

Performance hints

It is usually a good idea to let XMLOutputter instances write to buffered Writers. This typically improves performance on large documents or relatively slow or blocking output streams.

Instances of this class can be cached in a pool to reduce object creations. Call reset() 55 (with no arguments) when storing an instance in the pool. Use reset(Writer,String) 55 (with 2 arguments) to re-initialize the instance after fetching it from the pool.

Since:
xmlenc 0.19
Version:
$Revision: 1.118 $ $Date: 2005/09/12 08:40:02 $

Field Summary
private  boolean _anythingOutput
          Flag that indicates whether anything has been output already.
private  java.lang.String[] _elementStack
          Stack of open elements.
private  int _elementStackSize
          The size of the element stack.
private  XMLEncoder _encoder
          The encoder used to actually encode character streams.
private  boolean _escapeAmpersands
          Flag that indicates if ampersands should be escaped.
private  java.lang.String _indentation
          The currently used indentation string.
private  LineBreak _lineBreak
          The line break that is currently in use.
private  char[] _lineBreakChars
          The line break as a char array.
private  java.io.Writer _out
          The output stream this outputter will write to.
private  char _quotationMark
          The current quotation mark.
private  XMLEventListenerState _state
          The state of this outputter.
static java.lang.String DEFAULT_INDENTATION
          Default indentation.
 
Fields inherited from interface org.znerd.xmlenc.XMLEventListenerStates
AFTER_ROOT_ELEMENT, BEFORE_DTD_DECLARATION, BEFORE_ROOT_ELEMENT, BEFORE_XML_DECLARATION, DOCUMENT_ENDED, ERROR_STATE, START_TAG_OPEN, UNINITIALIZED, WITHIN_ELEMENT
 
Constructor Summary
XMLOutputter()
          Constructs a new XMLOutputter.
XMLOutputter(java.io.Writer out, java.lang.String encoding)
          Constructs a new XMLOutputter for the specified Writer and encoding.
XMLOutputter(java.io.Writer out, XMLEncoder encoder)
          Constructs a new XMLOutputter for the specified Writer and encoder.
 
Method Summary
 void attribute(java.lang.String name, java.lang.String value)
          Adds an attribute to the current element.
 void cdata(java.lang.String text)
          Writes a CDATA section.
private  void checkInvariants()
          Checks all invariants.
 void close()
          Closes all open elements.
private  void closeStartTag()
          Closes an open start tag.
 void comment(java.lang.String text)
          Writes the specified comment.
 void declaration()
          Writes the XML declaration.
 void dtd(java.lang.String name, java.lang.String publicID, java.lang.String systemID)
          Writes a document type declaration.
 void endDocument()
          Ends the XML output.
 void endTag()
          Writes an element end tag.
 java.lang.String[] getElementStack()
          Returns a copy of the element stack.
 int getElementStackCapacity()
          Returns the current capacity for the stack of open elements.
 int getElementStackSize()
          Returns the current depth of open elements.
 java.lang.String getEncoding()
          Returns the encoding of this outputter.
 java.lang.String getIndentation()
          Returns the string currently used for indentation.
 LineBreak getLineBreak()
          Returns the currently used line break.
 char getQuotationMark()
          Gets the quotation mark character.
 XMLEventListenerState getState()
          Returns the current state of this outputter.
 java.io.Writer getWriter()
          Returns the output stream this outputter uses.
 boolean isEscaping()
          Checks if escaping is currently enabled.
 void pcdata(char[] ch, int start, int length)
          Writes the specified character array as PCDATA.
 void pcdata(java.lang.String text)
          Writes the specified String as PCDATA.
 void pi(java.lang.String target, java.lang.String instruction)
          Writes a processing instruction.
 void reset()
          Resets this XMLOutputter.
private  void reset(java.io.Writer out)
          Resets this XMLOutputter and configures it for the specified output stream.
 void reset(java.io.Writer out, java.lang.String encoding)
          Resets this XMLOutputter and configures it for the specified output stream and encoding.
 void reset(java.io.Writer out, XMLEncoder encoder)
          Resets this XMLOutputter and configures it for the specified output stream and encoder.
 void setElementStackCapacity(int newCapacity)
          Sets the capacity for the stack of open elements.
 void setEscaping(boolean escapeAmpersands)
          Sets if ampersands should be escaped.
 void setIndentation(java.lang.String indentation)
          Sets the string to be used for indentation.
 void setLineBreak(LineBreak lineBreak)
          Sets the type of line break to use.
 void setQuotationMark(char c)
          Sets the quotation mark character to use.
 void setState(XMLEventListenerState newState, java.lang.String[] newElementStack)
          Sets the state of this outputter.
 void startTag(java.lang.String type)
          Writes an element start tag.
 void whitespace(char[] ch, int start, int length)
          Writes text from the specified character array as ignorable whitespace.
 void whitespace(java.lang.String whitespace)
          Writes the specified ignorable whitespace.
private  void writeIndentation()
          Writes the indentation to the output stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_INDENTATION

public static final java.lang.String DEFAULT_INDENTATION
Default indentation. This is the empty string, "", since by default no indentation is performed.

See Also:
Constant Field Values

_anythingOutput

private boolean _anythingOutput
Flag that indicates whether anything has been output already.


_out

private java.io.Writer _out
The output stream this outputter will write to.

This field is initialized by the constructor. It can never be null.

The value of this field is returned by getWriter() 55 .


_encoder

private XMLEncoder _encoder
The encoder used to actually encode character streams.


_state

private XMLEventListenerState _state
The state of this outputter.


_elementStack

private java.lang.String[] _elementStack
Stack of open elements.

This field is initialized by the constructor. It can never be null.

Since:
xmlenc 0.22

_elementStackSize

private int _elementStackSize
The size of the element stack. The actual capacity is _elementStack 55 .length.

Since:
xmlenc 0.22

_quotationMark

private char _quotationMark
The current quotation mark.

The value of this field can be set using setQuotationMark(char) 55 and can be retrieved using getQuotationMark() 55 .


_escapeAmpersands

private boolean _escapeAmpersands
Flag that indicates if ampersands should be escaped.


_lineBreak

private LineBreak _lineBreak
The line break that is currently in use. Should never become null.


_lineBreakChars

private char[] _lineBreakChars
The line break as a char array. Should never become null, but can be a zero-length array.


_indentation

private java.lang.String _indentation
The currently used indentation string. Can never become null.

Constructor Detail

XMLOutputter

public XMLOutputter()
Constructs a new XMLOutputter. This sets the state to XMLEventListenerStates.UNINITIALIZED 55 .


XMLOutputter

public XMLOutputter(java.io.Writer out,
                    java.lang.String encoding)
             throws java.lang.IllegalStateException,
                    java.lang.IllegalArgumentException,
                    java.io.UnsupportedEncodingException
Constructs a new XMLOutputter for the specified Writer and encoding. This sets the state to XMLEventListenerStates.BEFORE_XML_DECLARATION 55 .

The encoding will be stored exactly as passed, leaving the case intact.


XMLOutputter

public XMLOutputter(java.io.Writer out,
                    XMLEncoder encoder)
             throws java.lang.IllegalStateException,
                    java.lang.IllegalArgumentException,
                    java.io.UnsupportedEncodingException
Constructs a new XMLOutputter for the specified Writer and encoder. This sets the state to XMLEventListenerStates.BEFORE_XML_DECLARATION 55 .

Method Detail

checkInvariants

private final void checkInvariants()
                            throws java.lang.Error
Checks all invariants. This check should be performed at the end of every method that changes the internal state of this object.


writeIndentation

private final void writeIndentation()
                             throws java.io.IOException
Writes the indentation to the output stream.


getWriter

public final java.io.Writer getWriter()
Returns the output stream this outputter uses.


getEncoding

public final java.lang.String getEncoding()
Returns the encoding of this outputter.


reset

public void reset()
Resets this XMLOutputter. The Writer and the encoding will be set to null, the element stack will be cleared, the state will be set to XMLEventListenerStates.UNINITIALIZED 55 , the line break will be set to LineBreak.NONE 55 and the indentation will be set to DEFAULT_INDENTATION 55 (an empty string).

Specified by:
reset in interface XMLEventListener

reset

private final void reset(java.io.Writer out)
                  throws java.lang.IllegalArgumentException
Resets this XMLOutputter and configures it for the specified output stream. This sets the state to XMLEventListenerStates.BEFORE_XML_DECLARATION 55 and clears the stack of open elements.


reset

public final void reset(java.io.Writer out,
                        java.lang.String encoding)
                 throws java.lang.IllegalArgumentException,
                        java.io.UnsupportedEncodingException
Resets this XMLOutputter and configures it for the specified output stream and encoding. This resets the state to XMLEventListenerStates.BEFORE_XML_DECLARATION 55 and clears the stack of open elements.


reset

public final void reset(java.io.Writer out,
                        XMLEncoder encoder)
                 throws java.lang.IllegalArgumentException,
                        java.io.UnsupportedEncodingException
Resets this XMLOutputter and configures it for the specified output stream and encoder. This resets the state to XMLEventListenerStates.BEFORE_XML_DECLARATION 55 and clears the stack of open elements.


setState

public final void setState(XMLEventListenerState newState,
                           java.lang.String[] newElementStack)
                    throws java.lang.IllegalArgumentException
Sets the state of this outputter. Normally, it is not necessary to call this method.

Calling this method with XMLEventListenerStates.UNINITIALIZED 55 as the state is equivalent to calling reset() 55 .

Caution: This method can be used to let this class generate invalid XML.

Specified by:
setState in interface XMLEventListener
Since:
xmlenc 0.22

getState

public final XMLEventListenerState getState()
Returns the current state of this outputter.

Specified by:
getState in interface StatefulXMLEventListener

isEscaping

public final boolean isEscaping()
Checks if escaping is currently enabled. If escaping is enabled, then all ampersand characters ('&') are replaced by the character entity reference "&". This affects PCDATA string printing (pcdata(String) 55 and pcdata(char[],int,int) 55 ) and attribute value printing (attribute(String,String) 55 ).


setEscaping

public final void setEscaping(boolean escapeAmpersands)
Sets if ampersands should be escaped. This affects PCDATA string printing (pcdata(String) 55 and pcdata(char[],int,int) 55 ) and attribute value printing (attribute(String,String) 55 ).

If ampersands are not escaped, then entity references can be printed.

Since:
xmlenc 0.24

getElementStack

public final java.lang.String[] getElementStack()
Returns a copy of the element stack. The returned array will be a new array. The size of the array will be equal to the element stack size (see getElementStackSize() 55 .

Since:
xmlenc 0.22

getElementStackSize

public final int getElementStackSize()
Returns the current depth of open elements.

Since:
xmlenc 0.22

getElementStackCapacity

public final int getElementStackCapacity()
Returns the current capacity for the stack of open elements.

Since:
xmlenc 0.28

setElementStackCapacity

public final void setElementStackCapacity(int newCapacity)
                                   throws java.lang.IllegalArgumentException,
                                          java.lang.OutOfMemoryError
Sets the capacity for the stack of open elements. The new capacity must at least allow the stack to contain the current open elements.


setQuotationMark

public final void setQuotationMark(char c)
                            throws java.lang.IllegalArgumentException
Sets the quotation mark character to use. This character is printed before and after an attribute value. It can be either the single or the double quote character.

The default quotation mark character is '"'.


getQuotationMark

public final char getQuotationMark()
Gets the quotation mark character. This character is used to mark the start and end of an attribute value.

The default quotation mark character is '"'.


setLineBreak

public final void setLineBreak(LineBreak lineBreak)
Sets the type of line break to use. If the line break is set to LineBreak.NONE, then the indentation is reset to an empty string.


getLineBreak

public final LineBreak getLineBreak()
Returns the currently used line break.


setIndentation

public final void setIndentation(java.lang.String indentation)
                          throws java.lang.IllegalStateException
Sets the string to be used for indentation. A line break must be set prior to calling this method.

Only space and tab characters are allowed for the indentation.


getIndentation

public final java.lang.String getIndentation()
Returns the string currently used for indentation.


closeStartTag

private void closeStartTag()
                    throws java.io.IOException
Closes an open start tag.


declaration

public final void declaration()
                       throws java.lang.IllegalStateException,
                              java.io.IOException
Writes the XML declaration. This method always prints the name of the encoding. The case of the encoding is as it was specified during initialization (or re-initialization).

If the encoding is set to "ISO-8859-1", then this method will produce the following output:

<?xml version="1.0" encoding="ISO-8859-1"?>

Specified by:
declaration in interface XMLEventListener

dtd

public final void dtd(java.lang.String name,
                      java.lang.String publicID,
                      java.lang.String systemID)
               throws java.lang.IllegalStateException,
                      java.lang.IllegalArgumentException,
                      InvalidXMLException,
                      java.io.IOException
Writes a document type declaration.

An external subset can be specified using either a system identifier (alone), or using both a public identifier and a system identifier. It can never be specified using a public identifier alone.

For example, for XHTML 1.0 the public identifier is:

-//W3C//DTD XHTML 1.0 Transitional//EN

while the system identifier is:

http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd

The output is typically similar to this:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
or alternatively, if only the system identifier is specified:
<!DOCTYPE html SYSTEM "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

Specified by:
dtd in interface XMLEventListener

startTag

public final void startTag(java.lang.String type)
                    throws java.lang.IllegalStateException,
                           java.lang.IllegalArgumentException,
                           java.io.IOException
Writes an element start tag. The element type name will be stored in the internal element stack. If necessary, the capacity of this stack will be extended.

Specified by:
startTag in interface XMLEventListener

attribute

public final void attribute(java.lang.String name,
                            java.lang.String value)
                     throws java.lang.IllegalStateException,
                            java.lang.IllegalArgumentException,
                            java.io.IOException
Adds an attribute to the current element. There must currently be an open element.

The attribute value is surrounded by single quotes.

Specified by:
attribute in interface XMLEventListener

endTag

public final void endTag()
                  throws java.lang.IllegalStateException,
                         java.io.IOException
Writes an element end tag.

Specified by:
endTag in interface XMLEventListener

pcdata

public final void pcdata(java.lang.String text)
                  throws java.lang.IllegalStateException,
                         java.lang.IllegalArgumentException,
                         InvalidXMLException,
                         java.io.IOException
Writes the specified String as PCDATA.

Specified by:
pcdata in interface XMLEventListener

pcdata

public final void pcdata(char[] ch,
                         int start,
                         int length)
                  throws java.lang.IllegalStateException,
                         java.lang.IllegalArgumentException,
                         java.lang.IndexOutOfBoundsException,
                         InvalidXMLException,
                         java.io.IOException
Writes the specified character array as PCDATA.

Specified by:
pcdata in interface XMLEventListener

whitespace

public final void whitespace(java.lang.String whitespace)
                      throws java.lang.IllegalStateException,
                             java.lang.IllegalArgumentException,
                             InvalidXMLException,
                             java.io.IOException
Writes the specified ignorable whitespace. Ignorable whitespace may be written anywhere in XML output stream, except above the XML declaration.

If the state equals XMLEventListenerStates.BEFORE_XML_DECLARATION 55 , then it will be set to XMLEventListenerStates.BEFORE_DTD_DECLARATION 55 , otherwise if the state is XMLEventListenerStates.START_TAG_OPEN 55 then it will be set to XMLEventListenerStates.WITHIN_ELEMENT 55 , otherwise the state will not be changed.

Specified by:
whitespace in interface XMLEventListener

whitespace

public final void whitespace(char[] ch,
                             int start,
                             int length)
                      throws java.lang.IllegalStateException,
                             java.lang.IllegalArgumentException,
                             java.lang.IndexOutOfBoundsException,
                             InvalidXMLException,
                             java.io.IOException
Writes text from the specified character array as ignorable whitespace. Ignorable whitespace may be written anywhere in XML output stream, except above the XML declaration.

This method does not check if the string actually contains whitespace.

If the state equals XMLEventListenerStates.BEFORE_XML_DECLARATION 55 , then it will be set to XMLEventListenerStates.BEFORE_DTD_DECLARATION 55 , otherwise if the state is XMLEventListenerStates.START_TAG_OPEN 55 then it will be set to XMLEventListenerStates.WITHIN_ELEMENT 55 , otherwise the state will not be changed.

Specified by:
whitespace in interface XMLEventListener

comment

public final void comment(java.lang.String text)
                   throws java.lang.IllegalStateException,
                          java.lang.IllegalArgumentException,
                          InvalidXMLException,
                          java.io.IOException
Writes the specified comment. The comment should not contain the string "--".

If the state equals XMLEventListenerStates.BEFORE_XML_DECLARATION 55 , then it will be set to XMLEventListenerStates.BEFORE_DTD_DECLARATION 55 , otherwise if the state is XMLEventListenerStates.START_TAG_OPEN 55 then it will be set to XMLEventListenerStates.WITHIN_ELEMENT 55 , otherwise the state will not be changed.

Specified by:
comment in interface XMLEventListener

pi

public final void pi(java.lang.String target,
                     java.lang.String instruction)
              throws java.lang.IllegalStateException,
                     java.lang.IllegalArgumentException,
                     java.io.IOException
Writes a processing instruction. A target and an optional instruction should be specified.

A processing instruction can appear above and below the root element, and between elements. It cannot appear inside an element start or end tag, nor inside a comment. Processing instructions cannot be nested.

If the state equals XMLEventListenerStates.BEFORE_XML_DECLARATION 55 , then it will be set to XMLEventListenerStates.BEFORE_DTD_DECLARATION 55 , otherwise the state will not be changed.

Specified by:
pi in interface XMLEventListener

cdata

public final void cdata(java.lang.String text)
                 throws java.lang.IllegalStateException,
                        java.lang.IllegalArgumentException,
                        java.io.IOException
Writes a CDATA section.

A CDATA section can contain any string, except "]]>". This will, however, not be checked by this method.

Left angle brackets and ampersands will be output in their literal form; they need not (and cannot) be escaped using "&lt;" and "&amp;".

If the specified string is empty (i.e. "".equals(text), then nothing will be output.

If the specified string contains characters that cannot be printed in this encoding, then the result is undefined.

Specified by:
cdata in interface XMLEventListener

close

public final void close()
                 throws java.lang.IllegalStateException,
                        java.io.IOException
Closes all open elements. After calling this method, only the whitespace(String) 55 method can be called.

If you would like to flush the output stream as well, call endDocument() 55 instead.


endDocument

public final void endDocument()
                       throws java.lang.IllegalStateException,
                              java.io.IOException
Ends the XML output. All open elements will be closed and the underlying output stream will be flushed using getWriter() 55 .flush() 55 .

After calling this method, no more output can be written until this outputter is reset.

Specified by:
endDocument in interface XMLEventListener