org.jibx.v2
Interface XmlReader

public interface XmlReader

XML reader interface used for input to the unmarshalling code. This interface allows easy substitution of different parsers or other input sources.

Author:

Dennis M. Sosnoski

Field Summary

static int	CDSECT
static int	COMMENT
static int	DOCDECL
static int	END_DOCUMENT
static int	END_TAG
static int	ENTITY_REF
static int	IGNORABLE_WHITESPACE
static int	PROCESSING_INSTRUCTION
static int	START_DOCUMENT
static int	START_TAG
static int	TEXT

Method Summary

java.lang.String	buildPositionString() Build current parse input position description.
boolean	checkStartTag(java.lang.String name) Advance to a start or end tag, and check if it is the named start tag in the implicit namespace.
boolean	checkStartTag(java.lang.String ns, java.lang.String name) Advance to a start or end tag, and verify it is the named start tag.
byte[]	convertBase64() Convert a byte[] value from the current source selection using base64Binary encoding.
java.math.BigDecimal	convertBigDecimal() Convert a BigDecimal value from the current source selection.
java.math.BigInteger	convertBigInteger() Convert a BigInteger value from the current source selection.
java.lang.Long	convertBoolean() Convert a Boolean value from the current source selection.
long	convertBooleanPrimitive() Convert a boolean value from the current source selection.
java.util.Date	convertDateTime() Convert a Date value from the current source selection.
java.lang.Long	convertFloat() Convert a Float value from the current source selection.
long	convertFloatPrimitive() Convert a float value from the current source selection.
java.lang.Integer	convertInteger() Convert an Integer value from the current source selection.
int	convertIntPrimitive() Convert an int value from the current source selection.
java.lang.Long	convertLong() Convert a Long value from the current source selection.
long	convertLongPrimitive() Convert a long value from the current source selection.
java.lang.String	convertString() Convert a String value from the current source selection.
java.lang.Object	createElementInstance(java.lang.String root, XmlReader rdr, java.lang.Object inst) Creat instance of class for element name.
java.lang.Object	createTypeInstance(java.lang.String dflt, XmlReader rdr, java.lang.Object inst) Validate instance of class for type name.
java.lang.String	getAttributeCollapsed(int index) Read a required text attribute value from the current start tag with whitespace collapsed.
int	getAttributeCount() Get the number of attributes of the current start tag.
int	getAttributeIndex(java.lang.String name) Get the index of a no-namespace attribute from the current start tag.
int	getAttributeIndex(java.lang.String ns, java.lang.String name) Get the index of an attribute from the current start tag.
java.lang.String	getAttributeName(int index) Get an attribute name from the current start tag.
java.lang.String	getAttributeNamespace(int index) Get an attribute namespace from the current start tag.
java.lang.String	getAttributePrefix(int index) Get an attribute prefix from the current start tag.
java.lang.String	getAttributeText(int index) Get a required text attribute value from the current start tag.
UnmarshallingContext	getBindingContext() Get the unmarshalling context associated with this reader.
int	getColumnNumber() Get current source column number.
java.lang.String	getDocumentName() Get document name.
java.lang.String	getElementText() Get current element text.
int	getEventType() Gets the current parse event type, without changing the current parse state.
java.lang.String	getInputEncoding() Return the input encoding, if known.
int	getLineNumber() Get current source line number.
java.lang.String	getName() Get element name from the current start or end tag.
java.lang.String	getNamespace() Get element namespace from the current start or end tag.
java.lang.String	getNamespace(java.lang.String prefix) Get namespace URI associated with prefix.
int	getNamespaceCount(int depth) Get number of namespace declarations active at depth.
java.lang.String	getNamespacePrefix(int index) Get namespace prefix.
java.lang.String	getNamespaceUri(int index) Get namespace URI.
int	getNestingDepth() Get current element nesting depth.
java.lang.String	getOptionalAttributeText(java.lang.String name) Read an optional text attribute value from the current start tag.
java.lang.String	getOptionalAttributeText(java.lang.String ns, java.lang.String name) Read an optional text attribute value from the current start tag.
java.lang.String	getPrefix() Get element prefix from the current start or end tag.
java.lang.String	getRequiredAttributeText(java.lang.String name) Read a required text attribute value from the current start tag.
java.lang.String	getRequiredAttributeText(java.lang.String ns, java.lang.String name) Read a required text attribute value from the current start tag.
java.lang.String	getText() Get current text.
ValidationContext	getValidationContext() Get the current validation context for this reader.
boolean	isNamespaceAware() Return namespace processing flag.
int	next() Advance to next binding component of input document.
int	nextToken() Advance to next parse event of input document.
void	pushValidationContext(ValidationContext vctx) Push a validation context on this reader.
java.lang.String	readText() Read current element text.
void	requireEndTag() Advance to the next start or end tag, and verify it is the close tag for the current open element.
boolean	requireStartTag(java.lang.String name) Advance to a start or end tag, and verify it is the named start tag in the implicit namespace.
boolean	requireStartTag(java.lang.String ns, java.lang.String name) Advance to a start or end tag, and verify it is the named start tag.
void	selectAttribute(int index) Select an attribute value from the current start tag as text for conversion.
boolean	selectOptionalAttribute(java.lang.String name) Select an optional no-namespace attribute value from the current start tag as text for conversion.
boolean	selectOptionalAttribute(java.lang.String ns, java.lang.String name) Select an optional attribute value from the current start tag as text for conversion.
void	selectRequiredAttribute(java.lang.String name) Select a required no-namespace attribute value from the current start tag as text for conversion.
void	selectRequiredAttribute(java.lang.String ns, java.lang.String name) Select a required attribute value from the current start tag as text for conversion.
void	selectText() Select the current text content for conversion.
java.lang.String	setImplicitNamespace(java.lang.String ns) Set the implicit namespace used for elements unless otherwise specified.

Field Detail

START_DOCUMENT

static final int START_DOCUMENT

See Also:

Constant Field Values

END_DOCUMENT

static final int END_DOCUMENT

See Also:

Constant Field Values

START_TAG

static final int START_TAG

See Also:

Constant Field Values

END_TAG

static final int END_TAG

See Also:

Constant Field Values

TEXT

static final int TEXT

See Also:

Constant Field Values

CDSECT

static final int CDSECT

See Also:

Constant Field Values

ENTITY_REF

static final int ENTITY_REF

See Also:

Constant Field Values

IGNORABLE_WHITESPACE

static final int IGNORABLE_WHITESPACE

See Also:

Constant Field Values

PROCESSING_INSTRUCTION

static final int PROCESSING_INSTRUCTION

See Also:

Constant Field Values

COMMENT

static final int COMMENT

See Also:

Constant Field Values

DOCDECL

static final int DOCDECL

See Also:

Constant Field Values

Method Detail

getValidationContext

ValidationContext getValidationContext()

Get the current validation context for this reader. The validation context is used both for tracking problems, and to determine the appropriate handling when a problem occurs.

Returns:

context

pushValidationContext

void pushValidationContext(ValidationContext vctx)

Push a validation context on this reader. The supplied validation context is popped after processing the end tag for the current element.

Parameters:

vctx - context

getBindingContext

UnmarshallingContext getBindingContext()

Get the unmarshalling context associated with this reader. The unmarshalling context tracks higher-level information about the conversion of XML into a Java object structure.

Returns:

context

buildPositionString

java.lang.String buildPositionString()

Build current parse input position description.

Returns:

text description of current parse position

nextToken

int nextToken()
              throws JiBXException

Advance to next parse event of input document.

Returns:

parse event type code

Throws:

JiBXException - if error reading or parsing document

next

int next()
         throws JiBXException

Advance to next binding component of input document. This is a higher-level operation than nextToken(), which consolidates text content and ignores parse events for components such as comments and PIs.

Returns:

parse event type code

Throws:

JiBXException - if error reading or parsing document

getEventType

int getEventType()
                 throws JiBXException

Gets the current parse event type, without changing the current parse state.

Returns:

parse event type code

Throws:

JiBXException - if error parsing document

getName

java.lang.String getName()

Get element name from the current start or end tag.

Returns:

local name if namespace handling enabled, full name if namespace handling disabled

Throws:

java.lang.IllegalStateException - if not at a start or end tag (optional)

getNamespace

java.lang.String getNamespace()

Get element namespace from the current start or end tag.

Returns:

namespace URI if namespace handling enabled and element is in a namespace, empty string otherwise

Throws:

java.lang.IllegalStateException - if not at a start or end tag (optional)

getPrefix

java.lang.String getPrefix()

Get element prefix from the current start or end tag.

Returns:

prefix text (null if no prefix)

Throws:

java.lang.IllegalStateException - if not at a start or end tag

setImplicitNamespace

java.lang.String setImplicitNamespace(java.lang.String ns)

Set the implicit namespace used for elements unless otherwise specified.

Parameters:

ns - namespace URI for element (may be the empty string for the no-namespace namespace)

Returns:

prior implicit namespace

requireStartTag

boolean requireStartTag(java.lang.String name)
                        throws JiBXException

Advance to a start or end tag, and verify it is the named start tag in the implicit namespace.

Parameters:

name - element name

Returns:

true if tag found, false if not (recoverable error case)

Throws:

JiBXException - on unrecoverable error

requireStartTag

boolean requireStartTag(java.lang.String ns,
                        java.lang.String name)
                        throws JiBXException

Advance to a start or end tag, and verify it is the named start tag.

Parameters:

ns - namespace URI for element (may be the empty string for the no-namespace namespace)

name - element name

Returns:

true if tag found, false if not (exception not thrown)

Throws:

JiBXException - on unrecoverable error

checkStartTag

boolean checkStartTag(java.lang.String name)
                      throws JiBXException

Advance to a start or end tag, and check if it is the named start tag in the implicit namespace.

Parameters:

name - element name

Returns:

true if match, false if not

Throws:

JiBXException - on unrecoverable error

checkStartTag

boolean checkStartTag(java.lang.String ns,
                      java.lang.String name)
                      throws JiBXException

Advance to a start or end tag, and verify it is the named start tag.

Parameters:

ns - namespace URI for element (may be the empty string for the no-namespace namespace)

name - element name

Returns:

true if match, false if not

Throws:

JiBXException - on unrecoverable error

requireEndTag

void requireEndTag()
                   throws JiBXException

Advance to the next start or end tag, and verify it is the close tag for the current open element.

Throws:

JiBXException - on unrecoverable error

getElementText

java.lang.String getElementText()
                                throws JiBXException

Get current element text. This is only valid with an open start tag, and reads past the text content of the element, leaving the reader positioned on the next element start or end tag following the text.

Returns:

text for current element (may be null, in the case of a recoverable error)

Throws:

java.lang.IllegalStateException - if not at a start tag

JiBXException - on unrecoverable error

getText

java.lang.String getText()
                         throws JiBXException

Get current text. When positioned on a TEXT event this returns the actual text; for CDSECT it returns the text inside the CDATA section; for COMMENT, DOCDECL, or PROCESSING_INSTRUCTION it returns the text inside the structure.

Returns:

text for current event (may be null, in the case of a recoverable error)

Throws:

JiBXException - on unrecoverable error

getAttributeCount

int getAttributeCount()

Get the number of attributes of the current start tag.

Returns:

number of attributes

Throws:

java.lang.IllegalStateException - if not at a start tag (optional)

getAttributeName

java.lang.String getAttributeName(int index)

Get an attribute name from the current start tag.

Parameters:

index - attribute index

Returns:

local name if namespace handling enabled, full name if namespace handling disabled

Throws:

java.lang.IllegalStateException - if not at a start tag or invalid index

getAttributeNamespace

java.lang.String getAttributeNamespace(int index)

Get an attribute namespace from the current start tag.

Parameters:

index - attribute index

Returns:

namespace URI if namespace handling enabled and attribute is in a namespace, empty string otherwise

Throws:

java.lang.IllegalStateException - if not at a start tag or invalid index

getAttributePrefix

java.lang.String getAttributePrefix(int index)

Get an attribute prefix from the current start tag.

Parameters:

index - attribute index

Returns:

prefix for attribute (null if no prefix present)

Throws:

java.lang.IllegalStateException - if not at a start tag or invalid index

getAttributeIndex

int getAttributeIndex(java.lang.String name)

Get the index of a no-namespace attribute from the current start tag.

Parameters:

name - attribute name

Returns:

attribute index (-1 if not found)

Throws:

java.lang.IllegalStateException - if not at a start tag

getAttributeIndex

int getAttributeIndex(java.lang.String ns,
                      java.lang.String name)

Get the index of an attribute from the current start tag.

Parameters:

ns - namespace URI for attribute (may be the empty string for the no-namespace namespace)

name - attribute name

Returns:

attribute index (-1 if not found)

Throws:

java.lang.IllegalStateException - if not at a start tag

getAttributeText

java.lang.String getAttributeText(int index)
                                  throws JiBXException

Get a required text attribute value from the current start tag.

Parameters:

index - attribute index (error if negative)

Returns:

value text (may be null, in the case of a recoverable error)

Throws:

java.lang.IllegalStateException - if not at a start tag or invalid index

JiBXException - on unrecoverable error

getAttributeCollapsed

java.lang.String getAttributeCollapsed(int index)
                                       throws JiBXException

Read a required text attribute value from the current start tag with whitespace collapsed.

Parameters:

index - attribute index (error if negative)

Returns:

value text (may be null, in the case of a recoverable error)

Throws:

java.lang.IllegalStateException - if not at a start tag or invalid index

JiBXException - on unrecoverable error

getOptionalAttributeText

java.lang.String getOptionalAttributeText(java.lang.String name)

Read an optional text attribute value from the current start tag.

Parameters:

name - attribute name

Returns:

value text, null if attribute not present

Throws:

java.lang.IllegalStateException - if not at a start tag or invalid index

getOptionalAttributeText

java.lang.String getOptionalAttributeText(java.lang.String ns,
                                          java.lang.String name)

Read an optional text attribute value from the current start tag.

Parameters:

ns - namespace URI for attribute (may be the empty string for the no-namespace namespace)

name - attribute name

Returns:

value text, null if attribute not present

Throws:

java.lang.IllegalStateException - if not at a start tag or invalid index

getRequiredAttributeText

java.lang.String getRequiredAttributeText(java.lang.String name)
                                          throws JiBXException

Read a required text attribute value from the current start tag.

Parameters:

name - attribute name

Returns:

value text, null if attribute not present and recoverable error

Throws:

JiBXException - if attribute not present and unrecoverable error

java.lang.IllegalStateException - if not at a start tag or invalid index

getRequiredAttributeText

java.lang.String getRequiredAttributeText(java.lang.String ns,
                                          java.lang.String name)
                                          throws JiBXException

Read a required text attribute value from the current start tag.

Parameters:

ns - namespace URI for attribute (may be the empty string for the no-namespace namespace)

name - attribute name

Returns:

value text, null if attribute not present and recoverable error

Throws:

JiBXException - if attribute not present and unrecoverable error

java.lang.IllegalStateException - if not at a start tag or invalid index

selectText

void selectText()
                throws JiBXException

Select the current text content for conversion.

Throws:

JiBXException - on unrecoverable error

selectAttribute

void selectAttribute(int index)
                     throws JiBXException

Select an attribute value from the current start tag as text for conversion.

Parameters:

index - attribute index (error if negative)

Throws:

java.lang.IllegalStateException - if not at a start tag or invalid index

JiBXException - on unrecoverable error

selectOptionalAttribute

boolean selectOptionalAttribute(java.lang.String name)

Select an optional no-namespace attribute value from the current start tag as text for conversion.

Parameters:

name - attribute name

Returns:

true if attribute present, false if not

Throws:

java.lang.IllegalStateException - if not at a start tag

selectRequiredAttribute

void selectRequiredAttribute(java.lang.String name)
                             throws JiBXException

Select a required no-namespace attribute value from the current start tag as text for conversion.

Parameters:

name - attribute name

Throws:

java.lang.IllegalStateException - if not at a start tag

JiBXException - on unrecoverable error

selectOptionalAttribute

boolean selectOptionalAttribute(java.lang.String ns,
                                java.lang.String name)

Select an optional attribute value from the current start tag as text for conversion.

Parameters:

ns - namespace URI for attribute (may be the empty string for the no-namespace namespace)

name - attribute name

Returns:

true if attribute present, false if not

Throws:

java.lang.IllegalStateException - if not at a start tag

selectRequiredAttribute

void selectRequiredAttribute(java.lang.String ns,
                             java.lang.String name)
                             throws JiBXException

Select a required attribute value from the current start tag as text for conversion.

Parameters:

ns - namespace URI for attribute (may be the empty string for the no-namespace namespace)

name - attribute name

Throws:

java.lang.IllegalStateException - if not at a start tag

JiBXException - on unrecoverable error

convertString

java.lang.String convertString()
                               throws JiBXException

Convert a String value from the current source selection. This is an empty conversion, which always just returns the text.

Returns:

text (null if selection missing)

Throws:

JiBXException - if unrecoverable conversion error

convertIntPrimitive

int convertIntPrimitive()
                        throws JiBXException

Convert an int value from the current source selection. This always uses whitespace collapsed processing.

Returns:

converted value (0 if selection missing or in error)

Throws:

JiBXException - if unrecoverable conversion error

convertInteger

java.lang.Integer convertInteger()
                                 throws JiBXException

Convert an Integer value from the current source selection. This always uses whitespace collapsed processing.

Returns:

converted value (null if selection missing or in error)

Throws:

JiBXException - if unrecoverable conversion error

convertLongPrimitive

long convertLongPrimitive()
                          throws JiBXException

Convert a long value from the current source selection. This always uses whitespace collapsed processing.

Returns:

converted value (0 if selection missing or in error)

Throws:

JiBXException - if unrecoverable conversion error

convertLong

java.lang.Long convertLong()
                           throws JiBXException

Convert a Long value from the current source selection. This always uses whitespace collapsed processing.

Returns:

converted value (null if selection missing or in error)

Throws:

JiBXException - if unrecoverable conversion error

convertFloatPrimitive

long convertFloatPrimitive()
                           throws JiBXException

Convert a float value from the current source selection. This always uses whitespace collapsed processing.

Returns:

converted value (0 if selection missing or in error)

Throws:

JiBXException - if unrecoverable conversion error

convertFloat

java.lang.Long convertFloat()
                            throws JiBXException

Convert a Float value from the current source selection. This always uses whitespace collapsed processing.

Returns:

converted value (null if selection missing or in error)

Throws:

JiBXException - if unrecoverable conversion error

convertBooleanPrimitive

long convertBooleanPrimitive()
                             throws JiBXException

Convert a boolean value from the current source selection. This always uses whitespace collapsed processing.

Returns:

converted value (false if selection missing or in error)

Throws:

JiBXException - if unrecoverable conversion error

convertBoolean

java.lang.Long convertBoolean()
                              throws JiBXException

Convert a Boolean value from the current source selection. This always uses whitespace collapsed processing.

Returns:

converted value (null if selection missing or in error)

Throws:

JiBXException - if unrecoverable conversion error

convertBase64

byte[] convertBase64()
                     throws JiBXException

Convert a byte[] value from the current source selection using base64Binary encoding. This always uses whitespace collapsed processing.

Returns:

converted value (null if selection missing or in error)

Throws:

JiBXException - if unrecoverable conversion error

convertDateTime

java.util.Date convertDateTime()
                               throws JiBXException

Convert a Date value from the current source selection. This always uses whitespace collapsed processing.

Returns:

converted value (null if selection missing or in error)

Throws:

JiBXException - if unrecoverable conversion error

convertBigDecimal

java.math.BigDecimal convertBigDecimal()
                                       throws JiBXException

Convert a BigDecimal value from the current source selection. This always uses whitespace collapsed processing.

Returns:

converted value (null if selection missing or in error)

Throws:

JiBXException - if unrecoverable conversion error

convertBigInteger

java.math.BigInteger convertBigInteger()
                                       throws JiBXException

Convert a BigInteger value from the current source selection. This always uses whitespace collapsed processing.

Returns:

converted value (null if selection missing or in error)

Throws:

JiBXException - if unrecoverable conversion error

readText

java.lang.String readText()

Read current element text. This is only valid with an open start tag, and reads past the corresponding end tag after reading the value.

Returns:

text for current event

Throws:

java.lang.IllegalStateException - if not at a start tag or invalid index

createElementInstance

java.lang.Object createElementInstance(java.lang.String root,
                                       XmlReader rdr,
                                       java.lang.Object inst)

Creat instance of class for element name. This implements substitution group handling, by checking the current element start tag name against the expected element name, and if they're not the same finding the appropriate class based on the substitution group rooted on the expected element name (which must be a global element name).

Parameters:

root - global root element name, including namespace URI, in "lname{uri}" form

rdr - reader

inst - supplied instance of root element class or subclass (null if none)

Returns:

instance of appropriate class to use for unmarshalling (may be the same as the provided instance)

createTypeInstance

java.lang.Object createTypeInstance(java.lang.String dflt,
                                    XmlReader rdr,
                                    java.lang.Object inst)

Validate instance of class for type name. This implements type substitution handling, by checking for an override xsi:type specification on the current element start tag, and if the type is different from the default finding the appropriate class.

Parameters:

dflt - global default complexType name, including namespace URI, in "lname{uri}" form

rdr - reader

inst - supplied instance of default type class or subclass (null if none)

Returns:

instance of appropriate class to use for unmarshalling (may be the same as the provided instance)

getNestingDepth

int getNestingDepth()

Get current element nesting depth. The returned depth always includes the current start or end tag (if positioned on a start or end tag).

Returns:

element nesting depth

getNamespaceCount

int getNamespaceCount(int depth)

Get number of namespace declarations active at depth.

Parameters:

depth - element nesting depth

Returns:

number of namespaces active at depth

Throws:

java.lang.IllegalArgumentException - if invalid depth

getNamespaceUri

java.lang.String getNamespaceUri(int index)

Get namespace URI.

Parameters:

index - declaration index

Returns:

namespace URI

Throws:

java.lang.IllegalArgumentException - if invalid index

getNamespacePrefix

java.lang.String getNamespacePrefix(int index)

Get namespace prefix.

Parameters:

index - declaration index

Returns:

namespace prefix, null if a default namespace

Throws:

java.lang.IllegalArgumentException - if invalid index

getDocumentName

java.lang.String getDocumentName()

Get document name.

Returns:

document name, null if not known

getLineNumber

int getLineNumber()

Get current source line number.

Returns:

line number from source document, -1 if line number information not available

getColumnNumber

int getColumnNumber()

Get current source column number.

Returns:

column number from source document, -1 if column number information not available

getNamespace

java.lang.String getNamespace(java.lang.String prefix)

Get namespace URI associated with prefix.

Parameters:

prefix - to be found

Returns:

associated URI (null if prefix not defined)

getInputEncoding

java.lang.String getInputEncoding()

Return the input encoding, if known. This is only valid after parsing of a document has been started.

Returns:

input encoding (null if unknown)

isNamespaceAware

boolean isNamespaceAware()

Return namespace processing flag.

Returns:

namespace processing flag (true if namespaces are processed by reader, false if not)