org.deegree.gml
Class GMLStreamReader

java.lang.Object
  extended by 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


Copyright © 2011. All Rights Reserved.