com.luciad.format.gmlcommon.xml

LuciadLightspeedClass TLcdGMLModelDecoder

java.lang.Object

com.luciad.format.xml.bind.schema.ALcdXMLModelDecoder

com.luciad.format.gmlcommon.xml.TLcdGMLModelDecoder

All Implemented Interfaces:

ILcdInputStreamFactoryCapable, ILcdModelDecoder

@LcdService(service=ILcdModelDecoder.class,
            priority=20001)
public class TLcdGMLModelDecoder
extends ALcdXMLModelDecoder

This model decoder decodes Geography Markup Language (GML) versions 2.x, 3.0.x and 3.1.x., and 3.2. This decoder first analyses the start of the file in order to determine which GML version the file is based on. Next, it delegates the decoding to one of

• TLcdGML2ModelDecoder
• TLcdGML31ModelDecoder
• TLcdGML32ModelDecoder

This decoder may be updated in the future to support additional versions of the GML standard.

Input files

File	Required	Entry point	Description
*.gml, *.gml2, *.gml31, *.gml32, *.xml	x	x	GML data file
*.xsd	x		Application schema (XML Schema)

Supported file transfer protocols

• This model decoder supports all transfer protocols that are supported by the ILcdInputStreamFactory of this decoder.

Model structure

• This model decoder creates a model per GML file.
• A model represents a GML feature collection. A feature collection is any GML feature with a property element derived from AbstractFeatureMemberType. Elements of the deprecated AbstractFeatureCollectionType types also supported.
• All models returned by this model decoder implement ILcd2DBoundsIndexedModel.
• Hierarchic feature collections are decoded as a hierarchical ILcdModelTreeNode structure. For example, the following document:

  
        <my:featureCollectionA>
          <my:featureCollectionB>
          <my:featureA>
            ...
          </my:featureA>
          </my:featureCollectionB>
          <my:featureCollectionC>
          <my:featureB>
            ...
          </my:featureB>
          </my:featureCollectionC>
          <my:featureC>
            ...
          </my:featureC>
        </my:featureCollectionA>
       

  will be decoded as the followed model/element structure:

         ILcdModelTreeNode (myFeatureCollectionA)
          +- ILcdModelTreeNode (myFeatureCollectionB)
          |   +- ILcdShape (myFeatureA)
          +- ILcdModelTreeNode (myFeatureCollectionC)
          |   +- ILcdShape (myFeatureB)
          +- ILcdShape (myFeatureC)
       

Model descriptor

• All models returned by this model decoder have a TLcdGMLModelDescriptor.
• The type name of the model descriptor is the display name of the chosen version specific decoder (see above).

Model reference

• This model decoder supports all model references which can be parsed by the TLcdOGCModelReferenceParser.
• This model decoder retrieves its model references from the srsName attribute specified within the GML files. The first coordinate reference system (CRS) that is encountered is used as the model reference. Geographic data defined in other CRS'es are transformed during decoding to this model reference CRS.

Model elements

All domain objects used within this library implement ILcdDataObject. Refer to the javadoc of the version specific GML decoders for more information.

Useful settings

• an EntityResolver2 can be configured on this model decoder, to control how to resolve external entities (such as XSD schemas). By default, an entity resolver is configured which resolves references to all OGC schemas supported by LuciadLightspeed.

Sample code

 ILcdModelDecoder decoder = new TLcdGMLModelDecoder();
 ILcdModel model = decoder.decode("world.gml32");
 

Performance tips

GML is a verbose format, both on disk and in memory, and cannot be lazily accessed. It is perfectly suited for data exchange, but less so for opening and visualizing large datasets. Consider using a geospatial database if you want to store and access large vector datasets.

Thread safety

• The decoding of models is thread-safe, as long as no properties are changed during the decoding.
• The decoded models are thread-safe for read access.

Supported versions and specifications

• GML 2.x
• GML 3.0.x, 3.1.x
• GML 3.2.1

Since:

9.0

Constructor Summary

Constructors

Constructor and Description
TLcdGMLModelDecoder() Constructs a new TLcdGMLModelDecoder.
TLcdGMLModelDecoder(TLcdDataModel aDataModel) Creates a new TLcdGMLModelDecoder configured for the given data model.

Method Summary

Modifier and Type	Method and Description
boolean	canDecodeSource(String aSourceName) Checks whether this model decoder can decode the specified data source.
ILcdModel	decode(Source aSource) Creates a new model from the given data source.
ILcdModel	decode(String aSourceName) Creates a new model from the given data source.
String	getDefaultSrsName() Get the default srsName for this instance.
String	getDisplayName() Returns a short, displayable name for the format that is decoded by this ILcdModelDecoder.
EntityResolver2	getEntityResolver() Returns the org.xml.sax.ext.EntityResolver2 that is used for creating input sources for XSD schemas.
ILcdInputStreamFactory	getInputStreamFactory() Returns the ILcdInputStreamFactory that is used for creating input streams.
ILcdModelReferenceParser	getModelReferenceParser() Returns the model reference parser that is used to create ILcdModelReference instances when decoding an srsName.
XMLInputFactory	getXMLInputFactory() Returns the javax.xml.stream.XMLInputFactory that is used by this decoder for creating javax.xml.stream.XMLStreamReader instances.
boolean	isLinearElementsUseGeodesicInterpolationForGeodeticSrs() Returns true if a geodesic interpolation needs to be used for linear GML elements in case of a geodetic reference.
boolean	isUseApplicationSchemaCache() Returns if application schemas are cached.
void	setDefaultSrsName(String aDefaultSrsName) Set the default srsName that will be used to determine the model reference if neither the first feature, its possible envelope or the possible envelope of the feature collection has a srsName attribute set.
void	setEntityResolver(EntityResolver2 aEntityResolver) Sets the org.xml.sax.ext.EntityResolver2 to be used for creating input sources for XSD schemas.
void	setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory) Sets the ILcdInputStreamFactory to be used for creating input streams.
void	setLinearElementsUseGeodesicInterpolationForGeodeticSrs(boolean aUseGeodesicInterpolationForGeodeticSrs) Sets whether a geodesic interpolation needs to be used for linear GML elements in case of a geodetic reference.
void	setModelReferenceParser(ILcdModelReferenceParser aModelReferenceParser) Sets the parser that is used to create ILcdModelReference instances given an srsName.
void	setUseApplicationSchemaCache(boolean aUseCache) Enables or disables application schema caching depending on the parameter value.
void	setXMLInputFactory(XMLInputFactory aXMLInputFactory) Sets the javax.xml.stream.XMLInputFactory to be used by this decoder for creating javax.xml.stream.XMLStreamReader instances.
String	toString()

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.luciad.model.ILcdModelDecoder

canDecodeSource, decodeModelMetadata, decodeModelMetadata, decodeSource, discoverDataSources

Constructor Detail

TLcdGMLModelDecoder

public TLcdGMLModelDecoder()

Constructs a new TLcdGMLModelDecoder.

TLcdGMLModelDecoder

public TLcdGMLModelDecoder(TLcdDataModel aDataModel)

Creates a new TLcdGMLModelDecoder configured for the given data model.

Parameters:

aDataModel - the data model for which the decoder is to be configured

Throws:

IllegalArgumentException - if the data model does not depend on either the GML 2, GML 31 or GML32 data model

Method Detail

canDecodeSource

public boolean canDecodeSource(String aSourceName)

Description copied from interface: ILcdModelDecoder

Checks whether this model decoder can decode the specified data source. It is acceptable for this method to return true for a source name while decode throws an exception for that same source name.

For performance reasons, we strongly recommend that this will only be a simple test. For example: check the file extension of a file, but not that the file exists or contains expected content.

Parameters:

aSourceName - the data source to be verified; typically a file name or a URL.

Returns:

true if this decoder can likely decode the data specified by the source name, false otherwise.

See Also:

ILcdModelDecoder.decode(String), ILcdModelDecoder.decodeModelMetadata(String)

decode

public ILcdModel decode(String aSourceName)
                 throws IOException

Description copied from interface: ILcdModelDecoder

Creates a new model from the given data source.

Parameters:

aSourceName - the data source to be decoded; typically a file name or a URL.

Returns:

A model containing the decoded data. While null is allowed, implementors are advised to throw an error instead.

Throws:

IOException - for any exceptions caused by IO problems or invalid data. Since decoding invalid data almost always results in RunTimeExceptions (NullPointerException, IndexOutOfBoundsException, IllegalArgumentException, ...) on unexpected places, implementations are advised to catch RuntimeExceptions in their decode() method, and wrap them into an IOException, as illustrated in the code snippet below.

   public ILcdModel decode( String aSourceName ) throws IOException {
      try (InputStream input = fInputStreamFactory.createInputStream(aSourceName)) {
         // Perform decoding ...
      } catch (RuntimeException e) {
         throw new IOException(e);
      }
   }
 

InterruptedIOException - When the thread on which this method is called is interrupted: it is recommended to stop the decoding and throw an InterruptedIOException. This same exception can also be used if the decoder shows UI to the user, and the user cancels the decoding through the UI.

See Also:

ILcdModelDecoder.canDecodeSource(String)

getDisplayName

public String getDisplayName()

Description copied from interface: ILcdModelDecoder

Returns a short, displayable name for the format that is decoded by this ILcdModelDecoder.

Returns:

the displayable name of this ILcdModelDecoder.

getEntityResolver

public EntityResolver2 getEntityResolver()

Description copied from class: ALcdXMLModelDecoder

Returns the org.xml.sax.ext.EntityResolver2 that is used for creating input sources for XSD schemas. This entity resolver will only be used to resolve extension schemas that are not already configured on this decoder.

Specified by:

getEntityResolver in class ALcdXMLModelDecoder

Returns:

the entity resolver to be used for creating input sources for XSD schemas.

getInputStreamFactory

public ILcdInputStreamFactory getInputStreamFactory()

Description copied from class: ALcdXMLModelDecoder

Returns the ILcdInputStreamFactory that is used for creating input streams.

Specified by:

getInputStreamFactory in interface ILcdInputStreamFactoryCapable

Specified by:

getInputStreamFactory in class ALcdXMLModelDecoder

Returns:

the ILcdInputStreamFactory that is used for creating input streams.

See Also:

ALcdXMLModelDecoder.setInputStreamFactory(com.luciad.io.ILcdInputStreamFactory)

getXMLInputFactory

public XMLInputFactory getXMLInputFactory()

Description copied from class: ALcdXMLModelDecoder

Returns the javax.xml.stream.XMLInputFactory that is used by this decoder for creating javax.xml.stream.XMLStreamReader instances.

Specified by:

getXMLInputFactory in class ALcdXMLModelDecoder

Returns:

the javax.xml.stream.XMLInputFactory that is used by this decoder for creating javax.xml.stream.XMLStreamReader instances.

isUseApplicationSchemaCache

public boolean isUseApplicationSchemaCache()

Description copied from class: ALcdXMLModelDecoder

Returns if application schemas are cached. When application schemas are cached, the decoder caches all applications schemas it encounters. When a certain schema is referenced during decoding, only if the schema is not found in the cache, it will be resolved. The default is not to cache.

Note that in case multiple application schemas use the same namespace URI, it is not possible to turn on application schema caching because the decoder will not be able to discern between the different schemas.

Specified by:

isUseApplicationSchemaCache in class ALcdXMLModelDecoder

Returns:

if application schemas are cached

setEntityResolver

public void setEntityResolver(EntityResolver2 aEntityResolver)

Description copied from class: ALcdXMLModelDecoder

Sets the org.xml.sax.ext.EntityResolver2 to be used for creating input sources for XSD schemas.

When the entity resolver is unable to find a schema (i.e. the resolveEntity method returns null), the ALcdXMLModelDecoder.getInputStreamFactory() is used to create an appropriate input stream for the given system id of the schema.

Specified by:

setEntityResolver in class ALcdXMLModelDecoder

Parameters:

aEntityResolver - the entity resolver to be used for creating input sources for XSD schemas.

setInputStreamFactory

public void setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)

Description copied from class: ALcdXMLModelDecoder

Sets the ILcdInputStreamFactory to be used for creating input streams. If the configured entity resolver implements ILcdInputStreamFactoryCapable, it is also configured with this factory.

Specified by:

setInputStreamFactory in interface ILcdInputStreamFactoryCapable

Specified by:

setInputStreamFactory in class ALcdXMLModelDecoder

Parameters:

aInputStreamFactory - the input stream factory to be used by this model decoder.

See Also:

ALcdXMLModelDecoder.getInputStreamFactory()

setUseApplicationSchemaCache

public void setUseApplicationSchemaCache(boolean aUseCache)

Description copied from class: ALcdXMLModelDecoder

Enables or disables application schema caching depending on the parameter value.

Specified by:

setUseApplicationSchemaCache in class ALcdXMLModelDecoder

Parameters:

aUseCache - if true, application schema caching is turned on. If false, caching is turned off.

setXMLInputFactory

public void setXMLInputFactory(XMLInputFactory aXMLInputFactory)

Sets the javax.xml.stream.XMLInputFactory to be used by this decoder for creating javax.xml.stream.XMLStreamReader instances. If the configured entity resolver implements ILcdInputStreamFactoryCapable, it is also configured with this factory.

Specified by:

setXMLInputFactory in class ALcdXMLModelDecoder

Parameters:

aXMLInputFactory - the javax.xml.stream.XMLInputFactory to be used by this decoder

toString

public String toString()

Overrides:

toString in class Object

getModelReferenceParser

public ILcdModelReferenceParser getModelReferenceParser()

Returns the model reference parser that is used to create ILcdModelReference instances when decoding an srsName.

Returns:

the model reference parser of this decoder

setModelReferenceParser

public void setModelReferenceParser(ILcdModelReferenceParser aModelReferenceParser)

Sets the parser that is used to create ILcdModelReference instances given an srsName.

Parameters:

aModelReferenceParser - the model reference parser for this decoder

setDefaultSrsName

public void setDefaultSrsName(String aDefaultSrsName)

Set the default srsName that will be used to determine the model reference if neither the first feature, its possible envelope or the possible envelope of the feature collection has a srsName attribute set. Further elements with no srsName will be assumed to be in the same reference as the model.

By default, the model decoder uses CRS84.

Parameters:

aDefaultSrsName - the default srsName

Throws:

IllegalArgumentException - if the srsName can not be parsed.

Since:

2018.0

getDefaultSrsName

public String getDefaultSrsName()

Get the default srsName for this instance.

Returns:

the default srsName.

Since:

2018.0

See Also:

setDefaultSrsName(String)

decode

public ILcdModel decode(Source aSource)
                 throws IOException

Creates a new model from the given data source.

This implementation only supports StreamSource sources. In case other types of sources are required, the version-specific GML decoders should be used directly.

Overrides:

decode in class ALcdXMLModelDecoder

Parameters:

aSource - the source to read the model from

Throws:

UnsupportedOperationException - in case the decoder is not able to decode from the source

IOException

See Also:

decode(String)

setLinearElementsUseGeodesicInterpolationForGeodeticSrs

public void setLinearElementsUseGeodesicInterpolationForGeodeticSrs(boolean aUseGeodesicInterpolationForGeodeticSrs)

Sets whether a geodesic interpolation needs to be used for linear GML elements in case of a geodetic reference. This applies to the following linear GML elements: LinearRing, LineString and LineStringSegment.

Although these GML elements conceptually represent geometries with a linear interpolation, they are often used to represent geometries with lon/lat coordinates and a geodesic interpolation.. Setting this flag to true enables this use case by determining the interpolation based on the coordinate reference.

Parameters:

aUseGeodesicInterpolationForGeodeticSrs - whether a geodesic interpolation needs to be used in case of a geodetic reference

Since:

2019.0

See Also:

isLinearElementsUseGeodesicInterpolationForGeodeticSrs()

isLinearElementsUseGeodesicInterpolationForGeodeticSrs

public boolean isLinearElementsUseGeodesicInterpolationForGeodeticSrs()

Returns true if a geodesic interpolation needs to be used for linear GML elements in case of a geodetic reference. By default, true is returned.

Returns:

true if a geodesic interpolation needs to be used for linear GML elements in case of a geodetic reference.

Since:

2019.0

See Also:

setLinearElementsUseGeodesicInterpolationForGeodeticSrs(boolean)