|
|||||||||
| Home >> All >> org >> znerd >> [ xmlenc overview ] | PREV CLASS NEXT CLASS | ||||||||
SUMMARY: JAVADOC | SOURCE | DOWNLOAD | NESTED | FIELD | CONSTR | METHOD |
DETAIL: FIELD | CONSTR | METHOD | ||||||||
org.znerd.xmlenc
Class XMLOutputter

java.lang.Objectorg.znerd.xmlenc.XMLOutputter
- All Implemented Interfaces:
- StatefulXMLEventListener, XMLEventListener, XMLEventListenerStates
- public class XMLOutputter
- extends java.lang.Object
- implements StatefulXMLEventListener
- extends java.lang.Object
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:- The name of the applicable encoding is always printed in the XML declaration, even though it may not be necessary.
- The
standaloneattribute is not supported in the XML declaration. - Internal DTD subsets are not supported.
- Spacing is fixed, whitespace is always kept to the minimum.
Supported encodings
The following encodings are supported:- UTF-8
- UTF-16
- ISO-10646-UCS-2
- ISO-10646-UCS-4
- ISO-10646-UTF-1
- US-ASCII (also known as ASCII)
- ISO-8859-n, where n is the part number
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 toXMLEventListenerStates.ERROR_STATE 55 and no more output can be
performed.
Performance hints
It is usually a good idea to letXMLOutputter 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
The value of this field is returned bynull.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
_elementStack55.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 usinggetQuotationMark()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 toXMLEventListenerStates.UNINITIALIZED55 .
XMLOutputter
public XMLOutputter(java.io.Writer out, java.lang.String encoding) throws java.lang.IllegalStateException, java.lang.IllegalArgumentException, java.io.UnsupportedEncodingException
- Constructs a new
XMLOutputterfor the specifiedWriterand encoding. This sets the state toXMLEventListenerStates.BEFORE_XML_DECLARATION55 . 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
XMLOutputterfor the specifiedWriterandencoder. This sets the state toXMLEventListenerStates.BEFORE_XML_DECLARATION55 .
| 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. TheWriterand the encoding will be set tonull, the element stack will be cleared, the state will be set toXMLEventListenerStates.UNINITIALIZED55 , the line break will be set toLineBreak.NONE55 and the indentation will be set toDEFAULT_INDENTATION55 (an empty string).- Specified by:
resetin interfaceXMLEventListener
reset
private final void reset(java.io.Writer out) throws java.lang.IllegalArgumentException
- Resets this
XMLOutputterand configures it for the specified output stream. This sets the state toXMLEventListenerStates.BEFORE_XML_DECLARATION55 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
XMLOutputterand configures it for the specified output stream and encoding. This resets the state toXMLEventListenerStates.BEFORE_XML_DECLARATION55 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
XMLOutputterand configures it for the specified output stream and encoder. This resets the state toXMLEventListenerStates.BEFORE_XML_DECLARATION55 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.UNINITIALIZED55 as the state is equivalent to callingreset()55 . Caution: This method can be used to let this class generate invalid XML.- Specified by:
setStatein interfaceXMLEventListener
- Since:
- xmlenc 0.22
getState
public final XMLEventListenerState getState()
- Returns the current state of this outputter.
- Specified by:
getStatein interfaceStatefulXMLEventListener
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 andpcdata(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 andpcdata(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:
declarationin interfaceXMLEventListener
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:
while the system identifier is:-//W3C//DTD XHTML 1.0 Transitional//EN
The output is typically similar to this:http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd
or alternatively, if only the system identifier is specified:<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><!DOCTYPE html SYSTEM "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">- Specified by:
dtdin interfaceXMLEventListener
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:
startTagin interfaceXMLEventListener
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:
attributein interfaceXMLEventListener
endTag
public final void endTag()
throws java.lang.IllegalStateException,
java.io.IOException
- Writes an element end tag.
- Specified by:
endTagin interfaceXMLEventListener
pcdata
public final void pcdata(java.lang.String text) throws java.lang.IllegalStateException, java.lang.IllegalArgumentException, InvalidXMLException, java.io.IOException
- Writes the specified
Stringas PCDATA.- Specified by:
pcdatain interfaceXMLEventListener
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:
pcdatain interfaceXMLEventListener
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_DECLARATION55 , then it will be set toXMLEventListenerStates.BEFORE_DTD_DECLARATION55 , otherwise if the state isXMLEventListenerStates.START_TAG_OPEN55 then it will be set toXMLEventListenerStates.WITHIN_ELEMENT55 , otherwise the state will not be changed.- Specified by:
whitespacein interfaceXMLEventListener
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_DECLARATION55 , then it will be set toXMLEventListenerStates.BEFORE_DTD_DECLARATION55 , otherwise if the state isXMLEventListenerStates.START_TAG_OPEN55 then it will be set toXMLEventListenerStates.WITHIN_ELEMENT55 , otherwise the state will not be changed.- Specified by:
whitespacein interfaceXMLEventListener
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 equalsXMLEventListenerStates.BEFORE_XML_DECLARATION55 , then it will be set toXMLEventListenerStates.BEFORE_DTD_DECLARATION55 , otherwise if the state isXMLEventListenerStates.START_TAG_OPEN55 then it will be set toXMLEventListenerStates.WITHIN_ELEMENT55 , otherwise the state will not be changed.- Specified by:
commentin interfaceXMLEventListener
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_DECLARATION55 , then it will be set toXMLEventListenerStates.BEFORE_DTD_DECLARATION55 , otherwise the state will not be changed.- Specified by:
piin interfaceXMLEventListener
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"<"and"&". 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:
cdatain interfaceXMLEventListener
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, callendDocument()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:
endDocumentin interfaceXMLEventListener
|
|||||||||
| Home >> All >> org >> znerd >> [ xmlenc overview ] | PREV CLASS NEXT CLASS | ||||||||
SUMMARY: JAVADOC | SOURCE | DOWNLOAD | NESTED | FIELD | CONSTR | METHOD |
DETAIL: FIELD | CONSTR | METHOD | ||||||||
JAVADOC
org.znerd.xmlenc.XMLOutputter