org.znerd.xmlenc
Interface XMLEventListener

All Known Subinterfaces:
StatefulXMLEventListener

public interface XMLEventListener
extends XMLEventListenerStates

Interface for XML event listeners.

Since:
xmlenc 0.30
Version:
$Revision: 1.4 $ $Date: 2003/04/29 08:50:18 $
Author:
Ernst de Haan (znerd@FreeBSD.org)

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 listener.
 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 XMLEventListenerStates.UNINITIALIZED.

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 XMLEventListenerStates.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).

getState

public XMLEventListenerState getState()
Returns the current state of this listener.
Returns:
the current state, cannot be null.

declaration

public void declaration()
                 throws IllegalStateException,
                        IOException
Notification of an 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"?gt;
Throws:
IllegalStateException - if getState() != BEFORE_XML_DECLARATION.
IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.

dtd

public void dtd(String name,
                String publicID,
                String systemID)
         throws IllegalStateException,
                IllegalArgumentException,
                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.

startTag

public void startTag(String type)
              throws IllegalStateException,
                     IllegalArgumentException,
                     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 XMLEventListenerStates.ERROR_STATE.

attribute

public void attribute(String name,
                      String value)
               throws IllegalStateException,
                      IllegalArgumentException,
                      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.

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


Copyright © Ernst de Haan
See http://xmlenc.sourceforge.net/.