Package com.luciad.format.shp

Class TLcdSHPModelDecoder

java.lang.Object
com.luciad.format.shp.TLcdSHPModelDecoder
All Implemented Interfaces:
ILcdInputStreamFactoryCapable, ILcdModelDecoder, ILcdCharsetSettable
@LcdService(service=ILcdModelDecoder.class, priority=50000) public class TLcdSHPModelDecoder extends Object implements ILcdModelDecoder, ILcdCharsetSettable, ILcdInputStreamFactoryCapable
This model decoder decodes ESRI shape files.

Important note

This decoder does eager loading of all the geometry and property data up-front. This results in large memory footprint as well as a big decoding hit on startup, but subsequent queries are very fast.

It is recommended to use TLcdSHPModelDecoder2 instead: it does lazy loading depending on the client request. For example, it will only load data within a requested area based on a spatial index.

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
*.shx

Index file containing the offset of each record from the beginning of the main file

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 all transfer protocols that are supported by the input stream factory of this decoder.

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.

Model elements

The supported shapes are represented by:
SHP TypeDecoded Type
POINT TLcd2DEditableFeaturedPoint
POLYLINE TLcdFeaturedShapeList with shape array of ILcd2DEditablePolyline objects
POLYGON TLcdFeaturedShapeList with shape array of a single TLcdComplexPolygon containing a set of ILcd2DEditablePolygon objects
MULTI_POINT TLcdFeaturedShapeList with shape array of ILcd2DEditablePolypoint objects
POINT_Z TLcd2DEditableFeaturedPoint with a TLcdSHPPointZ
POLYLINE_Z TLcdFeaturedShapeList with shape array of TLcdSHPPolylineZ objects
POLYGON_Z TLcdFeaturedShapeList with shape array of a single TLcdComplexPolygon containing a set of TLcdSHPPolygonZ objects
MULTI_POINT_Z TLcdFeaturedShapeList with shape array of TLcdSHPMultiPointZ objects
POINT_M TLcd2DEditableFeaturedPoint with a TLcdSHPPointM
POLYLINE_M TLcdFeaturedShapeList with shape array of TLcdSHPPolylineZ objects
POLYGON_M TLcdFeaturedShapeList with shape array of a single TLcdComplexPolygon containing a set of TLcdSHPPolygonZ objects
MULTI_POINT_Z TLcdFeaturedShapeList with shape array of TLcdSHPMultiPointZ objects

Useful settings

  • The lazyFeaturing property specifies whether the features are read at the time of decoding or only when their feature is actually needed. When they are read, they are kept in memory. This gives a performance increase for reading SHP files but may give some performance loss if many features have to be read later (labeling for example). By default this property is set to true.
  • By using the lazyFeaturingOffForHTTP the lazy feature mechanism can still be switched off if the file is to be retrieved over an http connection. By default, this property is set to true.

Sample code


 ILcdModelDecoder decoder = new TLcdSHPModelDecoder();
 ILcdModel model = decoder.decode( "vector.shp" );

Thread safety

  • The decoding of models is not thread-safe.
  • The decoded models are thread-safe for read access.

Supported versions and specifications

Known limitations

  • MultiPointM and MultiPatch elements are not supported

  • Constructor Details

    • TLcdSHPModelDecoder

      public TLcdSHPModelDecoder()
      Constructs a new SHP model decoder.

    • TLcdSHPModelDecoder

      public TLcdSHPModelDecoder(String aDataModelName)
      Constructs a new SHP model decoder with a fixed TLcdDataModel. All files that are decoded with this decoder will use exactly the same data model. This data model will have the given name. It is the responsibility of the caller of this method to ensure that all files that are decoded have exactly the same structure; this means that the shape type is the same and that all files contain the same feature structure. The result of decoding files with different structures with a fixed data model is unspecified.

  • Method Details

    • setClassTraceOn

      public static void setClassTraceOn(boolean aClassTraceOn)
      Deprecated.
      This method has been deprecated. It is recommended to use the standard Java logging framework directly.
      Enables tracing for all instances of this class. If the argument is true then all log messages are recorded, otherwise only the informative, warning and error messages are recorded.
      Parameters:
      aClassTraceOn - if true then all log messages are recorded, otherwise only the informative, warning and error messages are recorded.

    • setTraceOn

      public void setTraceOn(boolean aTraceOn)
      Deprecated.
      This method has been deprecated. It is recommended to use the standard Java logging framework directly.
      Enables tracing for this class instance. Calling this method with either true or false as argument automatically turns off tracing for all other class instances for which setTraceOn has not been called. If the argument is false then only the informative, warning and error log messages are recorded.
      Parameters:
      aTraceOn - if true then all log messages are recorded for this instance. If false, then only the informative, warning and error log messages are recorded.

    • isTraceOn

      public boolean isTraceOn()
      Deprecated.
      This method has been deprecated. It is recommended to use the standard Java logging framework directly.
      Returns true if tracing is enabled for this class.
      Returns:
      true if tracing is enabled for this class, false otherwise.

    • setCharacterSet

      public void setCharacterSet(String aCharacterSet)
      Sets the character set to use to decode DBF files. Default value is "windows-1252".
      Specified by:
      setCharacterSet in interface ILcdCharsetSettable
      Parameters:
      aCharacterSet - the character set to use to decode DBF files. The supported character sets depend on the JVM implementation and can be found at String(byte[], String).

    • getCharacterSet

      public String getCharacterSet()
      Description copied from interface: ILcdCharsetSettable
      Returns the name of the current Charset.
      Specified by:
      getCharacterSet in interface ILcdCharsetSettable
      Returns:
      the name of the Charset.

    • setParseFloatAsDouble

      public void setParseFloatAsDouble(boolean aFloatAsDouble)
      Specifies whether or not floating point values are parsed as a Float or a Double. The default setting is false, parsing as Float.
      Parameters:
      aFloatAsDouble - whether or not floating point values are parsed as Float or Double.

    • isParseFloatAsDouble

      public boolean isParseFloatAsDouble()
      Indicates whether or not floating point values are parsed as a Float or a Double. false for Float, true for Double.
      Returns:
      whether or not floating point values are parsed as Float or Double. false for Float, true for Double

    • setWithFeatures

      public final void setWithFeatures(boolean aReadWithFeatures)
      Sets whether the features of the objects should be read or not. If true the decoder will try to read the corresponding DBF file. If false the features will be read depending on the value of withLazyFeaturing. By default the value is true.
      See Also:

    • setWithLazyFeaturing

      public void setWithLazyFeaturing(boolean aLazyFeaturing)
      Sets whether the features of the objects should be read with the lazy mechanism or not. Default value is false. If withFeatures is false this property is of no importance.
      Parameters:
      aLazyFeaturing - true if the features of the objects should be read with the lazy mechanism.
      See Also:

    • isWithLazyFeaturing

      public boolean isWithLazyFeaturing()
      Returns whether the decoder will read the object's features with the lazy mechanism or not.
      Returns:
      whether the decoder will read the object's features with the lazy mechanism or not.
      See Also:

    • setLazyFeaturingOffForHTTP

      public void setLazyFeaturingOffForHTTP(boolean aLazyFeaturingOffForHTTP)
      Sets whether the lazy feature mechanism should be switched of in case files are retrieved via a http connection.
      Parameters:
      aLazyFeaturingOffForHTTP - true if the lazy feature mechanism should be switched of in case files are retrieved via a http connection.
      See Also:

    • isLazyFeaturingOffForHTTP

      public boolean isLazyFeaturingOffForHTTP()
      Returns whether the lazy feature mechanism should be switched of in case files are retrieved via a http connection.
      Returns:
      true if the lazy feature mechanism should be switched of in case files are retrieved via a http connection.
      See Also:

    • setUseXYFloatPoint

      public void setUseXYFloatPoint(boolean aUseXYFloatPoint)
      Sets whether the decoder should return shapes containing TLcdXYFloatPoints instead of the normal TLcdXYPoints.
      Parameters:
      aUseXYFloatPoint - true if the decoder should return shapes containing TLcdXYFloatPoints instead of the normal TLcdXYPoints.
      See Also:

    • isUseXYFloatPoint

      public boolean isUseXYFloatPoint()
      Returns whether the decoder returns shapes containing TLcdXYFloatPoints instead of the normal TLcdXYPoints.
      Returns:
      whether the decoder returns shapes containing TLcdXYFloatPoints instead of the normal TLcdXYPoints.
      See Also:

    • getUseXYFloatPoint

      public boolean getUseXYFloatPoint()
      Returns whether the decoder returns shapes containing TLcdXYFloatPoints instead of the normal TLcdXYPoints.
      Returns:
      whether the decoder returns shapes containing TLcdXYFloatPoints instead of the normal TLcdXYPoints.
      See Also:

    • getDecodingBounds

      public ILcdBounds getDecodingBounds()
      Returns the decodingBounds of this decoder.
      Returns:
      The decodingBounds of this decoder.
      See Also:

    • setDecodingBounds

      public void setDecodingBounds(ILcdBounds aDecodingBounds)
      Sets the decodingBounds of the decoder to aDecodingBounds. Only those elements of the SHP file of which the bounds interact with the decodingBounds end up in the decoded model. If the decodingBounds is null, no filtering is performed. Default value is null.
      Parameters:
      aDecodingBounds - The new decodingBounds to be set.
      See Also:

    • getDisplayName

      public String getDisplayName()
      Returns the display name to use for this decoder.
      Specified by:
      getDisplayName in interface ILcdModelDecoder
      Returns:
      "ESRI-ShapeFile".

    • getDefaultExtension

      public String getDefaultExtension()
      Returns the default extension for files that can be read with this decoder.
      Returns:
      "shp".

    • setFeatureIndexForDisplayName

      public void setFeatureIndexForDisplayName(int aFeatureIndexForDisplayName)
      Set the index of the feature to be used as default display name (e.g. the feature value to be used by the Object.toString() method). This index shall be chosen taking into account the feature ordering in the dbf file to decode. The default value is 0;
      Parameters:
      aFeatureIndexForDisplayName - the index of the feature to be used as default display name.
      See Also:

    • getFeatureIndexForDisplayName

      public int getFeatureIndexForDisplayName()
      Returns the index of the feature to be used as a default display name.
      Returns:
      the index of the feature to be used as a default display name.
      See Also:

    • 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 the file extension is <defaultExtension> or <defaultExtension>.gz, false otherwise (<defaultExtension> is the String returned by getDefaultExtension.
      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:

    • setInputStreamFactory

      public void setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)
      Sets the factory that will create input streams from which models can be decoded.
      Specified by:
      setInputStreamFactory in interface ILcdInputStreamFactoryCapable
      Parameters:
      aInputStreamFactory - the input stream factory to be used.

    • getInputStreamFactory

      public ILcdInputStreamFactory getInputStreamFactory()
      Returns the factory that creates input streams from which models are decoded.
      Specified by:
      getInputStreamFactory in interface ILcdInputStreamFactoryCapable
      Returns:
      the input stream factory that is used.

    • getModelFactory

      public ILcdModelFactory getModelFactory()
      Returns the factory object used for creating the output model.
      Returns:
      the model factory.

    • setModelFactory

      public void setModelFactory(ILcdModelFactory aModelFactory)
      Sets the factory object used for creating the output model.
      Parameters:
      aModelFactory - the model factory.

    • decode

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

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

    • makeVectorModel

      protected ILcdModel makeVectorModel() throws IOException
      Creates a TLcdVectorModel, sets a model reference, adds all the SHP Objects in the TLcdVectorModel and closes the inputStream.
      Returns:
      a TLcdVectorModel containing all objects retrieved from the input stream.
      Throws:
      IOException - when an I/O error occurs while reading the model from the input.

    • makeIndexedModel

      protected ILcdModel makeIndexedModel() throws IOException
      Creates a TLcdVectorModel by calling makeVectorModel() and then converts it to ILcd2DBoundsIndexedModel.
      Returns:
      an indexed model containing all objects from the input stream.
      Throws:
      IOException - when an I/O error occurs while reading the model from the input.
      See Also:

    • readData

      protected int readData(ILcdModel aModel, int aCoordType) throws IOException
      Reads data from the input stream into a model.
      Parameters:
      aModel - the model the objects created from the data are put in.
      aCoordType - the type of data read ( Cartesian or Geodetic ).
      Returns:
      the number of words in a record.
      Throws:
      IOException - when reading the data fails due to I/O.
      See Also:

    • isValidShape

      public static boolean isValidShape(int aShapeType)
      Checks whether a shape type is valid for this decoder.
      Parameters:
      aShapeType - the shape type to check.
      Returns:
      true if the shape type is one of the following:

    • readShapeType

      protected int readShapeType() throws IOException
      Reads one integer as a shape type.
      Returns:
      the code for the shape type.
      Throws:
      IOException - when reading fails due to I/O.

    • readFeaturedObject

      protected ILcdFeatured readFeaturedObject() throws IOException
      Reads the features to an object.
      Returns:
      the features of an object.
      Throws:
      IOException - when reading fails due to I/O.

    • readPoint

      protected ILcd2DEditablePoint readPoint(int aCoordType) throws IOException
      Creates and reads a 2D point from the SHP file.
      Parameters:
      aCoordType - the type of coordinates, cartesian or geodetic (ILcdGeoReference).
      Returns:
      a 2D point read from the SHP file.
      Throws:
      IOException - when an I/O error occurs while reading from the input.

    • readPoint

      protected ILcd2DEditablePoint readPoint(int aCoordType, int aDimension) throws IOException
      Creates a point with the specified dimension (2D,3D). The first two coordinates are read.
      Parameters:
      aCoordType - the type of coordinates, cartesian or geodetic (ILcdGeoReference).
      aDimension - the dimension of the point to be read.
      Returns:
      a point with the specified dimension (2D,3D) and coordinate type.
      Throws:
      IOException - when an I/O error occurs while reading from the input.

    • readPointM

      protected ILcd2DEditablePoint readPointM(int aCoordType) throws IOException
      Reads a 2 dimensional point and a value from the input.
      Parameters:
      aCoordType - the type of coordinates, cartesian or geodetic (ILcdGeoReference).
      Returns:
      a TLcdSHPPointM
      Throws:
      IOException - when an I/O error occurs.

    • readPointZ

      protected ILcd3DEditablePoint readPointZ(int aCoordType) throws IOException
      Reads a 2 dimensional point and a value from the input.
      Parameters:
      aCoordType - the type of coordinates, cartesian or geodetic (ILcdGeoReference).
      Returns:
      a TLcdSHPPointZ.
      Throws:
      IOException - when an I/O error occurs.

    • readOtherShapes

      protected ILcdShape[] readOtherShapes(int aCoordType, int aRecordByteSize) throws IOException
      Can be redefined to order to define how to read an ESRI shape not supported by this ILcdModelDecoder
      Skips the unsupported shape.
      Parameters:
      aCoordType - the ESRI shape type (see ESRI documentation).
      aRecordByteSize - the size of the record in bytes ( read from the input stream ).
      Returns:
      null.
      Throws:
      IOException - when an I/O error occurs while reading from the input.

    • skipBytes

      protected final void skipBytes(int aNumberOfBytesToSkip) throws IOException
      Skips a number of bytes from the input stream.
      Parameters:
      aNumberOfBytesToSkip - the number of bytes to skip.
      Throws:
      IOException - when an I/O error occurs.

    • readPolyline

      protected ILcdShape[] readPolyline(int aCoordType, int aRecordByteSize) throws IOException
      Returns null when the decodingBounds is not null and the bounds of the polyline do not interact with the decodingBounds.
      Parameters:
      aCoordType - the type of coordinates, cartesian or geodetic (ILcdGeoReference).
      aRecordByteSize - the size of the record in bytes ( read from the input stream ).
      Returns:
      an array of TLcdSHPPolylineZ objects.
      Throws:
      IOException - when an I/O error occurs.

    • readPolylineM

      protected ILcdShape[] readPolylineM(int aCoordType, int aRecordByteSize) throws IOException
      Reads a polyline consisting of points accompanied with a value.
      Parameters:
      aCoordType - the type of coordinates, cartesian or geodetic (ILcdGeoReference).
      aRecordByteSize - the size of the record in bytes ( read from the input stream ).
      Returns:
      an array of TLcdSHPPolylineZ
      Throws:
      IOException - when an I/O error occurs.

    • readPolylineZ

      protected ILcdShape[] readPolylineZ(int aCoordType, int aRecordByteSize) throws IOException
      Reads a polyline consisting of three dimensional points accompanied with a value.
      Parameters:
      aCoordType - the type of coordinates, cartesian or geodetic (ILcdGeoReference).
      aRecordByteSize - the size of the record in bytes ( read from the input stream ).
      Returns:
      an array of TLcdSHPPolylineZ
      Throws:
      IOException - when an I/O error occurs.

    • readPolygon

      protected ILcdShape[] readPolygon(int aCoordType, int aRecordByteSize) throws IOException
      Reads a polygon from the input.
      Parameters:
      aCoordType - the type of coordinates, cartesian or geodetic (ILcdGeoReference).
      aRecordByteSize - the size of the record in bytes ( read from the input stream ).
      Returns:
      an array containing one TLcdComplexPolygon.
      Throws:
      IOException - when reading the data fails due to I/O.

    • readPolygonM

      protected ILcdShape[] readPolygonM(int aCoordType, int aRecordByteSize) throws IOException
      Reads a polygon consisting of measured points from the input.
      Parameters:
      aCoordType - the type of coordinates, cartesian or geodetic (ILcdGeoReference).
      aRecordByteSize - the size of the record in bytes ( read from the input stream ).
      Returns:
      an array containing one TLcdComplexPolygon.
      Throws:
      IOException - when an I/O error occurs.

    • readPolygonZ

      protected ILcdShape[] readPolygonZ(int aCoordType, int aRecordByteSize) throws IOException
      Reads a polygon consisting of three dimensional measured points from the input.
      Parameters:
      aCoordType - the type of coordinates, cartesian or geodetic (ILcdGeoReference).
      aRecordByteSize - the size of the record in bytes ( read from the input stream ).
      Returns:
      an array containing one TLcdComplexPolygon.
      Throws:
      IOException - when an I/O error occurs.

    • readMultiPoint

      protected ILcdShape[] readMultiPoint(int aCoordType, int aRecordByteSize) throws IOException
      Reads a set of points as a multi point.
      Parameters:
      aCoordType - the type of coordinates, cartesian or geodetic (ILcdGeoReference).
      aRecordByteSize - the size of the record in bytes ( read from the input stream ).
      Returns:
      an array containing one ILcd2DEditablePolypoint.
      Throws:
      IOException - when an I/O error occurs.

    • readMultiPointM

      protected ILcdShape[] readMultiPointM(int aCoordType, int aRecordByteSize) throws IOException
      Reads a set of measured points as a multi point.
      Parameters:
      aCoordType - the type of coordinates, cartesian or geodetic (ILcdGeoReference).
      aRecordByteSize - the size of the record in bytes ( read from the input stream ).
      Returns:
      an array containing one TLcdSHPMultiPointZ.
      Throws:
      IOException - when an I/O error occurs.

    • readMultiPointZ

      protected ILcdShape[] readMultiPointZ(int aCoordType, int aRecordByteSize) throws IOException
      Reads a set of three dimensional measured points as a multi point.
      Parameters:
      aCoordType - the type of coordinates, cartesian or geodetic (ILcdGeoReference).
      aRecordByteSize - the size of the record in bytes ( read from the input stream ).
      Returns:
      an array containing one TLcdSHPMultiPointZ.
      Throws:
      IOException - when an I/O error occurs.

    • readBounds

      protected ILcdBounds readBounds(int aCoordType) throws IOException
      Reads a bounds from the input.
      Parameters:
      aCoordType - the type of coordinates, cartesian or geodetic (ILcdGeoReference).
      Returns:
      a ILcdBounds
      Throws:
      IOException - when an I/O error occurs.

    • formatShapeType

      public static String formatShapeType(int aShapeType)
      Returns a shape type by in human-readable form.
      Parameters:
      aShapeType - the shape type to format.
      Returns:
      the human-readable form of a shape type.

    • isValidField

      protected boolean isValidField(String aField)
      Returns whether the field with name aField is a valid field in the ILcdModel produced by this TLcdSHPModelDecoder.
      Parameters:
      aField - the field to check.
      Returns:
      true if and only if the field with name aField is a valid field in the ILcdModel produced by this TLcdSHPModelDecoder.