|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Interface for XML event listeners.
XMLEventListener
s. 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:
BEFORE_XML_DECLARATION
BEFORE_DTD_DECLARATION
BEFORE_ROOT_ELEMENT
START_TAG_OPEN
WITHIN_ELEMENT
AFTER_ROOT_ELEMENT
DOCUMENT_ENDED
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 |
public void reset()
UNINITIALIZED
.
public XMLEventListenerState getState() throws UnsupportedOperationException
null
.
UnsupportedOperationException
- if this is not a stateful XML event listener.public void setState(XMLEventListenerState newState, String[] newElementStack) throws IllegalArgumentException
Calling this method with UNINITIALIZED
as
the state is equivalent to calling reset()
.
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
.
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
).public void declaration() throws IllegalStateException, IOException
IllegalStateException
- if getState() != BEFORE_XML_DECLARATION
.
IOException
- if an I/O error occurs; this will set the state to
ERROR_STATE
.public void dtd(String name, String publicID, String systemID) throws IllegalStateException, IllegalArgumentException, InvalidXMLException, IOException
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">
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.
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
public void startTag(String type) throws IllegalStateException, IllegalArgumentException, InvalidXMLException, IOException
type
- the type of the tag to start, not null
.
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
public void attribute(String name, String value) throws IllegalStateException, IllegalArgumentException, InvalidXMLException, IOException
The attribute value is surrounded by single quotes.
name
- the name of the attribute, not null
.value
- the value of the attribute, not null
.
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
public void endTag() throws IllegalStateException, IOException
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
.public void pcdata(String text) throws IllegalStateException, IllegalArgumentException, InvalidXMLException, IOException
String
).
text
- the PCDATA section contents, not null
.
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
.public void pcdata(char[] ch, int start, int length) throws IllegalStateException, IllegalArgumentException, IndexOutOfBoundsException, InvalidXMLException, IOException
char
array).
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.
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
.public void cdata(String text) throws IllegalStateException, IllegalArgumentException, InvalidXMLException, IOException
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.
text
- the contents of the CDATA section, not null
.
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
.public void whitespace(String whitespace) throws IllegalStateException, IllegalArgumentException, InvalidXMLException, IOException
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.
whitespace
- the ignorable whitespace to be written, not null
.
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
.public void whitespace(char[] ch, int start, int length) throws IllegalStateException, IllegalArgumentException, IndexOutOfBoundsException, InvalidXMLException, IOException
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.
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.
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
.public void comment(String text) throws IllegalStateException, IllegalArgumentException, InvalidXMLException, IOException
"--"
.
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.
text
- the text for the comment be written, not null
.
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
.public void pi(String target, String instruction) throws IllegalStateException, IllegalArgumentException, InvalidXMLException, IOException
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.
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.
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
.public void endDocument() throws IllegalStateException, IOException
reset()
is called.
IllegalStateException
- if getState() == UNINITIALIZED
|| getState() == DOCUMENT_ENDED
.
IOException
- if an I/O error occurs; this will set the state to
XMLEventListenerStates.ERROR_STATE
.
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |