tuwien.auto.calimero.xml
Interface XMLReader

All Known Implementing Classes:

DefaultXMLReader

public interface XMLReader

XML reader interface for pull based reading of XML documents.

The reader only does non-validating processing, and resolves predefined XML entities.
This interface does not support XML namespaces for now, and has no methods for setting and requesting XML reader features/properties.
A reader based on pull parsing style only reads a little piece of a document at once, waiting for the user application to request the next chunk of data. So the application controls the progress of reading a XML document. The reader does not create nor maintain a representation of the entire document for the user (like a model parser would).

XML reader implementations don't need to be thread safe.

Field Summary

static int	CHAR_DATA Character data of an element.
static int	END_DOC End of XML document.
static int	END_TAG End of XML tag.
static int	NO_INPUT No input specified.
static int	START_DOC Start of XML document.
static int	START_TAG Start of XML tag.

Method Summary

void	close() Closes this XML reader.
void	complete(Element e) Reads until end of element e.
Element	getCurrent() Returns the current element read with the last invocation of read().
int	getLineNumber() Returns the line number for the current position in a XML input source processed by this XML reader.
int	getPosition() Returns the current logical position in a XML document for this XML reader.
int	read() Reads to the next XML element tag, a CDATA section or character data.
void	setInput(java.io.Reader input, boolean close) Sets the input source for this XML reader.

Field Detail

CHAR_DATA

static final int CHAR_DATA

Character data of an element.

This position identifier is especially important on mixed content in an element.
(Definition: An element type has mixed content when elements of that type may contain character data, optionally interspersed with child elements.)
So this position only occurs between START_TAG and END_TAG. Anyway, usually there is no mixed content and complete(Element) will be used after a START_TAG to read all character data into the supplied current element.

See Also:

Constant Field Values

END_DOC

static final int END_DOC

End of XML document.

See Also:

Constant Field Values

END_TAG

static final int END_TAG

End of XML tag.

See Also:

Constant Field Values

NO_INPUT

static final int NO_INPUT

No input specified.

See Also:

Constant Field Values

START_DOC

static final int START_DOC

Start of XML document.

See Also:

Constant Field Values

START_TAG

static final int START_TAG

Start of XML tag.

See Also:

Constant Field Values

Method Detail

close

void close()
           throws KNXMLException

Closes this XML reader.

If this XML reader is already closed, no action is performed. If for an input source was specified to get closed on invocation of this method, it is closed first (calling Reader.close().

Throws:

KNXMLException

complete

void complete(Element e)
              throws KNXMLException

Reads until end of element e.

All gathered relevant information is stored into e.

Parameters:

e - the element to be completed

Throws:

KNXMLException - if document is not well-formed, e.g. end of input or end-tag of parent element was reached before end of specified element

getCurrent

Element getCurrent()

Returns the current element read with the last invocation of read().

Returns:

current element or null if no element is available

getLineNumber

int getLineNumber()

Returns the line number for the current position in a XML input source processed by this XML reader.

On no input source, or before an input source is first read, 0 is returned.

Returns:

line number, or 0 if no line number is available

getPosition

int getPosition()

Returns the current logical position in a XML document for this XML reader.

The position is given with constants like START_DOC or similar. If no input was set or the reader is closed, NO_INPUT is returned.

Returns:

the logical position in the document

read

int read()
         throws KNXMLException

Reads to the next XML element tag, a CDATA section or character data.

The logical position returned by this method can also be obtained with getPosition().
Comments and processing instructions can be ignored, i.e. skipped on reading.

Returns:

the current logical position after reading

Throws:

KNXMLException - on read error or a not well-formed XML document

setInput

void setInput(java.io.Reader input,
              boolean close)

Sets the input source for this XML reader.

If this XML reader was already closed, setting a new input has no effect.

Parameters:

input - a reader with input, like obtained from EntityResolver.getInputReader(java.io.InputStream)

close - true if the specified input reader should be closed on close(), false to leave it open