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:

• S0: BEFORE_XML_DECLARATION
• S1: BEFORE_DTD_DECLARATION
• S2: BEFORE_ROOT_ELEMENT
• S3: START_TAG_OPEN
• S4: WITHIN_ELEMENT
• S5: AFTER_ROOT_ELEMENT
• S6: DOCUMENT_ENDED

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 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

Modifier and Type	Method	Description
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 Details

reset

void reset()

Resets this XML event listener. The state will be set to UNINITIALIZED.

getState

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

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

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

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

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

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

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

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

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

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 "<" 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.

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

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

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

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

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

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.