org.codehaus.stax2.typed

Interface TypedXMLStreamReader

All Superinterfaces:

XMLStreamConstants, XMLStreamReader

All Known Subinterfaces:

XMLStreamReader2

All Known Implementing Classes:

DOMWrappingReader, Stax2FilteredStreamReader, Stax2ReaderAdapter, Stax2ReaderImpl, StreamReader2Delegate

public interface TypedXMLStreamReader
extends XMLStreamReader

This interface provides a typed extension to XMLStreamReader. It defines methods for reading XML data and converting it into Java types.

Since:

3.0

Author:

Santiago.PericasGeertsen@sun.com, Tatu Saloranta

Field Summary

Fields inherited from interface javax.xml.stream.XMLStreamConstants

ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT

Method Summary

Methods

Modifier and Type	Method and Description
void	getAttributeAs(int index, TypedValueDecoder tvd) Generic access method that can be used for efficient decoding of additional types not support natively by the typed stream reader.
int	getAttributeAsArray(int index, TypedArrayDecoder tad) Method that allows reading contents of an attribute as an array of whitespace-separate tokens, decoded using specified decoder.
byte[]	getAttributeAsBinary(int index) Read an attribute value as a byte array.
byte[]	getAttributeAsBinary(int index, Base64Variant v)
boolean	getAttributeAsBoolean(int index) Read an attribute value as a boolean.
BigDecimal	getAttributeAsDecimal(int index)
double	getAttributeAsDouble(int index)
double[]	getAttributeAsDoubleArray(int index)
float	getAttributeAsFloat(int index)
float[]	getAttributeAsFloatArray(int index)
int	getAttributeAsInt(int index) Read an attribute value as a boolean.
int[]	getAttributeAsIntArray(int index) Read an attribute content as an int array.
BigInteger	getAttributeAsInteger(int index)
long	getAttributeAsLong(int index) Read an attribute value as a boolean.
long[]	getAttributeAsLongArray(int index)
QName	getAttributeAsQName(int index)
int	getAttributeIndex(String namespaceURI, String localName) Returns the index of the attribute whose local name is localName and URI is namespaceURI or -1 if no such attribute exists.
void	getElementAs(TypedValueDecoder tvd) Generic decoding method that can be used for efficient decoding of additional types not support natively by the typed stream reader.
byte[]	getElementAsBinary() Convenience method that can be used similar to read binary content instead of readElementAsBinary(byte[], int, int, org.codehaus.stax2.typed.Base64Variant), in cases where neither performance nor memory usage is a big concern.
byte[]	getElementAsBinary(Base64Variant variant) Convenience method that can be used similar to read binary content instead of readElementAsBinary(byte[], int, int, org.codehaus.stax2.typed.Base64Variant), in cases where neither performance nor memory usage is a big concern.
boolean	getElementAsBoolean() Read an element content as a boolean.
BigDecimal	getElementAsDecimal()
double	getElementAsDouble() Read an element content as a 64-bit floating point value.
float	getElementAsFloat() Read an element content as a 32-bit floating point value.
int	getElementAsInt() Read an element content as a 32-bit integer.
BigInteger	getElementAsInteger()
long	getElementAsLong() Read an element content as a 64-bit integer.
QName	getElementAsQName()
int	readElementAsArray(TypedArrayDecoder tad) Read an element content as an array of tokens.
int	readElementAsBinary(byte[] resultBuffer, int offset, int maxLength)
int	readElementAsBinary(byte[] resultBuffer, int offset, int maxLength, Base64Variant variant) Read element content as decoded byte sequence; possibly only reading a fragment of all element content.
int	readElementAsDoubleArray(double[] resultBuffer, int offset, int length)
int	readElementAsFloatArray(float[] resultBuffer, int offset, int length)
int	readElementAsIntArray(int[] resultBuffer, int offset, int length) Read an element content as an int array.
int	readElementAsLongArray(long[] resultBuffer, int offset, int length)

Methods inherited from interface javax.xml.stream.XMLStreamReader

close, getAttributeCount, getAttributeLocalName, getAttributeName, getAttributeNamespace, getAttributePrefix, getAttributeType, getAttributeValue, getAttributeValue, getCharacterEncodingScheme, getElementText, getEncoding, getEventType, getLocalName, getLocation, getName, getNamespaceContext, getNamespaceCount, getNamespacePrefix, getNamespaceURI, getNamespaceURI, getNamespaceURI, getPIData, getPITarget, getPrefix, getProperty, getText, getTextCharacters, getTextCharacters, getTextLength, getTextStart, getVersion, hasName, hasNext, hasText, isAttributeSpecified, isCharacters, isEndElement, isStandalone, isStartElement, isWhiteSpace, next, nextTag, require, standaloneSet

Method Detail

getElementAsBoolean

boolean getElementAsBoolean()
                            throws XMLStreamException

Read an element content as a boolean. The lexical representation of a boolean is defined by the XML Schema boolean data type. Whitespace MUST be collapsed according to the whiteSpace facet for the XML Schema boolean data type. An exception is thrown if, after whitespace is collapsed, the resulting sequence of characters is not in the lexical space defined by the XML Schema boolean data type. (note: allowed lexical values are canonicals "true" and "false", as well as non-canonical "0" and "1")

These are the pre- and post-conditions of calling this method:

• Precondition: the current event is START_ELEMENT.
• Postcondition: the current event is the corresponding END_ELEMENT.

Throws:

XMLStreamException - If unable to access content

TypedXMLStreamException - If unable to convert the resulting character sequence into an XML Schema boolean value.

getElementAsInt

int getElementAsInt()
                    throws XMLStreamException

Read an element content as a 32-bit integer. The lexical representation of a integer is defined by the XML Schema integer data type. Whitespace MUST be collapsed according to the whiteSpace facet for the XML Schema integer data type. An exception is thrown if, after whitespace is collapsed, the resulting sequence of characters is not in the lexical space defined by the XML Schema integer data type.

These are the pre and post conditions of calling this method:

• Precondition: the current event is START_ELEMENT.
• Postcondition: the current event is the corresponding END_ELEMENT.

Throws:

XMLStreamException - If unable to access content

TypedXMLStreamException - If unable to convert the resulting character sequence into a Java (32-bit) integer.

getElementAsLong

long getElementAsLong()
                      throws XMLStreamException

Read an element content as a 64-bit integer. The lexical representation of a integer is defined by the XML Schema integer data type. Whitespace MUST be collapsed according to the whiteSpace facet for the XML Schema integer data type. An exception is thrown if, after whitespace is collapsed, the resulting sequence of characters is not in the lexical space defined by the XML Schema integer data type.

These are the pre and post conditions of calling this method:

• Precondition: the current event is START_ELEMENT.
• Postcondition: the current event is the corresponding END_ELEMENT.

Throws:

XMLStreamException - If unable to access content

TypedXMLStreamException - If unable to convert the resulting character sequence into a Java (64-bit) integer.

getElementAsFloat

float getElementAsFloat()
                        throws XMLStreamException

Read an element content as a 32-bit floating point value. The lexical representation is defined by the XML Schema float data type. Whitespace MUST be collapsed according to the whiteSpace facet for the XML Schema float data type. An exception is thrown if, after whitespace is collapsed, the resulting sequence of characters is not in the lexical space defined by the XML Schema integer data type.
Note that valid representations include basic Java textual representations, as well as 3 special tokens: "INF", "-INF" and "NaN"

These are the pre and post conditions of calling this method:

• Precondition: the current event is START_ELEMENT.
• Postcondition: the current event is the corresponding END_ELEMENT.

Throws:

XMLStreamException - If unable to access content

TypedXMLStreamException - If unable to convert the resulting character sequence into a Java float

getElementAsDouble

double getElementAsDouble()
                          throws XMLStreamException

Read an element content as a 64-bit floating point value. The lexical representation is defined by the XML Schema double data type. Whitespace MUST be collapsed according to the whiteSpace facet for the XML Schema double data type. An exception is thrown if, after whitespace is collapsed, the resulting sequence of characters is not in the lexical space defined by the XML Schema integer data type.
Note that valid representations include basic Java textual representations, as well as 3 special tokens: "INF", "-INF" and "NaN"

These are the pre and post conditions of calling this method:

• Precondition: the current event is START_ELEMENT.
• Postcondition: the current event is the corresponding END_ELEMENT.

Throws:

XMLStreamException - If unable to access content

TypedXMLStreamException - If unable to convert the resulting character sequence into a Java double

getElementAsInteger

BigInteger getElementAsInteger()
                               throws XMLStreamException

Throws:

XMLStreamException

getElementAsDecimal

BigDecimal getElementAsDecimal()
                               throws XMLStreamException

Throws:

XMLStreamException

getElementAsQName

QName getElementAsQName()
                        throws XMLStreamException

Throws:

XMLStreamException

getElementAsBinary

byte[] getElementAsBinary()
                          throws XMLStreamException

Convenience method that can be used similar to read binary content instead of readElementAsBinary(byte[], int, int, org.codehaus.stax2.typed.Base64Variant), in cases where neither performance nor memory usage is a big concern.

Note: base64 variant defaults to Base64Variants.MIME.

Throws:

XMLStreamException

See Also:

readElementAsBinary(byte[], int, int, org.codehaus.stax2.typed.Base64Variant)

getElementAsBinary

byte[] getElementAsBinary(Base64Variant variant)
                          throws XMLStreamException

Convenience method that can be used similar to read binary content instead of readElementAsBinary(byte[], int, int, org.codehaus.stax2.typed.Base64Variant), in cases where neither performance nor memory usage is a big concern.

Parameters:

variant - Base64 variant content is in; needed to decode alternative variants ("modified base64")

Throws:

XMLStreamException

See Also:

readElementAsBinary(byte[], int, int, org.codehaus.stax2.typed.Base64Variant)

getElementAs

void getElementAs(TypedValueDecoder tvd)
                  throws XMLStreamException

Generic decoding method that can be used for efficient decoding of additional types not support natively by the typed stream reader. When method is called, stream reader will collect all textual content of the current element (effectively doing something similar to a call to XMLStreamReader.getElementText(), and then call one of decode methods defined in TypedValueDecoder. The only difference is that passed value will be trimmed: that is, any leading or trailing white space will be removed prior to calling decode method. After the call, passed decoder object will have decoded and stored value (if succesful) or thrown an exception (if not).

The main benefit of using this method (over just getting all content by calling XMLStreamReader.getElementText() is efficiency: the stream reader can efficiently gather all textual content necessary and pass it to the decoder, often avoiding construction of intemediate Strings.

These are the pre- and post-conditions of calling this method:

• Precondition: the current event is START_ELEMENT.
• Postcondition: the current event is the corresponding END_ELEMENT.

Note that caller has to know more specific type of decoder, since the base interface does not specify methods for accessing actual decoded value.

Throws:

XMLStreamException

readElementAsBinary

int readElementAsBinary(byte[] resultBuffer,
                      int offset,
                      int maxLength,
                      Base64Variant variant)
                        throws XMLStreamException

Read element content as decoded byte sequence; possibly only reading a fragment of all element content. The lexical representation of a byte array is defined by the XML Schema base64Binary data type. Whitespace MUST be collapsed according to the whiteSpace facet for the XML Schema base64Binary data type. An exception is thrown if content is not in the lexical space defined by the XML Schema base64Binary data type.

Each call will read at least one decoded byte (and no more than the specified maximum length), if there is any content remaining. If none is available and END_ELEMENT is encountered, -1 is returned.

These are the pre and post conditions of calling this method:

• Precondition: the current event is either START_ELEMENT, or a textual event (CHARACTERS, CDATA), or END_ELEMENT (END_ELEMENT is allowed for convenience; if so, no read operation is tried, and -1 is returned immediately
• Postcondition: the current event is the corresponding END_ELEMENT, if all remaining binary content was read, or CHARACTERS if only a portion of the array was read

Additionally, caller MUST start decoding at START_ELEMENT; if the first decode calls is at CHARACTERS or CDATA event, results are not defined: result may be an exception, or invalid data being returned. Implementations are encouraged to throw an exception if possible, to make it easier to figure out the problem.

This method can be called multiple times until the cursor is positioned at the corresponding END_ELEMENT event. Stated differently, after the method is called for the first time, the cursor will move and remain in the CHARACTERS position while there are potentially more bytes available for reading.

Parameters:

resultBuffer - Array in which to copy decoded bytes.

offset - Starting offset of the first decoded byte within result buffer

maxLength - Maximun number of bytes to decode with this call

Returns:

The number of bytes actually decoded and returned, if any were available; -1 if there is no more content. If any content was copied, value must be less or equal than maxLength Note that this value is not guaranteed to equal maxLength even if enough content was available; that is, implementations can return shorter sections if they choose to, down to and including returning zero (0) if it was not possible to decode a full base64 triplet (3 output bytes from 4 input characters).

Throws:

IllegalArgumentException - If resultBuffer is null or offset is less than 0.

XMLStreamException

readElementAsBinary

int readElementAsBinary(byte[] resultBuffer,
                      int offset,
                      int maxLength)
                        throws XMLStreamException

Throws:

XMLStreamException

readElementAsIntArray

int readElementAsIntArray(int[] resultBuffer,
                        int offset,
                        int length)
                          throws XMLStreamException

Read an element content as an int array. The lexical representation of a int array is defined by the following XML schema type:

    <xs:simpleType name="intArray">
       <xs:list itemType="xs:int"/>
    </xs:simpleType>

whose lexical space is a list of space-separated ints. Whitespace MUST be collapsed according to the whiteSpace facet for the intArray type shown above. An exception is thrown if, after whitespace is collapsed, the resulting sequence of characters is not in the lexical space defined by the intArray data type.

These are the pre and post conditions of calling this method:

• Precondition: the current event is either START_ELEMENT, or a textual event (CHARACTERS, CDATA), or END_ELEMENT (END_ELEMENT is allowed for convenience; if so, no read operation is tried, and -1 is returned immediately
• Postcondition: the current event is the corresponding END_ELEMENT or CHARACTERS if only a portion of the array has been copied thus far.

This method can be called multiple times until the cursor is positioned at the corresponding END_ELEMENT event. Stated differently, after the method is called for the first time, the cursor will move and remain in the CHARACTERS position while there are more bytes available for reading.

Parameters:

resultBuffer - The array in which to copy the ints.

offset - The index in the array from which copying starts.

length - The maximun number of ints to copy. Minimum value is 1; others an IllegalArgumentException is thrown

Returns:

The number of ints actually copied which must be less or equal than length, but at least one if any ints found. If not, -1 is returned to signal end of ints to parse.

Throws:

IllegalStateException - If called on event other than START_ELEMENT, END_ELEMENT, or CHARACTERS (which resulted from an earlier call)

XMLStreamException

readElementAsLongArray

int readElementAsLongArray(long[] resultBuffer,
                         int offset,
                         int length)
                           throws XMLStreamException

Throws:

XMLStreamException

readElementAsFloatArray

int readElementAsFloatArray(float[] resultBuffer,
                          int offset,
                          int length)
                            throws XMLStreamException

Throws:

XMLStreamException

readElementAsDoubleArray

int readElementAsDoubleArray(double[] resultBuffer,
                           int offset,
                           int length)
                             throws XMLStreamException

Throws:

XMLStreamException

readElementAsArray

int readElementAsArray(TypedArrayDecoder tad)
                       throws XMLStreamException

Read an element content as an array of tokens. This is done by reader tokenizing textual content by white space, and sending each token to specified decoder for decoding. This is repeated as long as element content has more tokens and decoder can accept more values.

These are the pre- and post-conditions of calling this method:

• Precondition: the current event is either START_ELEMENT, or a textual event (CHARACTERS, CDATA), or END_ELEMENT (END_ELEMENT is allowed for convenience; if so, no read operation is tried, and -1 is returned immediately
• Postcondition: the current event is the corresponding END_ELEMENT or CHARACTERS if only a portion of the array has been copied thus far.

This method can be called multiple times until the cursor is positioned at the corresponding END_ELEMENT event. Stated differently, after the method is called for the first time, the cursor will move and remain in the CHARACTERS position while there are more bytes available for reading.

Note: passed decoder must accept at least one value, reader will not verify capacity before calling it with the first token.

Returns:

Number of elements decoded, or -1 to indicate that there was no more element content tokens to decode.

Throws:

IllegalStateException - If called on event other than START_ELEMENT, END_ELEMENT, or CHARACTERS (which resulted from an earlier call)

XMLStreamException

getAttributeIndex

int getAttributeIndex(String namespaceURI,
                    String localName)

Returns the index of the attribute whose local name is localName and URI is namespaceURI or -1 if no such attribute exists.

Parameters:

namespaceURI - The attribute's namespace URI. Values of null and "" are considered the same, i.e. "no namespace" (or "empty" namespace)

localName - The attribute's local name.

Returns:

The attribute's index or -1 if no such attribute exists.

Throws:

IllegalStateException - If this is not a START_ELEMENT event

XMLStreamException - If unable to convert the resulting character sequence into an XML Schema boolean value.

getAttributeAsBoolean

boolean getAttributeAsBoolean(int index)
                              throws XMLStreamException

Read an attribute value as a boolean. The lexical representation of a boolean is defined by the XML Schema boolean data type. Whitespace MUST be collapsed according to the whiteSpace facet for the XML Schema boolean data type. An exception is thrown if, after whitespace is collapsed, the resulting sequence of characters is not in the lexical space defined by the XML Schema boolean data type.

Parameters:

index - The attribute's index as returned by getAttributeIndex(String, String)

Throws:

IllegalStateException - If this is not a START_ELEMENT event.

XMLStreamException - If unable to convert the resulting character sequence into an XML Schema boolean value.

getAttributeAsInt

int getAttributeAsInt(int index)
                      throws XMLStreamException

Read an attribute value as a boolean. The lexical representation of a boolean is defined by the XML Schema integer data type. Whitespace MUST be collapsed according to the whiteSpace facet for the type. An exception is thrown if, after whitespace is collapsed, the resulting sequence of characters is not in the lexical space defined by the XML Schema integer data type.

Parameters:

index - The attribute's index as returned by getAttributeIndex(String, String)

Throws:

IllegalStateException - If this is not a START_ELEMENT event.

XMLStreamException - If unable to convert the resulting character sequence into an XML Schema boolean value.

getAttributeAsLong

long getAttributeAsLong(int index)
                        throws XMLStreamException

Read an attribute value as a boolean. The lexical representation of a boolean is defined by the XML Schema long data type. Whitespace MUST be collapsed according to the whiteSpace facet for the type. An exception is thrown if, after whitespace is collapsed, the resulting sequence of characters is not in the lexical space defined by the XML Schema long data type.

Parameters:

index - The attribute's index as returned by getAttributeIndex(String, String)

Throws:

IllegalStateException - If this is not a START_ELEMENT event.

XMLStreamException - If unable to convert the resulting character sequence into an XML Schema boolean value.

getAttributeAsFloat

float getAttributeAsFloat(int index)
                          throws XMLStreamException

Throws:

XMLStreamException

getAttributeAsDouble

double getAttributeAsDouble(int index)
                            throws XMLStreamException

Throws:

XMLStreamException

getAttributeAsInteger

BigInteger getAttributeAsInteger(int index)
                                 throws XMLStreamException

Throws:

XMLStreamException

getAttributeAsDecimal

BigDecimal getAttributeAsDecimal(int index)
                                 throws XMLStreamException

Throws:

XMLStreamException

getAttributeAsQName

QName getAttributeAsQName(int index)
                          throws XMLStreamException

Throws:

XMLStreamException

getAttributeAs

void getAttributeAs(int index,
                  TypedValueDecoder tvd)
                    throws XMLStreamException

Generic access method that can be used for efficient decoding of additional types not support natively by the typed stream reader. The main benefit of using this method is that the stream reader can efficient gather all textual content necessary and pass it to the decoder, often avoiding construction of intemediate Strings.

As with getElementAs(org.codehaus.stax2.typed.TypedValueDecoder), value passed to a decode method will be trimmed of any leading or trailing white space.

Throws:

XMLStreamException

getAttributeAsBinary

byte[] getAttributeAsBinary(int index)
                            throws XMLStreamException

Read an attribute value as a byte array. The lexical representation of a byte array is defined by the XML Schema base64Binary data type. Whitespace MUST be collapsed according to the whiteSpace facet for the XML Schema base64Binary data type. An exception is thrown if, after whitespace is collapsed, the resulting sequence of characters is not in the lexical space defined by the XML Schema base64Binary data type.

Parameters:

index - The attribute's index as returned by getAttributeIndex(String, String).

Returns:

An array of bytes with the content.

Throws:

IllegalStateException - If this is not a START_ELEMENT or ATTRIBUTE event.

XMLStreamException - If unable to convert the resulting character sequence into an XML Schema boolean value.

getAttributeAsBinary

byte[] getAttributeAsBinary(int index,
                          Base64Variant v)
                            throws XMLStreamException

Throws:

XMLStreamException

getAttributeAsIntArray

int[] getAttributeAsIntArray(int index)
                             throws XMLStreamException

Read an attribute content as an int array. The lexical representation of a int array is defined by the following XML schema type:

    <xs:simpleType name="intArray">
       <xs:list itemType="xs:int"/>
    </xs:simpleType>

whose lexical space is a list of space-separated ints. Whitespace MUST be collapsed according to the whiteSpace facet for the intArray type shown above. An exception is thrown if, after whitespace is collapsed, the resulting sequence of characters is not in the lexical space defined by the intArray data type.

Parameters:

index - The attribute's index as returned by getAttributeIndex(String, String).

Returns:

An array of ints with the content.

Throws:

IllegalStateException - If this is not a START_ELEMENT or ATTRIBUTE event.

XMLStreamException - If unable to convert the resulting character sequence into an XML Schema boolean value.

getAttributeAsLongArray

long[] getAttributeAsLongArray(int index)
                               throws XMLStreamException

Throws:

XMLStreamException

getAttributeAsFloatArray

float[] getAttributeAsFloatArray(int index)
                                 throws XMLStreamException

Throws:

XMLStreamException

getAttributeAsDoubleArray

double[] getAttributeAsDoubleArray(int index)
                                   throws XMLStreamException

Throws:

XMLStreamException

getAttributeAsArray

int getAttributeAsArray(int index,
                      TypedArrayDecoder tad)
                        throws XMLStreamException

Method that allows reading contents of an attribute as an array of whitespace-separate tokens, decoded using specified decoder.

Returns:

Number of tokens decoded, 0 if none found

Throws:

XMLStreamException