Top Description Methods
org.codehaus.stax2.typed

public Interface TypedXMLStreamReader

extends XMLStreamReader
Known Direct Subinterfaces
org.codehaus.stax2.XMLStreamReader2
Imports
javax.xml.stream.XMLStreamException, .XMLStreamReader, java.math.BigDecimal, .BigInteger, javax.xml.namespace.QName
This interface provides a typed extension to javax.xml.stream.XMLStreamReader. It defines methods for reading XML data and converting it into Java types.
Authors
[email protected], Tatu Saloranta
Since
3.0

Method Summary

Modifier and TypeMethod and Description
public 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.

public int

Returns:

Number of tokens decoded, 0 if none found
getAttributeAsArray(int index, TypedArrayDecoder tad)

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

public byte[]

Returns:

An array of bytes with the content.
getAttributeAsBinary(int
The attribute's index as returned by getAttributeIndex(String, String).
index)

Read an attribute value as a byte array.

public byte[]
getAttributeAsBinary(int index, Base64Variant v)

public boolean
getAttributeAsBoolean(int
The attribute's index as returned by getAttributeIndex(String, String)
index)

Read an attribute value as a boolean.

public BigDecimal
getAttributeAsDecimal(int index)

public double
getAttributeAsDouble(int index)

public double[]
getAttributeAsDoubleArray(int index)

public float
getAttributeAsFloat(int index)

public float[]
getAttributeAsFloatArray(int index)

public int
getAttributeAsInt(int
The attribute's index as returned by getAttributeIndex(String, String)
index)

Read an attribute value as a boolean.

public int[]

Returns:

An array of ints with the content.
getAttributeAsIntArray(int
The attribute's index as returned by getAttributeIndex(String, String).
index)

Read an attribute content as an int array.

public BigInteger
getAttributeAsInteger(int index)

public long
getAttributeAsLong(int
The attribute's index as returned by getAttributeIndex(String, String)
index)

Read an attribute value as a boolean.

public long[]
getAttributeAsLongArray(int index)

public QName
getAttributeAsQName(int index)

public int

Returns:

The attribute's index or -1 if no such attribute exists.
getAttributeIndex(String
The attribute's namespace URI. Values of null and "" are considered the same, i.e. "no namespace" (or "empty" namespace)
namespaceURI, String
The attribute's local name.
localName)

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

public 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.

public byte[]
getElementAsBinary()

Convenience method that can be used similar to read binary content instead of readElementAsBinary, in cases where neither performance nor memory usage is a big concern.

public byte[]
getElementAsBinary(Base64Variant
Base64 variant content is in; needed to decode alternative variants ("modified base64")
variant)

Convenience method that can be used similar to read binary content instead of readElementAsBinary, in cases where neither performance nor memory usage is a big concern.

public boolean
getElementAsBoolean()

Read an element content as a boolean.

public BigDecimal
getElementAsDecimal()

public double
getElementAsDouble()

Read an element content as a 64-bit floating point value.

public float
getElementAsFloat()

Read an element content as a 32-bit floating point value.

public int
getElementAsInt()

Read an element content as a 32-bit integer.

public BigInteger
getElementAsInteger()

public long
getElementAsLong()

Read an element content as a 64-bit integer.

public QName
getElementAsQName()

public int

Returns:

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

Read an element content as an array of tokens.

public int

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).
readElementAsBinary(byte[]
Array in which to copy decoded bytes.
resultBuffer, int
Starting offset of the first decoded byte within result buffer
offset, int
Maximum number of bytes to decode with this call
maxLength, Base64Variant variant)

Read element content as decoded byte sequence; possibly only reading a fragment of all element content.

public int
readElementAsBinary(byte[] resultBuffer, int offset, int maxLength)

public int
readElementAsDoubleArray(double[] resultBuffer, int offset, int length)

public int
readElementAsFloatArray(float[] resultBuffer, int offset, int length)

public int

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.
readElementAsIntArray(int[]
The array in which to copy the ints.
resultBuffer, int
The index in the array from which copying starts.
offset, int
The maximun number of ints to copy. Minimum value is 1; others an IllegalArgumentException is thrown
length)

Read an element content as an int array.

public int
readElementAsLongArray(long[] resultBuffer, int offset, int length)

Inherited from javax.xml.stream.XMLStreamReader:
closegetAttributeCountgetAttributeLocalNamegetAttributeNamegetAttributeNamespacegetAttributePrefixgetAttributeTypegetAttributeValuegetAttributeValuegetCharacterEncodingSchemegetElementTextgetEncodinggetEventTypegetLocalNamegetLocationgetNamegetNamespaceContextgetNamespaceCountgetNamespacePrefixgetNamespaceURIgetNamespaceURIgetNamespaceURIgetPIDatagetPITargetgetPrefixgetPropertygetTextgetTextCharactersgetTextCharactersgetTextLengthgetTextStartgetVersionhasNamehasNexthasTextisAttributeSpecifiedisCharactersisEndElementisStandaloneisStartElementisWhiteSpacenextnextTagrequirestandaloneSet

Method Detail

getAttributeAsback to summary
public 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, value passed to a decode method will be trimmed of any leading or trailing white space.

getAttributeAsArrayback to summary
public 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:int

Number of tokens decoded, 0 if none found

getAttributeAsBinaryback to summary
public 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:int

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

Returns:byte[]

An array of bytes with the content.

Exceptions
XMLStreamException:
If unable to convert the resulting character sequence into an XML Schema boolean value.
IllegalStateException:
If this is not a START_ELEMENT or ATTRIBUTE event.
getAttributeAsBinaryback to summary
public byte[] getAttributeAsBinary(int index, Base64Variant v) throws XMLStreamException
getAttributeAsBooleanback to summary
public 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:int

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

Exceptions
XMLStreamException:
If unable to convert the resulting character sequence into an XML Schema boolean value.
IllegalStateException:
If this is not a START_ELEMENT event.
getAttributeAsDecimalback to summary
public BigDecimal getAttributeAsDecimal(int index) throws XMLStreamException
getAttributeAsDoubleback to summary
public double getAttributeAsDouble(int index) throws XMLStreamException
getAttributeAsDoubleArrayback to summary
public double[] getAttributeAsDoubleArray(int index) throws XMLStreamException
getAttributeAsFloatback to summary
public float getAttributeAsFloat(int index) throws XMLStreamException
getAttributeAsFloatArrayback to summary
public float[] getAttributeAsFloatArray(int index) throws XMLStreamException
getAttributeAsIntback to summary
public 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:int

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

Exceptions
XMLStreamException:
If unable to convert the resulting character sequence into an XML Schema boolean value.
IllegalStateException:
If this is not a START_ELEMENT event.
getAttributeAsIntArrayback to summary
public 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:int

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

Returns:int[]

An array of ints with the content.

Exceptions
XMLStreamException:
If unable to convert the resulting character sequence into an XML Schema boolean value.
IllegalStateException:
If this is not a START_ELEMENT or ATTRIBUTE event.
getAttributeAsIntegerback to summary
public BigInteger getAttributeAsInteger(int index) throws XMLStreamException
getAttributeAsLongback to summary
public 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:int

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

Exceptions
XMLStreamException:
If unable to convert the resulting character sequence into an XML Schema boolean value.
IllegalStateException:
If this is not a START_ELEMENT event.
getAttributeAsLongArrayback to summary
public long[] getAttributeAsLongArray(int index) throws XMLStreamException
getAttributeAsQNameback to summary
public QName getAttributeAsQName(int index) throws XMLStreamException
getAttributeIndexback to summary
public 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:String

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

localName:String

The attribute's local name.

Returns:int

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

Exceptions
IllegalStateException:
If this is not a START_ELEMENT event
getElementAsback to summary
public 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 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 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.

getElementAsBinaryback to summary
public byte[] getElementAsBinary() throws XMLStreamException

Convenience method that can be used similar to read binary content instead of readElementAsBinary, in cases where neither performance nor memory usage is a big concern.

Note

base64 variant defaults to Base64Variants#MIME.

See Also
readElementAsBinary
getElementAsBinaryback to summary
public byte[] getElementAsBinary(Base64Variant variant) throws XMLStreamException

Convenience method that can be used similar to read binary content instead of readElementAsBinary, in cases where neither performance nor memory usage is a big concern.

Parameters
variant:Base64Variant

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

See Also
readElementAsBinary
getElementAsBooleanback to summary
public 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.
Exceptions
XMLStreamException:
If unable to access content
TypedXMLStreamException:
If unable to convert the resulting character sequence into an XML Schema boolean value.
getElementAsDecimalback to summary
public BigDecimal getElementAsDecimal() throws XMLStreamException
getElementAsDoubleback to summary
public 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.
Exceptions
XMLStreamException:
If unable to access content
TypedXMLStreamException:
If unable to convert the resulting character sequence into a Java double
getElementAsFloatback to summary
public 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.
Exceptions
XMLStreamException:
If unable to access content
TypedXMLStreamException:
If unable to convert the resulting character sequence into a Java float
getElementAsIntback to summary
public 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.
Exceptions
XMLStreamException:
If unable to access content
TypedXMLStreamException:
If unable to convert the resulting character sequence into a Java (32-bit) integer.
getElementAsIntegerback to summary
public BigInteger getElementAsInteger() throws XMLStreamException
getElementAsLongback to summary
public 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.
Exceptions
XMLStreamException:
If unable to access content
TypedXMLStreamException:
If unable to convert the resulting character sequence into a Java (64-bit) integer.
getElementAsQNameback to summary
public QName getElementAsQName() throws XMLStreamException
readElementAsArrayback to summary
public 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:int

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

Exceptions
IllegalStateException:
If called on event other than START_ELEMENT, END_ELEMENT, or CHARACTERS (which resulted from an earlier call)
readElementAsBinaryback to summary
public 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:byte[]

Array in which to copy decoded bytes.

offset:int

Starting offset of the first decoded byte within result buffer

maxLength:int

Maximum number of bytes to decode with this call

Returns:int

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).

Exceptions
IllegalArgumentException:
If resultBuffer is null or offset is less than 0.
readElementAsBinaryback to summary
public int readElementAsBinary(byte[] resultBuffer, int offset, int maxLength) throws XMLStreamException
readElementAsDoubleArrayback to summary
public int readElementAsDoubleArray(double[] resultBuffer, int offset, int length) throws XMLStreamException
readElementAsFloatArrayback to summary
public int readElementAsFloatArray(float[] resultBuffer, int offset, int length) throws XMLStreamException
readElementAsIntArrayback to summary
public 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:int[]

The array in which to copy the ints.

offset:int

The index in the array from which copying starts.

length:int

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

Returns:int

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.

Exceptions
IllegalStateException:
If called on event other than START_ELEMENT, END_ELEMENT, or CHARACTERS (which resulted from an earlier call)
readElementAsLongArrayback to summary
public int readElementAsLongArray(long[] resultBuffer, int offset, int length) throws XMLStreamException