Package org.apache.sis.internal.storage.gpx

Class Reader

java.lang.Object

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

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

org.apache.sis.internal.storage.gpx.Reader

All Implemented Interfaces:

AutoCloseable, Runnable, Spliterator<AbstractFeature>, XMLStreamConstants

final class Reader
extends StaxStreamReader

Reader for GPX 1.0 and 1.1 files. This reader is itself a spliterator over all features found in the XML file. Usage:

Since:

0.8

Version:

1.0

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 Metadata	metadata	The metadata (ISO 19115 compatible), or null if none.
private String	namespace	The namespace, which should be either Tags.NAMESPACE_V10 or Tags.NAMESPACE_V11.
private int	routeId	Identifier of the last "route" feature instance created.
private int	trackId	Identifier of the last "track" feature instance created.
private int	wayPointId	Identifier of the last "way point" feature instance created.

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

reader

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

owner

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

Constructor	Description
Reader(Store owner)	Creates a new GPX reader for the given data store.

Method Summary

Modifier and Type	Method	Description
private Person	author()	Returns the Metadata.author field, creating all necessary objects if needed.
void	forEachRemaining(Consumer<? super AbstractFeature> action)	Performs the given action for each remaining element until all elements have been processed.
Metadata	getMetadata()	Returns the metadata (ISO 19115 compatible), or null if none.
Version	initialize(boolean readMetadata)	Reads the metadata.
private boolean	isEndGPX()	Returns true if the current position of the given reader is the closing </gpx> tag.
private boolean	isGPX()	Returns true if the current element can be considered as in the GPX namespace.
private static boolean	isGPX(String ns)	Returns true if the given namespace is a GPX namespace or is null.
private Link	link()	Returns the first element of the Metadata.links field, creating all necessary objects if needed.
private Metadata	metadata()	Returns the metadata field, creating it if needed.
private boolean	parse(Consumer<? super AbstractFeature> action, boolean all)	Implementation of tryAdvance(Consumer) and forEachRemaining(Consumer).
private AbstractFeature	parseRoute(int index)	Parses a <rte> element.
private AbstractFeature	parseTrack(int index)	Parses a <trk> element.
private AbstractFeature	parseTrackSegment(int index)	Parses a <trkseg> element.
private AbstractFeature	parseWayPoint(int index)	Parses a <wpt>, <rtept> or <trkpt> element.
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.

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

canNotParseFile, characteristics, close, endOfFile, estimateSize, getElementAsDate, getElementAsDouble, getElementAsInteger, getElementAsList, getElementAsTemporal, getElementAsURI, getElementText, getSubReader, moveToRootElement, nestedElement, next, parseBoolean, parseDouble, run, skipUntilEnd, trySplit, unmarshal

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

errors

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

getComparator, getExactSizeIfKnown, hasCharacteristics

Field Details

namespace

private String namespace

The namespace, which should be either Tags.NAMESPACE_V10 or Tags.NAMESPACE_V11. We store this information for identifying the closing <gpx> tag.

metadata

private Metadata metadata

The metadata (ISO 19115 compatible), or null if none.

wayPointId

private int wayPointId

Identifier of the last "way point" feature instance created. We use sequential numbers starting from 1.

routeId

private int routeId

Identifier of the last "route" feature instance created. We use sequential numbers starting from 1.

trackId

private int trackId

Identifier of the last "track" feature instance created. We use sequential numbers starting from 1.

Constructor Details

Reader

Reader(Store owner)
throws Exception

Creates a new GPX reader for the given data store. The initialize(boolean) method must be invoked after this constructor.

Parameters:

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

Throws:

DataStoreException - if the input type is not recognized.

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

isGPX

private static boolean isGPX(String ns)

Returns true if the given namespace is a GPX namespace or is null.

isGPX

private boolean isGPX()

Returns true if the current element can be considered as in the GPX namespace. Strictly speaking we should require the namespace URI to be exactly namespace, but this method is a little bit more lenient.

isEndGPX

private boolean isEndGPX()

Returns true if the current position of the given reader is the closing </gpx> tag. The reader event should be XMLStreamConstants.END_ELEMENT before to invoke this method.

initialize

public Version initialize(boolean readMetadata)
                   throws DataStoreException,
XMLStreamException,
JAXBException,
URISyntaxException,
EOFException

Reads the metadata. This method should be invoked exactly once after construction. This work is performed outside the constructor for allowing StaxStreamReader.close() method invocation no matter if this initialize(boolean) method fails.

Parameters:

readMetadata - if false, skip the reading of metadata elements.

Returns:

the GPX file version, or null if no version information was found.

Throws:

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

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

JAXBException - if an error occurred while parsing GPX 1.1 metadata.

ClassCastException - if an object unmarshalled by JAXB was not of the expected type.

URISyntaxException - if an error occurred while parsing URI in GPX 1.0 metadata.

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

EOFException - if the file seems to be truncated.

metadata

private Metadata metadata()

Returns the metadata field, creating it if needed. This is a convenience method for GPX 1.0 metadata parsing. This is not for returning the metadata result after parsing.

See Also:

• getMetadata()

author

private Person author()

Returns the Metadata.author field, creating all necessary objects if needed. This is a convenience method for GPX 1.0 metadata parsing.

link

private Link link()

Returns the first element of the Metadata.links field, creating all necessary objects if needed. This is a convenience method for GPX 1.0 metadata parsing.

getMetadata

public Metadata getMetadata()

Returns the metadata (ISO 19115 compatible), or null if none. This method can return a non-null value only if initialize(true) has been invoked before this method.

Returns:

the metadata, or null if none.

See Also:

• initialize(boolean)

tryAdvance

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

Specified by:

tryAdvance in class StaxStreamReader

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 GPX file.

Throws:

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

forEachRemaining

public void forEachRemaining(Consumer<? super AbstractFeature> action)
                      throws BackingStoreException

Performs the given action for each remaining element until all elements have been processed.

Parameters:

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

Throws:

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

parse

private boolean parse(Consumer<? super AbstractFeature> action,
 boolean all)
               throws Exception

Implementation of tryAdvance(Consumer) and forEachRemaining(Consumer).

Parameters:

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

all - whether to perform the action on all remaining instances or only the next one.

Returns:

false if this method as detected the end of <gpx> element or the end of document.

Throws:

DataStoreException - if the file contains invalid elements.

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

URISyntaxException - if an error occurred while parsing GPX 1.0 URI.

JAXBException - if an error occurred while parsing GPX 1.1 link.

ClassCastException - if an object unmarshalled by JAXB was not of the expected type.

NumberFormatException - if a text cannot be parsed as an integer or a floating point number.

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

EOFException - if the file seems to be truncated.

Exception

parseWayPoint

private AbstractFeature parseWayPoint(int index)
                               throws Exception

Parses a <wpt>, <rtept> or <trkpt> element. The STAX reader current event must be a XMLStreamConstants.START_ELEMENT. After this method invocation, the reader will be on XMLStreamConstants.END_ELEMENT.

Throws:

Exception - see the list of exceptions documented in parse(Consumer, boolean).

parseRoute

private AbstractFeature parseRoute(int index)
                            throws Exception

Parses a <rte> element. The STAX reader current event must be a XMLStreamConstants.START_ELEMENT and the name of that start element must be Tags.ROUTES.

Throws:

Exception - see the list of exceptions documented in parse(Consumer, boolean).

parseTrackSegment

private AbstractFeature parseTrackSegment(int index)
                                   throws Exception

Parses a <trkseg> element. The STAX reader current event must be a XMLStreamConstants.START_ELEMENT and the name of that start element must be Tags.TRACK_SEGMENTS.

Throws:

Exception - see the list of exceptions documented in parse(Consumer, boolean).

parseTrack

private AbstractFeature parseTrack(int index)
                            throws Exception

Parses a <trk> element. The STAX reader current event must be a XMLStreamConstants.START_ELEMENT and the name of that start element must be Tags.TRACKS.

Throws:

Exception - see the list of exceptions documented in parse(Consumer, boolean).