org.deegree.gml
Class GMLStreamReader

java.lang.Object
  org.deegree.gml.GMLStreamReader

public class GMLStreamReader
extends Object

Stream-based reader for GML instance documents or GML document fragments. Currently supports GML 2/3.0/3.1/3.2.

Initialization

A GMLStreamReader always works on top of a XMLStreamReader instance. Use the methods provided in GMLInputFactory to create a GMLStreamReader instance.

 ...
   GMLStreamReader gmlReader = GMLInputFactory.createGMLStreamReader( GMLVersion.GML_2, new URL ("...") );
 ...
 

General usage

After initialization, read() is used to consume the next GML object element (geometry, feature, feature collection, etc.) from the stream and turn it into an object representation.

 ...
   GMLObject object = gmlReader.read();
 ...
 

It's vital that the underlying XMLStreamReader points to the START_ELEMENT event of the GML element to be read. After calling, the underlying XMLStreamReader will be positioned on the event after the corresponding END_ELEMENT event. Depending on the actual element, a corresponding GMLObject instance will be created (Geometry, FeatureCollection, Feature, etc.). In order to work with the object, it has to be cast to the concrete type. Alternatively (if one knows the type of element to be read beforehand), use on of the specific read methods to avoid the cast:

 ...
   Feature feature = gmlReader.readFeature();
 ...
 

Reading GML features/feature collections

TODO

Specifying the application schema

TODO

Streaming vs. non-streaming

TODO

Reading other GML objects

TODO

Advanced options

...

Notes

Instances of this class are not thread-safe.

Version:

$Revision: 31641 $, $Date: 2011-08-24 21:24:55 +0200 (Wed, 24 Aug 2011) $

Author:

Markus Schneider, last edited by: $Author: mschneider $

See Also:

GMLObject, GMLInputFactory

Method Summary

void	close() Closes the underlying XML stream.
GMLDictionaryReader	getDictionaryReader() Returns a configured GMLDictionaryReader instance for calling specific dictionary parsing methods.
GMLFeatureReader	getFeatureReader() Returns a configured GMLFeatureReader instance for calling specific feature parsing methods.
GMLGeometryReader	getGeometryReader() Returns a configured GMLGeometryReader instance for calling specific geometry parsing methods.
GMLDocumentIdContext	getIdContext() Returns the GMLDocumentIdContext that keeps track of objects, identifiers and references.
XMLStreamReader	getXMLReader() Returns the underlying XMLStreamReader.
boolean	isGeometryElement()
boolean	isGeometryOrEnvelopeElement()
GMLObject	read() Returns the deegree model representation for the GML object element event that the cursor of the underlying xml stream points to.
CRS	readCRS() Returns the deegree model representation for the GML crs element event that the cursor of the underlying xml stream points to.
Dictionary	readDictionary() Returns the deegree model representation for the GML dictionary element event that the cursor of the underlying xml stream points to.
Feature	readFeature() Returns the deegree model representation for the GML feature element event that the cursor of the underlying xml stream points to.
FeatureCollection	readFeatureCollection() Returns the deegree model representation for the GML feature collection element event that the cursor of the underlying xml stream points to.
StreamFeatureCollection	readFeatureCollectionStream() Returns a StreamFeatureCollection that allows stream-based access to the members of the feature collection that the cursor of the given XMLStreamReader points at.
Geometry	readGeometry() Returns the deegree model representation for the GML geometry element event that the cursor of the underlying xml stream points to.
Geometry	readGeometryOrEnvelope() Returns the deegree model representation for the GML geometry element event that the cursor of the underlying xml stream points to.
void	setApplicationSchema(AppSchema schema) Controls the application schema that is assumed when features or feature collections are parsed.
void	setDefaultCRS(ICRS defaultCRS) Controls the default CRS that is assumed when GML objects (especially geometries) without SRS information are parsed.
void	setGeometryFactory(GeometryFactory geomFac) Controls the GeometryFactory instance to be used for creating geometries.
void	setResolver(GMLReferenceResolver resolver) Sets the GMLReferenceResolver that the generated GMLReferences will use for resolving themselves.

Methods inherited from class java.lang.Object

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

Method Detail

setApplicationSchema

public void setApplicationSchema(AppSchema schema)

Controls the application schema that is assumed when features or feature collections are parsed.

Parameters:

schema - application schema, can be null (use xsi:schemaLocation attribute to build the application schema)

setDefaultCRS

public void setDefaultCRS(ICRS defaultCRS)

Controls the default CRS that is assumed when GML objects (especially geometries) without SRS information are parsed.

Parameters:

defaultCRS - default CRS, can be null

setGeometryFactory

public void setGeometryFactory(GeometryFactory geomFac)

Controls the GeometryFactory instance to be used for creating geometries.

Parameters:

geomFac - geometry factory, can be null (use a default factory)

isGeometryElement

public boolean isGeometryElement()

Returns:

true if the stream's event is an XMLStreamConstants.START_ELEMENT && the current element's name is a known geometry (with respect to it's gml version).

isGeometryOrEnvelopeElement

public boolean isGeometryOrEnvelopeElement()

Returns:

true if the stream's event is an XMLStreamConstants.START_ELEMENT && the current element's name is a known geometry (with respect to it's gml version).

setResolver

public void setResolver(GMLReferenceResolver resolver)

Sets the GMLReferenceResolver that the generated GMLReferences will use for resolving themselves.

Parameters:

resolver -

read

public GMLObject read()
               throws XMLStreamException,
                      XMLParsingException,
                      UnknownCRSException

Returns the deegree model representation for the GML object element event that the cursor of the underlying xml stream points to.

Returns:

deegree model representation for the current GML object element, never null

Throws:

XMLStreamException

UnknownCRSException

XMLParsingException

readFeature

public Feature readFeature()
                    throws XMLStreamException,
                           XMLParsingException,
                           UnknownCRSException

Returns the deegree model representation for the GML feature element event that the cursor of the underlying xml stream points to.

Returns:

deegree model representation for the current GML feature element, never null

Throws:

XMLStreamException

XMLParsingException

UnknownCRSException

readFeatureCollection

public FeatureCollection readFeatureCollection()
                                        throws XMLStreamException,
                                               XMLParsingException,
                                               UnknownCRSException

Returns the deegree model representation for the GML feature collection element event that the cursor of the underlying xml stream points to.

Please note that readFeatureCollectionStream() should be preferred (especially for large feature collections), because it does not build and store all features in memory at once.

Returns:

deegree model representation for the current GML feature collection element, never null

Throws:

XMLStreamException

XMLParsingException

UnknownCRSException

readFeatureCollectionStream

public StreamFeatureCollection readFeatureCollectionStream()
                                                    throws XMLStreamException,
                                                           XMLParsingException,
                                                           UnknownCRSException

Returns a StreamFeatureCollection that allows stream-based access to the members of the feature collection that the cursor of the given XMLStreamReader points at.

This method does not automatically consume all events from the underlying XML stream. Instead, it allows the caller to control the consumption by iterating over the features in the returned collection.

Returns:

deegree model representation for the current GML feature collection element, never null

Throws:

XMLStreamException

XMLParsingException

UnknownCRSException

readGeometryOrEnvelope

public Geometry readGeometryOrEnvelope()
                                throws XMLStreamException,
                                       XMLParsingException,
                                       UnknownCRSException

Returns the deegree model representation for the GML geometry element event that the cursor of the underlying xml stream points to.

Returns:

deegree model representation for the current GML geometry element, never null

Throws:

XMLStreamException

XMLParsingException

UnknownCRSException

readGeometry

public Geometry readGeometry()
                      throws XMLStreamException,
                             XMLParsingException,
                             UnknownCRSException

Returns the deegree model representation for the GML geometry element event that the cursor of the underlying xml stream points to.

Returns:

deegree model representation for the current GML geometry element, never null

Throws:

XMLStreamException

XMLParsingException

UnknownCRSException

readDictionary

public Dictionary readDictionary()
                          throws XMLStreamException

Returns the deegree model representation for the GML dictionary element event that the cursor of the underlying xml stream points to.

Returns:

deegree model representation for the current GML dictionary element, never null

Throws:

XMLStreamException

readCRS

public CRS readCRS()
            throws XMLStreamException

Returns the deegree model representation for the GML crs element event that the cursor of the underlying xml stream points to.

Returns:

deegree model representation for the current GML crs element, never null

Throws:

XMLStreamException

getIdContext

public GMLDocumentIdContext getIdContext()

Returns the GMLDocumentIdContext that keeps track of objects, identifiers and references.

Returns:

the GMLDocumentIdContext, never null

getXMLReader

public XMLStreamReader getXMLReader()

Returns the underlying XMLStreamReader.

Returns:

the underlying XMLStreamReader, never null

close

public void close()
           throws XMLStreamException

Closes the underlying XML stream.

Throws:

XMLStreamException

getFeatureReader

public GMLFeatureReader getFeatureReader()

Returns a configured GMLFeatureReader instance for calling specific feature parsing methods.

Returns:

a configured GMLFeatureReader instance, never null

getGeometryReader

public GMLGeometryReader getGeometryReader()

Returns a configured GMLGeometryReader instance for calling specific geometry parsing methods.

Returns:

a configured GMLGeometryReader instance, never null

getDictionaryReader

public GMLDictionaryReader getDictionaryReader()

Returns a configured GMLDictionaryReader instance for calling specific dictionary parsing methods.

Returns:

a configured GMLDictionaryReader instance, never null