org.znerd.xmlenc
Interface XMLEventListener

All Superinterfaces:
XMLEventListenerStates
All Known Subinterfaces:
StatefulXMLEventListener
All Known Implementing Classes:
XMLOutputter

public interface XMLEventListener
extends XMLEventListenerStates

Interface for XML event listeners.

State transitions

XML event sources must obey a state model when calling XMLEventListeners. However, an XMLEventListener is not required to check that this state model is actually respected. If it does, then it will throw an IllegalStateException if the state model is violated.

Stateful XMLEventListener implementations should implement the StatefulXMLEventListener interface instead of implementing XMLEventListener directly.

Initially the state of an uninitialized XMLEventListener is UNINITIALIZED.

The following table defines how the state changes when a certain method is called in a certain state. Horizontally are the current states, vertically the notification methods. The cells self contain the new state.

S0 S1 S2 S3 S4 S5 S6
declaration() S1 ISE ISE ISE ISE ISE ISE
dtd(String,String,String) S2 S2 ISE ISE ISE ISE ISE
startTag(String) S3 S3 S3 S3 S3 ISE ISE
attribute(String,String) ISE ISE ISE S3 ISE ISE ISE
endTag() ISE ISE ISE S4/S5 S4/S5 ISE ISE
pcdata(String) ISE ISE ISE S4 S4 ISE ISE
pcdata(char[],int,int) ISE ISE ISE S4 S4 ISE ISE
cdata(String) ISE ISE ISE S4 S4 ISE ISE
whitespace(String) S1 S1 S4 S4 S4 S5 ISE
whitespace(char[],int,int) S1 S1 S4 S4 S4 S5 ISE
comment(String) S1 S1 S4 S4 S4 S5 ISE
pi(String,String) S1 S1 S4 S4 S4 S5 ISE
endDocument() ISE ISE ISE S6 S6 S6 ISE

List of states as used in the table:

Since:
xmlenc 0.30
Version:
$Revision: 1.9 $ $Date: 2005/09/12 08:40:02 $
Author:
Ernst de Haan (wfe.dehaan@gmail.com)

Field Summary
 
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
 
Method Summary
 void attribute(String name, String value)
          Adds an attribute to the current element.
 void cdata(String text)
          Notification of a CDATA section.
 void comment(String text)
          Notification of a comment.
 void declaration()
          Notification of an XML declaration.
 void dtd(String name, String publicID, String systemID)
          Notification of a document type declaration.
 void endDocument()
          Notification of the end of the document.
 void endTag()
          Notification of an element end tag.
 XMLEventListenerState getState()
          Returns the current state of this outputter.
 void pcdata(char[] ch, int start, int length)
          Notification of a PCDATA section (as a char array).
 void pcdata(String text)
          Notification of a PCDATA section (as a String).
 void pi(String target, String instruction)
          Notification of a processing instruction.
 void reset()
          Resets this XML event listener.
 void setState(XMLEventListenerState newState, String[] newElementStack)
          Sets the state of this XML event listener.
 void startTag(String type)
          Notification of an element start tag.
 void whitespace(char[] ch, int start, int length)
          Notification of ignorable whitespace (as a String).
 void whitespace(String whitespace)
          Notification of ignorable whitespace (as a String).
 

Method Detail

reset

public void reset()
Resets this XML event listener. The state will be set to UNINITIALIZED.


getState

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

Returns:
the current state, cannot be null.
Throws:
UnsupportedOperationException - if this is not a stateful XML event listener.

setState

public void setState(XMLEventListenerState newState,
                     String[] newElementStack)
              throws IllegalArgumentException
Sets the state of this XML event listener. Normally, it is not necessary to call this method and it should be used with great care.

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

Parameters:
newState - the new state, not null.
newElementStack - the new element stack, if newState == START_TAG_OPEN || newState == WITHIN_ELEMENT then it should be non-null and containing no null elements, otherwise it must be null.
Throws:
IllegalArgumentException - if newState == null || (newState == START_TAG_OPEN && newElementStack == null) || (newState == WITHIN_ELEMENT && newElementStack == null) || (newState != START_TAG_OPEN && newState != WITHIN_ELEMENT && newElementStack != null) || newElementStack[n] == null (where 0 <= n < newElementStack.length).

declaration

public void declaration()
                 throws IllegalStateException,
                        IOException
Notification of an XML declaration. No encoding is explicitly specified.

Throws:
IllegalStateException - if getState() != BEFORE_XML_DECLARATION.
IOException - if an I/O error occurs; this will set the state to ERROR_STATE.

dtd

public void dtd(String name,
                String publicID,
                String systemID)
         throws IllegalStateException,
                IllegalArgumentException,
                InvalidXMLException,
                IOException
Notification of 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">

Parameters:
name - the name of the document type, not null.
publicID - the public identifier, can be null.
systemID - the system identifier, can be null, but otherwise it should be a properly formatted URL, see section 4.2.2 External Entities in the XML 1.0 Specification.
Throws:
IllegalStateException - if getState() != BEFORE_XML_DECLARATION&& getState() != BEFORE_DTD_DECLARATION.
IllegalArgumentException - if name == null || (publicID != null && systemID == null).
IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.
InvalidXMLException

startTag

public void startTag(String type)
              throws IllegalStateException,
                     IllegalArgumentException,
                     InvalidXMLException,
                     IOException
Notification of an element start tag.

Parameters:
type - the type of the tag to start, not null.
Throws:
IllegalStateException - if getState() != BEFORE_XML_DECLARATION && getState() != BEFORE_DTD_DECLARATION && getState() != BEFORE_ROOT_ELEMENT && getState() != START_TAG_OPEN && getState() != WITHIN_ELEMENT.
IllegalArgumentException - if type == null.
IOException - if an I/O error occurs; this will set the state to ERROR_STATE.
InvalidXMLException

attribute

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

The attribute value is surrounded by single quotes.

Parameters:
name - the name of the attribute, not null.
value - the value of the attribute, not null.
Throws:
IllegalStateException - if getState() != XMLEventListenerStates.START_TAG_OPEN.
IllegalArgumentException - if name == null || value == null.
IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.
InvalidXMLException

endTag

public void endTag()
            throws IllegalStateException,
                   IOException
Notification of an element end tag.

Throws:
IllegalStateException - if getState() != START_TAG_OPEN && getState() != WITHIN_ELEMENT
IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.

pcdata

public void pcdata(String text)
            throws IllegalStateException,
                   IllegalArgumentException,
                   InvalidXMLException,
                   IOException
Notification of a PCDATA section (as a String).

Parameters:
text - the PCDATA section contents, not null.
Throws:
IllegalStateException - if getState() != START_TAG_OPEN && getState() != WITHIN_ELEMENT
IllegalArgumentException - if text == null.
InvalidXMLException - if the specified text contains an invalid character.
IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.

pcdata

public void pcdata(char[] ch,
                   int start,
                   int length)
            throws IllegalStateException,
                   IllegalArgumentException,
                   IndexOutOfBoundsException,
                   InvalidXMLException,
                   IOException
Notification of a PCDATA section (as a char array).

Parameters:
ch - the character array containing the PCDATA section contents, not null.
start - the start index in the array, must be >= 0 and it must be < ch.length.
length - the number of characters to read from the array, must be > 0.
Throws:
IllegalStateException - if getState() != START_TAG_OPEN && getState() != WITHIN_ELEMENT
IllegalArgumentException - if ch == null || start < 0 || start >= ch.length || length < 0.
IndexOutOfBoundsException - if start + length > ch.length.
InvalidXMLException - if the specified text contains an invalid character.
IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.

cdata

public void cdata(String text)
           throws IllegalStateException,
                  IllegalArgumentException,
                  InvalidXMLException,
                  IOException
Notification of 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.

Parameters:
text - the contents of the CDATA section, not null.
Throws:
IllegalStateException - if getState() != START_TAG_OPEN && getState() != WITHIN_ELEMENT
IllegalArgumentException - if text == null.
InvalidXMLException - if the specified text contains an invalid character.
IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.

whitespace

public void whitespace(String whitespace)
                throws IllegalStateException,
                       IllegalArgumentException,
                       InvalidXMLException,
                       IOException
Notification of ignorable whitespace (as a String). Ignorable whitespace can be found anywhere in an XML document, except above the XML declaration.

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

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

Parameters:
whitespace - the ignorable whitespace to be written, not null.
Throws:
IllegalStateException - if getState() == ERROR_STATE.
IllegalArgumentException - if whitespace == null.
InvalidXMLException - if the specified text contains an invalid character.
IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.

whitespace

public void whitespace(char[] ch,
                       int start,
                       int length)
                throws IllegalStateException,
                       IllegalArgumentException,
                       IndexOutOfBoundsException,
                       InvalidXMLException,
                       IOException
Notification of ignorable whitespace (as a String). Ignorable whitespace can be found anywhere in an XML document, except above the XML declaration.

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

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

Parameters:
ch - the character array containing the text to be written, not null.
start - the start index in the array, must be >= 0 and it must be < ch.length.
length - the number of characters to read from the array, must be > 0.
Throws:
IllegalStateException - if getState() == ERROR_STATE.
IllegalArgumentException - if ch == null || start < 0 || start >= ch.length || length < 0.
IndexOutOfBoundsException - if start + length > ch.length.
InvalidXMLException - if the specified text contains an invalid character.
IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.

comment

public void comment(String text)
             throws IllegalStateException,
                    IllegalArgumentException,
                    InvalidXMLException,
                    IOException
Notification of a comment. The comment should not contain the string "--".

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

Parameters:
text - the text for the comment be written, not null.
Throws:
IllegalStateException - if getState() == ERROR_STATE.
IllegalArgumentException - if text == null.
InvalidXMLException - if the specified text contains an invalid character.
IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.

pi

public void pi(String target,
               String instruction)
        throws IllegalStateException,
               IllegalArgumentException,
               InvalidXMLException,
               IOException
Notification of 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, then it will be set to XMLEventListenerStates.BEFORE_DTD_DECLARATION, otherwise the state will not be changed.

Parameters:
target - an identification of the application at which the instruction is targeted, not null.
instruction - the instruction, can be null, which is equivalent to an empty string.
Throws:
IllegalStateException - if getState() == ERROR_STATE.
IllegalArgumentException - if target == null.
InvalidXMLException - if the specified text contains an invalid character.
IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.

endDocument

public void endDocument()
                 throws IllegalStateException,
                        IOException
Notification of the end of the document. After calling this method, none of the other notification methods can be called until reset() is called.

Throws:
IllegalStateException - if getState() == UNINITIALIZED || getState() == DOCUMENT_ENDED.
IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.


See http://xmlenc.sourceforge.net/.