Package com.luciad.format.shp

Class TLcdSHPModelDecoder2

java.lang.Object
com.luciad.format.shp.TLcdSHPModelDecoder2
All Implemented Interfaces:
ILcdModelDecoder
@LcdService(service=ILcdModelDecoder.class, priority=20000) public class TLcdSHPModelDecoder2 extends Object implements ILcdModelDecoder
This model decoder decodes ESRI shape files and does lazy loading of elements, based on the client request.
  • This ensures a low memory footprint if only part of the data is needed at the same time:
    • when visualizing a small area
    • when a filter is used
    • when doing processing on the elements one by one
  • It also ensures fast model creation.
  • If you want eager-loading behavior, you can use TLcdSHPModelDecoder. It loads all records up-front, including all geometry and property data. This results in large memory footprint as well as a big decoding hit on startup, but subsequent queries are very fast.

Input files

File Required Entry point Description
*.shp x x Shape file containing the vector data
*.dbf

dBASE table file containing the feature attributes of the shapes
*.cpg

A plain text file which specifies the codepage number and which is used to identify the character encoding of the .shp file. The file can contain a code page number or the name of a char set.
*.shx

Index file containing the offset of each record from the beginning of the main file
*.sbn/*.sbx

Optional spatial index files. If these are not present the decoder will create its own spatial index files.

When the index file (*.shx) or one of the spatial index files (*.sbx or *.sbn) is missing, the decoder will create them at runtime. If possible the spatial index files are stored next to the source data with an *.sbnl and *.sbxl extension. If the files cannot be written next to the source data (e.g. no write permission), they will be written in the temp folder and deleted after disposing the model. If these files need to be created at runtime, there might be a small delay before the elements of this model are returned.

Model reference

The model reference is obtained from an ILcdModelReferenceDecoder. The default reference decoder set on this model decoder is based on all model reference decoders annotated with the LcdService annotation, and can handle If this fails, the decoder's default model reference is returned. Unless set by the user, the default model reference is null.

Supported file transfer protocols

  • This model decoder supports only direct file access.
  • This decoder uses random access files to decode objects lazily. If the source data is not a file (for example an http url), it will be downloaded to your temp folder, and deleted on model dispose or application exit.

Model structure

  • This model decoder creates a model per SHP file.
  • All models returned by this model decoder implement ILcd2DBoundsIndexedModel.

Model descriptor

  • All models returned by this model decoder have a TLcdSHPModelDescriptor.
  • The type name of the model descriptor is SHP.
  • The data model is based on the properties in the .dbf file.

Model elements

The supported shapes are represented by:
SHP TypeDecoded Type
POINT ILcd2DEditablePoint object
POINT_M ILcd2DEditablePoint object implementing ILcdSHPMeasure
POINT_Z ILcd3DEditablePoint object implementing ILcdSHPMeasure
POLYLINE ILcd2DEditablePolyline object, or ILcdShapeList thereof
POLYLINE_M ILcd2DEditablePolyline objects implementing ILcdSHPMeasureList, or ILcdShapeList thereof
POLYLINE_Z ILcd3DEditablePolyline objects implementing ILcdSHPMeasureList, or ILcdShapeList thereof
POLYGON ILcd2DEditablePolygon object, or ILcdComplexPolygon
POLYGON_M ILcd2DEditablePolygon objects implementing ILcdSHPMeasureList, or ILcdShapeList thereof
POLYGON_Z ILcd3DEditablePolygon objects implementing ILcdSHPMeasureList, or ILcdShapeList thereof
MULTI_POINT ILcd2DEditablePolypoint object, or ILcdShapeList thereof
MULTI_POINT_M ILcdPolypoint objects implementing ILcdSHPMeasureList, or ILcdShapeList thereof
MULTI_POINT_Z ILcdPolypoint objects implementing ILcdSHPMeasureList, or ILcdShapeList thereof

Sample code


 ILcdModelDecoder decoder = new TLcdSHPModelDecoder2();
 ILcdModel model = decoder.decode("world.shp");

Thread safety

  • The decoded models are thread-safe for read access when taking a read lock.

Supported versions and specifications

Notes

  • If available, the decoder uses the ".sbn" spatial index file.
  • If not, the decoder creates its own ".sbnl" spatial index file. This happens asynchronously, but any spatial query waits for its completion.

Memory-mapped files

This decoder uses memory-mapped files to lazily load data.

Memory-mapped files are an efficient way to do random access on files. The memory used by memory-mapped files is not part of the JVM heap. The OS can allocate otherwise free system memory for caching pages in the files.

If you don't want this behavior you can use TLcdSHPModelDecoder instead.

Known limitations

  • MultiPointM and MultiPatch elements are not supported
  • As long as the model is not disposed, file locks will be held on the *.shp, *.dbf, *.sbn(l) and *.sbx(l) files. Thus, it's not possible to modify or remove these files until the model has been disposed. This also prevents to export the model to the same location with the TLcdSHPModelEncoder.
Since:
2017.0

  • Constructor Details

    • TLcdSHPModelDecoder2

      public TLcdSHPModelDecoder2()

  • Method Details

    • getDisplayName

      public String getDisplayName()
      Description copied from interface: ILcdModelDecoder
      Returns a short, displayable name for the format that is decoded by this ILcdModelDecoder.
      Specified by:
      getDisplayName in interface ILcdModelDecoder
      Returns:
      the displayable name of this ILcdModelDecoder.

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

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

    • decode

      public ILcdModel decode(String aSourceName) throws IOException
      Description copied from interface: ILcdModelDecoder
      Creates a new model from the given data source.
      Specified by:
      decode in interface ILcdModelDecoder
      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:

    • decodeModelMetadata

      public TLcdModelMetadata decodeModelMetadata(String aSourceName) throws IOException
      Decodes metadata for the specified data source. This method does not create an actual ILcdModel and does not autogenerate any missing support files (such as the .sbnl file), like the decode(String) method does. The resulting TLcdModelMetadata can however contain references to such files, even though they do not (yet) exist.
      Specified by:
      decodeModelMetadata in interface ILcdModelDecoder
      Parameters:
      aSourceName - the data source for which the model metadata will be decoded.
      Returns:
      the model metadata for the data source, never null.
      Throws:
      IOException - if the metadata cannot be decoded for some reason.
      See Also:

    • setDefaultModelReference

      public void setDefaultModelReference(ILcdModelReference aDefaultModelReference)
      Sets the model reference to be used for models when the model reference decoder is set to null.
      Parameters:
      aDefaultModelReference - the model reference to be used for models when the model reference decoder is set to null.
      See Also:

    • getDefaultModelReference

      public ILcdModelReference getDefaultModelReference()
      Returns the model reference to be used for models when the model reference decoder is set to null.
      Returns:
      the model reference to be used for models when the model reference decoder is set to null.
      See Also:

    • getModelReferenceDecoder

      public ILcdModelReferenceDecoder getModelReferenceDecoder()
      Returns the decoder used to produce model references.
      Returns:
      the decoder to produce model references.
      See Also:

    • setModelReferenceDecoder

      public void setModelReferenceDecoder(ILcdModelReferenceDecoder aModelReferenceDecoder)
      Sets the decoder to use to produce model references for models created with this decoder.
      Parameters:
      aModelReferenceDecoder - the decoder to use to produce model references for models created with this decoder.
      See Also:

    • setTrimStringPropertyValues

      public void setTrimStringPropertyValues(boolean aTrimStringPropertyValues)
      Specifies whether or not leading and trailing whitespace should be removed from string properties while decoding DBF files. The default setting is true.
      Parameters:
      aTrimStringPropertyValues - whether or not string values in DBF files should be trimmed

    • isTrimStringPropertyValues

      public boolean isTrimStringPropertyValues()
      Indicates whether or not string values are trimmed when decoding DBF files.
      Returns:
      whether or not string values are trimmed when decoding DBF files
      See Also: