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 returnnull
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 newStaxStreamReader
instance must be created.
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 theDataStore
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,
T_CONS, T_SPLITR extends Spliterator.OfPrimitive<T, T_CONS, T_SPLITR>> -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate boolean
true
if thereader
already moved to the next element.protected final XMLStreamReader
The XML stream reader.private 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
ConstructorsModifierConstructorDescriptionprotected
StaxStreamReader
(StaxDataStore owner) Creates a new XML reader for the given data store. -
Method Summary
Modifier and TypeMethodDescriptionprotected final String
Returns an error message forBackingStoreException
.int
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
Returns an error message forEOFException
.long
Returns the sentinel value meaning that the number of elements is too expensive to compute.protected final Date
Returns the current value ofXMLStreamReader.getElementText()
as a date, ornull
if that value is null or empty.protected final Double
Returns the current value ofXMLStreamReader.getElementText()
as a floating point number, ornull
if that value is null or empty.protected final Integer
Returns the current value ofXMLStreamReader.getElementText()
as an integer, ornull
if that value is null or empty.Returns the current value ofXMLStreamReader.getElementText()
as a list of strings, ornull
if that value is null or empty.protected final Temporal
Returns the current value ofXMLStreamReader.getElementText()
as a temporal object, ornull
if that value is null or empty.protected final URI
Returns the current value ofXMLStreamReader.getElementText()
as a URI, ornull
if that value is null or empty.protected final String
Returns the current value ofXMLStreamReader.getElementText()
, ornull
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()
Invokesclose()
and wraps checked exceptions in aBackingStoreException
.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 returnsnull
if there are no more features to parse.trySplit()
Returnsnull
by default since non-binary XML files are hard to split.protected final <T> T
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
The XML stream reader. -
isNextDone
private boolean isNextDonetrue
if thereader
already moved to the next element. This happen ifunmarshal(Class)
has been invoked. In such case, the next call toXMLStreamReader.next()
needs to be replaced by a call toXMLStreamReader.getEventType()
. -
unmarshaller
The unmarshaller reserved to this reader usage, created only when first needed and kept until this reader is closed.- See Also:
-
-
Constructor Details
-
StaxStreamReader
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 assumedSpliterator.ORDERED
in the declaration order in the XML file. The iteration isSpliterator.NONNULL
(i.e.tryAdvance(Consumer)
is not allowed to return null value) andSpliterator.IMMUTABLE
(i.e. we do not support modification of the XML file while an iteration is in progress).- Specified by:
characteristics
in interfaceSpliterator<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 returnsnull
if there are no more features to parse.- Specified by:
tryAdvance
in interfaceSpliterator<AbstractFeature>
- Parameters:
action
- the action to perform on the next feature instances.- Returns:
true
if a feature has been found, orfalse
if we reached the end of XML file.- Throws:
BackingStoreException
- if an error occurred while parsing the next feature instance. The cause may beDataStoreException
,IOException
,URISyntaxException
or variousRuntimeException
among others.
-
trySplit
Returnsnull
by default since non-binary XML files are hard to split.- Specified by:
trySplit
in interfaceSpliterator<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 interfaceSpliterator<AbstractFeature>
- Returns:
Long.MAX_VALUE
.
-
getSubReader
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
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 beXMLStreamConstants.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
Gets next parsing event. This method should be used instead ofXMLStreamReader.next()
when thewhile (next())
loop may contain call to theunmarshal(Class)
method.- Returns:
- one of the
XMLStreamConstants
. - Throws:
XMLStreamException
- if an error occurred while fetching the next event.
-
getElementText
Returns the current value ofXMLStreamReader.getElementText()
, ornull
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 beXMLStreamConstants.END_ELEMENT
.- Returns:
- the current text element, or
null
if empty. - Throws:
XMLStreamException
- if a text element cannot be returned.
-
getElementAsURI
Returns the current value ofXMLStreamReader.getElementText()
as a URI, ornull
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
Returns the current value ofXMLStreamReader.getElementText()
as an integer, ornull
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
Returns the current value ofXMLStreamReader.getElementText()
as a floating point number, ornull
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:
-
getElementAsDate
Returns the current value ofXMLStreamReader.getElementText()
as a date, ornull
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
Returns the current value ofXMLStreamReader.getElementText()
as a temporal object, ornull
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
Returns the current value ofXMLStreamReader.getElementText()
as a list of strings, ornull
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
Parses the given text as a XML floating point number. This method performs the same parsing thanDouble.valueOf(String)
with the addition ofINF
and-INF
values. The following summarizes the special values (note that parsing is case-sensitive):NaN
— a XML value which is also understood natively byDouble.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
— aDouble.valueOf(String)
specific value.
Note: this method duplicatesDatatypeConverter.parseDouble(String)
work, but avoid synchronization or volatile field cost ofDatatypeConverter
.- Parameters:
value
- the text to parse.- Returns:
- the floating point value for the given text.
- Throws:
NumberFormatException
- if parsing failed.- See Also:
-
parseBoolean
Parses the given string as a boolean value. This method performs the same parsing thanBoolean.parseBoolean(String)
with one extension: the "0" value is considered asfalse
and the "1" value astrue
.Note: this method duplicatesDatatypeConverter.parseBoolean(String)
work (except for its behavior in case of invalid value), but avoid synchronization or volatile field cost ofDatatypeConverter
.- Parameters:
value
- the string value to parse as a boolean.- Returns:
- true if the boolean is equal to "true" or "1".
- See Also:
-
unmarshal
Delegates to JAXB the unmarshalling of a part of XML document, starting from the current element (inclusive). This method assumes that the reader is onXMLStreamConstants.START_ELEMENT
. After this method invocation, the reader will be on the event afterXMLStreamConstants.END_ELEMENT
; this implies that the caller will need to invokeXMLStreamReader.getEventType()
instead ofXMLStreamReader.next()
.- Type Parameters:
T
- compile-time value of thetype
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:
-
close
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 interfaceAutoCloseable
- Overrides:
close
in classStaxStreamIO
- Throws:
XMLStreamException
- if an error occurred while releasing XML reader resources.IOException
- if an error occurred while closing the input stream.Exception
-
run
Invokesclose()
and wraps checked exceptions in aBackingStoreException
. This method is defined for allowing thisStaxStreamReader
to be given toBaseStream.onClose(Runnable)
.- Specified by:
run
in interfaceRunnable
- Throws:
BackingStoreException
-
endOfFile
Returns an error message forEOFException
. This a convenience method for a frequently-used error.- Returns:
- a localized error message for end of file error.
-
canNotParseFile
Returns an error message forBackingStoreException
. This a convenience method fortryAdvance(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
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.
-