Package com.luciad.format.gml31.xml

Class TLcdGML31ModelDecoder

java.lang.Object
com.luciad.format.xml.bind.schema.ALcdXMLModelDecoder
com.luciad.format.gml31.xml.TLcdGML31ModelDecoder
All Implemented Interfaces:
ILcdInputStreamFactoryCapable, ILcdModelDecoder
public class TLcdGML31ModelDecoder extends ALcdXMLModelDecoder
This model decoder decodes Geography Markup Language (GML) version 3.0.x and 3.1.x.

Input files

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

Supported file transfer protocols

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

Model structure

  • This model decoder creates a model per GML file.
  • A model represents a GML feature collection, i.e. an element of type AbstractFeatureCollectionType.
  • 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 TLcdGML31ModelDescriptor.
  • The type name of the model descriptor is the display name of this decoder.

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. The ILcdDataObject structure of each domain object is defined by the rules described in the default XML Schema - ILcdDataObject Mapping specification.

In addition, the following mapping applies:

AbstractCurveSegmentType com.luciad.shape.ILcdShape
com.luciad.shape.ILcdCurve
AbstractCurveType com.luciad.shape.ILcdCurve
AbstractFeatureCollectionType com.luciad.model.ILcd2DBoundsIndexedModel
com.luciad.model.ILcdIntegerIndexedModel
AbstractFeatureType com.luciad.shape.ILcdShapeList
AbstractGeometricAggregateType com.luciad.shape.ILcdEditableShapeList
AbstractGeometryType com.luciad.shape.ILcdShape
AbstractRingType com.luciad.shape.ILcdRing
AbstractSurfacePatchType com.luciad.shape.ILcdShape
ArcByBulgeType com.luciad.shape.shape2D.ILcd2DEditableCircularArcByBulge
ArcByCenterPointType com.luciad.shape.shape2D.ILcd2DEditableCircularArcByCenterPoint
ArcStringByBulgeType com.luciad.shape.ILcdCompositeCurve
ArcStringType com.luciad.shape.ILcdCompositeCurve
ArcType com.luciad.shape.shape2D.ILcd2DEditableCircularArcBy3Points
CircleByCenterPointType com.luciad.shape.ILcdRing
com.luciad.shape.shape2D.ILcd2DEditableCircle
CircleType com.luciad.shape.shape2D.ILcd2DEditableCircleBy3Points
CompositeCurveType com.luciad.shape.ILcdEditableCompositeCurve
CoordinatesType com.luciad.shape.shape3D.ILcd3DEditablePointList
CurveType com.luciad.shape.ILcdEditableCompositeCurve
DirectPositionListType com.luciad.shape.shape3D.ILcd3DEditablePointList
DirectPositionType com.luciad.shape.shape3D.ILcd3DEditablePoint
EnvelopeType com.luciad.shape.shape3D.ILcd3DEditableBounds
GeodesicStringType com.luciad.shape.shape3D.ILcd3DEditablePolyline
LineStringSegmentType com.luciad.shape.shape3D.ILcd3DEditablePolyline
LineStringType com.luciad.shape.shape3D.ILcd3DEditablePolyline
com.luciad.shape.ILcdCurve
LinearRingType com.luciad.shape.shape3D.ILcd3DEditablePolygon
com.luciad.shape.ILcdRing
MeasureType com.luciad.util.iso19103.ILcdISO19103Measure
PointType com.luciad.shape.shape3D.ILcd3DEditablePoint
PolygonPatchType com.luciad.shape.ILcdEditableSurface
PolygonType com.luciad.shape.ILcdEditableSurface
RectangleType com.luciad.shape.shape3D.ILcd3DEditableBounds
RingType com.luciad.shape.ILcdEditableCompositeCurve
com.luciad.shape.ILcdRing
SurfaceType com.luciad.shape.ILcdEditableShapeList
TriangleType com.luciad.shape.shape3D.ILcd3DEditablePolygon

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 that are supported by LuciadLightspeed.

Alternative decoding methods

This decoder can also be used to directly decode a file containing a single feature or a single geometry.

Sample code


 ILcdModelDecoder decoder = new TLcdGML31ModelDecoder();
 ILcdModel model = decoder.decode("world.gml31");

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 3.0.x, 3.1.x

Since:
9.0

  • Constructor Details

    • TLcdGML31ModelDecoder

      public TLcdGML31ModelDecoder()
      Creates a new TLcdGML31ModelDecoder, ready to use.

    • TLcdGML31ModelDecoder

      public TLcdGML31ModelDecoder(TLcdDataModel aDataModel)
      Creates a new TLcdGML31ModelDecoder 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 the GML 31 data model

  • Method Details

    • canDecodeSource

      public boolean canDecodeSource(String aString)
      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.

      Specified by:
      canDecodeSource in interface ILcdModelDecoder
      Parameters:
      aString - 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:

    • 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);
      }
   }
      See Also:

    • 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:

    • 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:

    • 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)
      Description copied from class: ALcdXMLModelDecoder
      Sets the javax.xml.stream.XMLInputFactory to be used by this decoder for creating javax.xml.stream.XMLStreamReader instances.
      Specified by:
      setXMLInputFactory in class ALcdXMLModelDecoder
      Parameters:
      aXMLInputFactory - the javax.xml.stream.XMLInputFactory to be used by this decoder for creating javax.xml.stream.XMLStreamReader instances.

    • 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:

    • decode

      public ILcdModel decode(Source aSource) throws IOException

      Creates a new model from the given data source.

      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:

    • decodeFeature

      public TLcdGML31AbstractFeature decodeFeature(String aSource) throws IOException
      Decodes a data source representing a GML 3.1 Feature into a TLcdGML31AbstractFeature.

      Note that this method does not return an ILcdModel. The feature returned by this method should be wrapped in a model explicitly.

      Parameters:
      aSource - a data source containing a GML 3.1 Feature
      Returns:
      a TLcdGML31AbstractFeature representing the decoded GML Feature
      Throws:
      IOException - if the data source is not recognized as an GML 3.1 Feature

    • decodeShape

      public ILcdShape decodeShape(String aSource) throws IOException
      Decodes a GML 3.1 geometry into an ILcdShape.
      Parameters:
      aSource - a data source containing a shape-compatible GML 3.1 geometry object, that is, a source that maps onto a class in com.luciad.format.gml31.model that implements ILcdShape.
      Returns:
      a ILcdShape representing the decoded GML geometry
      Throws:
      IOException - if the data source is not recognized as an GML 3.1 Feature

    • 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.
      Parameters:
      aUseGeodesicInterpolationForGeodeticSrs - whether a geodesic interpolation needs to be used in case of a geodetic reference

    • isLinearElementsUseGeodesicInterpolationForGeodeticSrs

      public boolean isLinearElementsUseGeodesicInterpolationForGeodeticSrs()
      Returns true if a geodesic interpolation needs to be used for linear GML elements in case of a geodetic reference.
      Returns:
      true if a geodesic interpolation needs to be used for linear GML elements in case of a geodetic reference.