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

All Methods Instance Methods Abstract Methods
Modifier and Type	Method	Description
`void`	`attribute(java.lang.String name, java.lang.String value)`	Adds an attribute to the current element.
`void`	`cdata(java.lang.String text)`	Notification of a CDATA section.
`void`	`comment(java.lang.String text)`	Notification of a comment.
`void`	`declaration()`	Notification of an XML declaration.
`void`	`dtd(java.lang.String name, java.lang.String publicID, java.lang.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(java.lang.String text)`	Notification of a PCDATA section (as a `String`).
`void`	`pi(java.lang.String target, java.lang.String instruction)`	Notification of a processing instruction.
`void`	`reset()`	Resets this XML event listener.
`void`	`setState(XMLEventListenerState newState, java.lang.String[] newElementStack)`	Sets the state of this XML event listener.
`void`	`startTag(java.lang.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(java.lang.String whitespace)`	Notification of ignorable whitespace (as a `String`).

- Method Detail
  - reset
```
void reset()
```
    Resets this XML event listener. The state will be set to UNINITIALIZED.
  - getState
```
XMLEventListenerState getState()
                        throws java.lang.UnsupportedOperationException
```
    Returns the current state of this outputter.
    
    Returns:
    
    the current state, cannot be null.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if this is not a stateful XML event listener.
  - setState
```
void setState(XMLEventListenerState newState,
              java.lang.String[] newElementStack)
       throws java.lang.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:
    
    java.lang.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 java.lang.IllegalStateException,
                 java.io.IOException
```
    Notification of an XML declaration. No encoding is explicitly specified.
    
    Throws:
    
    java.lang.IllegalStateException - if getState() != BEFORE_XML_DECLARATION.
    
    java.io.IOException - if an I/O error occurs; this will set the state to ERROR_STATE.
  - dtd
```
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
```
    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:
    
    java.lang.IllegalStateException - if getState() != BEFORE_XML_DECLARATION&& getState() != BEFORE_DTD_DECLARATION.
    
    java.lang.IllegalArgumentException - if name == null || (publicID != null && systemID == null).
    
    java.io.IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.
    
    InvalidXMLException
  - startTag
```
void startTag(java.lang.String type)
       throws java.lang.IllegalStateException,
              java.lang.IllegalArgumentException,
              InvalidXMLException,
              java.io.IOException
```
    Notification of an element start tag.
    
    Parameters:
    
    type - the type of the tag to start, not null.
    
    Throws:
    
    java.lang.IllegalStateException - if getState() != BEFORE_XML_DECLARATION && getState() != BEFORE_DTD_DECLARATION && getState() != BEFORE_ROOT_ELEMENT && getState() != START_TAG_OPEN && getState() != WITHIN_ELEMENT.
    
    java.lang.IllegalArgumentException - if type == null.
    
    java.io.IOException - if an I/O error occurs; this will set the state to ERROR_STATE.
    
    InvalidXMLException
  - attribute
```
void attribute(java.lang.String name,
               java.lang.String value)
        throws java.lang.IllegalStateException,
               java.lang.IllegalArgumentException,
               InvalidXMLException,
               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.
    
    Parameters:
    
    name - the name of the attribute, not null.
    
    value - the value of the attribute, not null.
    
    Throws:
    
    java.lang.IllegalStateException - if getState() != XMLEventListenerStates.START_TAG_OPEN.
    
    java.lang.IllegalArgumentException - if name == null || value == null.
    
    java.io.IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.
    
    InvalidXMLException
  - endTag
```
void endTag()
     throws java.lang.IllegalStateException,
            java.io.IOException
```
    Notification of an element end tag.
    
    Throws:
    
    java.lang.IllegalStateException - if getState() != START_TAG_OPEN && getState() != WITHIN_ELEMENT
    
    java.io.IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.
  - pcdata
```
void pcdata(java.lang.String text)
     throws java.lang.IllegalStateException,
            java.lang.IllegalArgumentException,
            InvalidXMLException,
            java.io.IOException
```
    Notification of a PCDATA section (as a String).
    
    Parameters:
    
    text - the PCDATA section contents, not null.
    
    Throws:
    
    java.lang.IllegalStateException - if getState() != START_TAG_OPEN && getState() != WITHIN_ELEMENT
    
    java.lang.IllegalArgumentException - if text == null.
    
    InvalidXMLException - if the specified text contains an invalid character.
    
    java.io.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 java.lang.IllegalStateException,
            java.lang.IllegalArgumentException,
            java.lang.IndexOutOfBoundsException,
            InvalidXMLException,
            java.io.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:
    
    java.lang.IllegalStateException - if getState() != START_TAG_OPEN && getState() != WITHIN_ELEMENT
    
    java.lang.IllegalArgumentException - if ch == null || start < 0 || start >= ch.length || length < 0.
    
    java.lang.IndexOutOfBoundsException - if start + length > ch.length.
    
    InvalidXMLException - if the specified text contains an invalid character.
    
    java.io.IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.
  - cdata
```
void cdata(java.lang.String text)
    throws java.lang.IllegalStateException,
           java.lang.IllegalArgumentException,
           InvalidXMLException,
           java.io.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:
    
    java.lang.IllegalStateException - if getState() != START_TAG_OPEN && getState() != WITHIN_ELEMENT
    
    java.lang.IllegalArgumentException - if text == null.
    
    InvalidXMLException - if the specified text contains an invalid character.
    
    java.io.IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.
  - whitespace
```
void whitespace(java.lang.String whitespace)
         throws java.lang.IllegalStateException,
                java.lang.IllegalArgumentException,
                InvalidXMLException,
                java.io.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:
    
    java.lang.IllegalStateException - if getState() == ERROR_STATE.
    
    java.lang.IllegalArgumentException - if whitespace == null.
    
    InvalidXMLException - if the specified text contains an invalid character.
    
    java.io.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 java.lang.IllegalStateException,
                java.lang.IllegalArgumentException,
                java.lang.IndexOutOfBoundsException,
                InvalidXMLException,
                java.io.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:
    
    java.lang.IllegalStateException - if getState() == ERROR_STATE.
    
    java.lang.IllegalArgumentException - if ch == null || start < 0 || start >= ch.length || length < 0.
    
    java.lang.IndexOutOfBoundsException - if start + length > ch.length.
    
    InvalidXMLException - if the specified text contains an invalid character.
    
    java.io.IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.
  - comment
```
void comment(java.lang.String text)
      throws java.lang.IllegalStateException,
             java.lang.IllegalArgumentException,
             InvalidXMLException,
             java.io.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:
    
    java.lang.IllegalStateException - if getState() == ERROR_STATE.
    
    java.lang.IllegalArgumentException - if text == null.
    
    InvalidXMLException - if the specified text contains an invalid character.
    
    java.io.IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.
  - pi
```
void pi(java.lang.String target,
        java.lang.String instruction)
 throws java.lang.IllegalStateException,
        java.lang.IllegalArgumentException,
        InvalidXMLException,
        java.io.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:
    
    java.lang.IllegalStateException - if getState() == ERROR_STATE.
    
    java.lang.IllegalArgumentException - if target == null.
    
    InvalidXMLException - if the specified text contains an invalid character.
    
    java.io.IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.
  - endDocument
```
void endDocument()
          throws java.lang.IllegalStateException,
                 java.io.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:
    
    java.lang.IllegalStateException - if getState() == UNINITIALIZED || getState() == DOCUMENT_ENDED.
    
    java.io.IOException - if an I/O error occurs; this will set the state to XMLEventListenerStates.ERROR_STATE.

Interface XMLEventListener

State transitions

Field Summary

Fields inherited from interface org.znerd.xmlenc.XMLEventListenerStates

Method Summary

Method Detail

reset

getState

setState

declaration

dtd

startTag

attribute

endTag

pcdata

pcdata

cdata

whitespace

whitespace

comment

pi

endDocument