com.luciad.format.shp

LuciadLightspeedClass 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

• EPSG references (<filename>.epsg): see TLcdEPSGModelReferenceDecoder for more info.
• WKT references (<filename>.prj): see TLcdWKTModelReferenceDecoder for more info.
• Luciad encoded model references (<filename>.ref): see TLcdModelReferenceDecoder for more info.

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 Type	Decoded 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

• ESRI Shapefile Technical Description - An ESRI White Paper. July 1998.

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 Summary

Constructors

Constructor and Description
TLcdSHPModelDecoder2()

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(String aSourceName) Creates a new model from the given data source.
TLcdModelMetadata	decodeModelMetadata(String aSourceName) Decodes metadata for the specified data source.
ILcdModelReference	getDefaultModelReference() Returns the model reference to be used for models when the model reference decoder is set to null.
String	getDisplayName() Returns a short, displayable name for the format that is decoded by this ILcdModelDecoder.
ILcdModelReferenceDecoder	getModelReferenceDecoder() Returns the decoder used to produce model references.
boolean	isTrimStringPropertyValues() Indicates whether or not string values are trimmed when decoding DBF files.
void	setDefaultModelReference(ILcdModelReference aDefaultModelReference) Sets the model reference to be used for models when the model reference decoder is set to null.
void	setModelReferenceDecoder(ILcdModelReferenceDecoder aModelReferenceDecoder) Sets the decoder to use to produce model references for models created with this decoder.
void	setTrimStringPropertyValues(boolean aTrimStringPropertyValues) Specifies whether or not leading and trailing whitespace should be removed from string properties while decoding DBF files.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.luciad.model.ILcdModelDecoder

canDecodeSource, decodeModelMetadata, decodeSource, discoverDataSources

Constructor Detail

TLcdSHPModelDecoder2

public TLcdSHPModelDecoder2()

Method Detail

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:

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.

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);
      }
   }
 

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)

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:

ILcdModelDecoder.canDecodeSource(String)

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()

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:

setDefaultModelReference(com.luciad.model.ILcdModelReference)

getModelReferenceDecoder

public ILcdModelReferenceDecoder getModelReferenceDecoder()

Returns the decoder used to produce model references.

Returns:

the decoder to produce model references.

See Also:

setModelReferenceDecoder(com.luciad.model.ILcdModelReferenceDecoder), setDefaultModelReference(com.luciad.model.ILcdModelReference)

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:

getModelReferenceDecoder(), setDefaultModelReference(com.luciad.model.ILcdModelReference)

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:

setTrimStringPropertyValues(boolean)