Package org.apache.sis.internal.storage.xml.stream

Class StaxStreamReader

java.lang.Object

org.apache.sis.internal.storage.xml.stream.StaxStreamIO

org.apache.sis.internal.storage.xml.stream.StaxStreamReader

All Implemented Interfaces:

AutoCloseable, Runnable, Spliterator<AbstractFeature>, XMLStreamConstants

Direct Known Subclasses:

Reader

public abstract class StaxStreamReader
extends StaxStreamIO
implements XMLStreamConstants, Spliterator<AbstractFeature>, Runnable

Base class of Apache SIS readers of XML files using STAX parser. This class is itself an spliterator over all Feature instances found in the XML file, with the following restrictions:

• tryAdvance(Consumer) shall returns the features in the order they are declared in the XML file.
• tryAdvance(Consumer) shall not return null value.
• Modifications of the XML file are not allowed while an iteration is in progress.
• A StaxStreamReader instance can iterate over the features only once; if a new iteration is wanted, a new StaxStreamReader instance must be created.

This is a helper class for DataStore implementations. Readers for a given specification should extend this class and implement methods as in the following example:

Example:

Readers can be used like below:

Multi-threading

This class and subclasses are not tread-safe. Synchronization shall be done by the DataStore that contains the StaxStreamReader instance.

Since:

0.8

Version:

0.8

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Spliterator

Spliterator.OfDouble, Spliterator.OfInt, Spliterator.OfLong, Spliterator.OfPrimitive<T extends Object,T_CONS extends Object,T_SPLITR extends Spliterator.OfPrimitive<T,T_CONS,T_SPLITR>>

Field Summary

Fields

Modifier and Type	Field	Description
private boolean	isNextDone	true if the reader already moved to the next element.
protected final XMLStreamReader	reader	The XML stream reader.
private Unmarshaller	unmarshaller	The unmarshaller reserved to this reader usage, created only when first needed and kept until this reader is closed.

Fields inherited from class org.apache.sis.internal.storage.xml.stream.StaxStreamIO

owner, stream

Fields inherited from interface java.util.Spliterator

CONCURRENT, DISTINCT, IMMUTABLE, NONNULL, ORDERED, SIZED, SORTED, SUBSIZED

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

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	StaxStreamReader(StaxDataStore owner)	Creates a new XML reader for the given data store.

Method Summary

Modifier and Type	Method	Description
protected final String	canNotParseFile()	Returns an error message for BackingStoreException.
int	characteristics()	Returns the characteristics of the iteration over feature instances.
void	close()	Closes the input stream and releases any resources used by this XML reader.
protected final String	endOfFile()	Returns an error message for EOFException.
long	estimateSize()	Returns the sentinel value meaning that the number of elements is too expensive to compute.
protected final Date	getElementAsDate()	Returns the current value of XMLStreamReader.getElementText() as a date, or null if that value is null or empty.
protected final Double	getElementAsDouble()	Returns the current value of XMLStreamReader.getElementText() as a floating point number, or null if that value is null or empty.
protected final Integer	getElementAsInteger()	Returns the current value of XMLStreamReader.getElementText() as an integer, or null if that value is null or empty.
protected final List<String>	getElementAsList()	Returns the current value of XMLStreamReader.getElementText() as a list of strings, or null if that value is null or empty.
protected final Temporal	getElementAsTemporal()	Returns the current value of XMLStreamReader.getElementText() as a temporal object, or null if that value is null or empty.
protected final URI	getElementAsURI()	Returns the current value of XMLStreamReader.getElementText() as a URI, or null if that value is null or empty.
protected final String	getElementText()	Returns the current value of XMLStreamReader.getElementText(), or null if that value is null or empty.
protected final XMLStreamReader	getSubReader(QName tagName)	Returns a XML stream reader over only a portion of the document, from given position inclusive until the end of the given element exclusive.
protected final void	moveToRootElement(Predicate<String> isNamespace, String localName)	Moves the cursor to the first start element and verifies that it is the expected element.
protected final String	nestedElement(String name)	Returns an error message saying that nested elements are not allowed.
protected final int	next()	Gets next parsing event.
protected static boolean	parseBoolean(String value)	Parses the given string as a boolean value.
protected static double	parseDouble(String value)	Parses the given text as a XML floating point number.
final void	run()	Invokes close() and wraps checked exceptions in a BackingStoreException.
protected final void	skipUntilEnd(QName tagName)	Skips all remaining elements until we reach the end of the given tag.
abstract boolean	tryAdvance(Consumer<? super AbstractFeature> action)	Performs the given action on the next feature instance, or returns null if there are no more features to parse.
Spliterator<AbstractFeature>	trySplit()	Returns null by default since non-binary XML files are hard to split.
protected final <T> T	unmarshal(Class<T> type)	Delegates to JAXB the unmarshalling of a part of XML document, starting from the current element (inclusive).

Methods inherited from class org.apache.sis.internal.storage.xml.stream.StaxStreamIO

errors, getMarshallerPool

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Spliterator

forEachRemaining, getComparator, getExactSizeIfKnown, hasCharacteristics

Field Details

reader

protected final XMLStreamReader reader

The XML stream reader.

isNextDone

private boolean isNextDone

true if the reader already moved to the next element. This happen if unmarshal(Class) has been invoked. In such case, the next call to XMLStreamReader.next() needs to be replaced by a call to XMLStreamReader.getEventType().

unmarshaller

private Unmarshaller unmarshaller

The unmarshaller reserved to this reader usage, created only when first needed and kept until this reader is closed.

See Also:

• unmarshal(Class)

Constructor Details

StaxStreamReader

protected StaxStreamReader(StaxDataStore owner)
                    throws Exception

Creates a new XML reader for the given data store.

Parameters:

owner - the data store for which this reader is created.

Throws:

DataStoreException - if the input type is not recognized or the data store is closed.

XMLStreamException - if an error occurred while opening the XML file.

IOException - if an error occurred while preparing the input stream.

Exception - if another kind of error occurred while closing a previous stream.

Method Details

characteristics

public int characteristics()

Returns the characteristics of the iteration over feature instances. The iteration is assumed Spliterator.ORDERED in the declaration order in the XML file. The iteration is Spliterator.NONNULL (i.e. tryAdvance(Consumer) is not allowed to return null value) and Spliterator.IMMUTABLE (i.e. we do not support modification of the XML file while an iteration is in progress).

Specified by:

characteristics in interface Spliterator<AbstractFeature>

Returns:

characteristics of iteration over the features in the XML file.

tryAdvance

public abstract boolean tryAdvance(Consumer<? super AbstractFeature> action)
                            throws BackingStoreException

Performs the given action on the next feature instance, or returns null if there are no more features to parse.

Specified by:

tryAdvance in interface Spliterator<AbstractFeature>

Parameters:

action - the action to perform on the next feature instances.

Returns:

true if a feature has been found, or false if we reached the end of XML file.

Throws:

BackingStoreException - if an error occurred while parsing the next feature instance. The cause may be DataStoreException, IOException, URISyntaxException or various RuntimeException among others.

trySplit

public Spliterator<AbstractFeature> trySplit()

Returns null by default since non-binary XML files are hard to split.

Specified by:

trySplit in interface Spliterator<AbstractFeature>

Returns:

null.

estimateSize

public long estimateSize()

Returns the sentinel value meaning that the number of elements is too expensive to compute.

Specified by:

estimateSize in interface Spliterator<AbstractFeature>

Returns:

Long.MAX_VALUE.

getSubReader

protected final XMLStreamReader getSubReader(QName tagName)
                                      throws XMLStreamException

Returns a XML stream reader over only a portion of the document, from given position inclusive until the end of the given element exclusive. Nested elements of the same name, if any, will be ignored.

Parameters:

tagName - name of the tag to close.

Returns:

a reader over a portion of the stream.

Throws:

XMLStreamException - if this XML reader has been closed.

moveToRootElement

protected final void moveToRootElement(Predicate<String> isNamespace,
 String localName)
                                throws EOFException,
XMLStreamException,
DataStoreContentException

Moves the cursor to the first start element and verifies that it is the expected element. This method is useful for skipping comments, entity declarations, etc. before the root element.

If the reader is already on a start element, then this method does not move forward. Once a root element has been found, this method verifies that the namespace and local name are the expected ones, or throws an exception otherwise.

Parameters:

isNamespace - a predicate receiving the namespace in argument (which may be null) and returning whether that namespace is the expected one.

localName - the expected name of the root element.

Throws:

EOFException - if no start element has been found before we reached the end of file.

XMLStreamException - if an error occurred while reading the XML stream.

DataStoreContentException - if the root element is not the expected one.

skipUntilEnd

protected final void skipUntilEnd(QName tagName)
                           throws EOFException,
XMLStreamException

Skips all remaining elements until we reach the end of the given tag. Nested tags of the same name, if any, are also skipped.

The current event when this method is invoked must be XMLStreamConstants.START_ELEMENT. After this method invocation, the current event will be XMLStreamConstants.END_ELEMENT.

Parameters:

tagName - name of the tag to close.

Throws:

EOFException - if end tag could not be found.

XMLStreamException - if an error occurred while reading the XML stream.

next

protected final int next()
                  throws XMLStreamException

Gets next parsing event. This method should be used instead of XMLStreamReader.next() when the while (next()) loop may contain call to the unmarshal(Class) method.

Returns:

one of the XMLStreamConstants.

Throws:

XMLStreamException - if an error occurred while fetching the next event.

getElementText

protected final String getElementText()
                               throws XMLStreamException

Returns the current value of XMLStreamReader.getElementText(), or null if that value is null or empty.

The current event when this method is invoked must be XMLStreamConstants.START_ELEMENT. After this method invocation, the current event will be XMLStreamConstants.END_ELEMENT.

Returns:

the current text element, or null if empty.

Throws:

XMLStreamException - if a text element cannot be returned.

getElementAsURI

protected final URI getElementAsURI()
                             throws XMLStreamException,
URISyntaxException

Returns the current value of XMLStreamReader.getElementText() as a URI, or null if that value is null or empty.

Returns:

the current text element as a URI, or null if empty.

Throws:

XMLStreamException - if a text element cannot be returned.

URISyntaxException - if the text cannot be parsed as a URI.

getElementAsInteger

protected final Integer getElementAsInteger()
                                     throws XMLStreamException

Returns the current value of XMLStreamReader.getElementText() as an integer, or null if that value is null or empty.

Returns:

the current text element as an integer, or null if empty.

Throws:

XMLStreamException - if a text element cannot be returned.

NumberFormatException - if the text cannot be parsed as an integer.

getElementAsDouble

protected final Double getElementAsDouble()
                                   throws XMLStreamException

Returns the current value of XMLStreamReader.getElementText() as a floating point number, or null if that value is null or empty.

Returns:

the current text element as a floating point number, or null if empty.

Throws:

XMLStreamException - if a text element cannot be returned.

NumberFormatException - if the text cannot be parsed as a floating point number.

See Also:

• parseDouble(String)

getElementAsDate

protected final Date getElementAsDate()
                               throws XMLStreamException

Returns the current value of XMLStreamReader.getElementText() as a date, or null if that value is null or empty.

Returns:

the current text element as a date, or null if empty.

Throws:

XMLStreamException - if a text element cannot be returned.

DateTimeParseException - if the text cannot be parsed as a date.

getElementAsTemporal

protected final Temporal getElementAsTemporal()
                                       throws XMLStreamException

Returns the current value of XMLStreamReader.getElementText() as a temporal object, or null if that value is null or empty.

Returns:

the current text element as a temporal object, or null if empty.

Throws:

XMLStreamException - if a text element cannot be returned.

DateTimeParseException - if the text cannot be parsed as a date.

getElementAsList

protected final List<String> getElementAsList()
                                       throws XMLStreamException

Returns the current value of XMLStreamReader.getElementText() as a list of strings, or null if that value is null or empty.

Returns:

the current text element as a list.

Throws:

XMLStreamException - if a text element cannot be returned.

parseDouble

protected static double parseDouble(String value)
                             throws NumberFormatException

Parses the given text as a XML floating point number. This method performs the same parsing than Double.valueOf(String) with the addition of INF and -INF values. The following summarizes the special values (note that parsing is case-sensitive):

• NaN — a XML value which is also understood natively by Double.valueOf(String).
• INF — a XML value which is processed by this method.
• -INF — a XML value which is processed by this method.
• +INF — illegal XML value, nevertheless processed by this method.
• Infinity — a Double.valueOf(String) specific value.

Note: this method duplicates DatatypeConverter.parseDouble(String) work, but avoid synchronization or volatile field cost of DatatypeConverter.

Parameters:

value - the text to parse.

Returns:

the floating point value for the given text.

Throws:

NumberFormatException - if parsing failed.

See Also:

• getElementAsDouble()
• DatatypeConverter.parseDouble(String)

parseBoolean

protected static boolean parseBoolean(String value)

Parses the given string as a boolean value. This method performs the same parsing than Boolean.parseBoolean(String) with one extension: the "0" value is considered as false and the "1" value as true.

Note: this method duplicates DatatypeConverter.parseBoolean(String) work (except for its behavior in case of invalid value), but avoid synchronization or volatile field cost of DatatypeConverter.

Parameters:

value - the string value to parse as a boolean.

Returns:

true if the boolean is equal to "true" or "1".

See Also:

• DatatypeConverter.parseBoolean(String)

unmarshal

protected final <T> T unmarshal(Class<T> type)
                         throws XMLStreamException,
JAXBException

Delegates to JAXB the unmarshalling of a part of XML document, starting from the current element (inclusive). This method assumes that the reader is on XMLStreamConstants.START_ELEMENT. After this method invocation, the reader will be on the event after XMLStreamConstants.END_ELEMENT; this implies that the caller will need to invoke XMLStreamReader.getEventType() instead of XMLStreamReader.next().

Type Parameters:

T - compile-time value of the type argument.

Parameters:

type - expected type of the object to unmarshal.

Returns:

the unmarshalled object, or null if none.

Throws:

XMLStreamException - if the XML stream is closed.

JAXBException - if an error occurred during unmarshalling.

ClassCastException - if the unmarshalling result is not of the expected type.

See Also:

• Unmarshaller.unmarshal(XMLStreamReader, Class)

close

public void close()
           throws Exception

Closes the input stream and releases any resources used by this XML reader. This reader cannot be used anymore after this method has been invoked.

Specified by:

close in interface AutoCloseable

Overrides:

close in class StaxStreamIO

Throws:

XMLStreamException - if an error occurred while releasing XML reader resources.

IOException - if an error occurred while closing the input stream.

Exception

run

public final void run()
               throws BackingStoreException

Invokes close() and wraps checked exceptions in a BackingStoreException. This method is defined for allowing this StaxStreamReader to be given to BaseStream.onClose(Runnable).

Specified by:

run in interface Runnable

Throws:

BackingStoreException

endOfFile

protected final String endOfFile()

Returns an error message for EOFException. This a convenience method for a frequently-used error.

Returns:

a localized error message for end of file error.

canNotParseFile

protected final String canNotParseFile()

Returns an error message for BackingStoreException. This a convenience method for tryAdvance(Consumer) implementations. The error message will contain the current line and column number if available.

Returns:

a localized error message for a file that cannot be parsed.

nestedElement

protected final String nestedElement(String name)

Returns an error message saying that nested elements are not allowed.

Parameters:

name - the name of the nested element found.

Returns:

a localized error message for forbidden nested element.