com.luciad.format.gdf

Graph and Routing EngineClass TLcdGDFModelDecoder

java.lang.Object

com.luciad.format.gdf.TLcdGDFModelDecoder

All Implemented Interfaces:

ILcdInputStreamFactoryCapable, ILcdModelDecoder

@LcdService(service=ILcdModelDecoder.class,
            priority=20000)
public class TLcdGDFModelDecoder
extends Object
implements ILcdModelDecoder, ILcdInputStreamFactoryCapable

This ILcdModelDecoder decodes Geographic Data Files (GDF standard).

Input

File	Required	Entry point	Description
*.gdf	x	x	Main file containing the data
*.gdf.gz			Compressed main file containing the data
*.gdf.zip			Compressed main file containing the data

Supported transfer protocols

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

Model structure

The models returned by this decoder are hierarchically structured, corresponding to the structure of the GDF data: each returned model is a TLcdModelList, representing a GDF dataset. This dataset contains a number of GDF layers (which are also TLcdModelList objects and should not be confused with LuciadLightspeed layers), each having a number of GDF sections. These sections are ILcd2DBoundsIndexedModel objects, containing the actual GDF features.

On each level (dataset, layer, section), the model has a corresponding model descriptor, containing information that is specific to that level (see the GDF specification and the documentation of the GDF model descriptors).

Model descriptor

• All models returned by this model decoder have a TLcdGDFDatasetModelDescriptor.

Model reference

• All models returned by this model decoder have an ILcdGeodeticReference.

Model elements

• Models decoded by this model decoder will only contain ILcdGDFFeature objects (ILcdGDFPointFeature, ILcdGDFLineFeature, ILcdGDFAreaFeature and ILcdGDFComplexFeature). All other supported records in the table above are accessible via these features or via the model descriptors.
• All domain objects implement the ILcdDataObject interface, providing access to the object's type, but since GDF does not define the attributes that can occur within a feature class, the data types do not expose any properties.

Sample code

 ILcdModelDecoder decoder = new TLcdGDFModelDecoder();
 ILcdModel model = decoder.decode( "streets.gdf" );
 

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

• The current implementation is based on, and compatible with version 3.0 of the GDF specification (CEN TC278, October 1995), but some of the modifications made in version 4.0 (ISO standard 14825) are already incorporated in the package.
The following GDF record types are currently supported:

GDF record type	Decoded object (or object containing the record data)
Dataset Header Record	TLcdGDFDatasetModelDescriptor
Attribute Definition Record	TLcdGDFAttributeType
Default Attribute Value Record	TLcdGDFAttributeType
Section Header Record	TLcdGDFSectionModelDescriptor
XY-coordinates Record
Node Record
Edge Record
Face Record
Point Feature Record	ILcdGDFPointFeature
Line Feature Record	ILcdGDFLineFeature
Area Feature Record	ILcdGDFAreaFeature
Complex Feature Record	ILcdGDFComplexFeature
Text Record	ILcdGDFText
Time Domain Record	ILcdGDFTimeDomain
Attribute Record	ILcdGDFAttribute
Conversion Record
Relationship Record	ILcdGDFRelationship

Since:

5.1

Constructor Summary

Constructors

Constructor and Description
TLcdGDFModelDecoder()

Method Summary

Modifier and Type	Method and Description
boolean	canDecodeSource(String aSourceAsString) Checks whether this model decoder can decode the specified data source.
ILcdModel	decode(String aSourceName) Creates a new model from the given data source.
String	getDefaultExtension() Returns the default extension for GDF files.
String	getDisplayName() Returns a short, displayable name for the format that is decoded by this ILcdModelDecoder.
ILcdFilter	getFeatureFilter() Returns the feature filter used in this model decoder, or null if none is used.
ILcdGDFFeatureThemeMap	getFeatureThemeMap() Returns the ILcdGDFFeatureThemeMap used by this decoder.
ILcdInputStreamFactory	getInputStreamFactory() Returns the factory that is used to create input streams from which models are decoded.
String[]	getTextTypeCodes() Returns the list of type codes whose attribute value is a pointer to a name record.
String[]	getTimeDomainTypeCodes() Returns the list of type codes whose attribute value is a pointer to a time domain record.
boolean	isDecodeAttributes() Returns true if the attribute decoding flag is set, falseotherwise.
boolean	isDecodeComplexFeatures() Returns true if the complex features decoding flag is set, falseotherwise.
boolean	isDecodeRelationships() Returns true if the relationship decoding flag is set, falseotherwise.
boolean	isDecodeZCoordinate() Returns true if the z coordinate decoding flag is set, falseotherwise.
void	setDecodeAttributes(boolean aDecodeAttributes) Sets a flag indicating whether attributes should be decoded or not.
void	setDecodeComplexFeatures(boolean aDecodeComplexFeatures) Sets a flag indicating whether complex features should be decoded or not.
void	setDecodeRelationships(boolean aDecodeRelationships) Sets a flag indicating whether relationships should be decoded or not.
void	setDecodeZCoordinate(boolean aDecodeZCoordinate) Sets a flag indicating whether the Z value of coordinates should be taken into account or not.
void	setFeatureFilter(ILcdFilter aFeatureFilter) Sets a filter to select which features will be added to the decoded models and which not.
void	setFeatureThemeMap(ILcdGDFFeatureThemeMap aFeatureThemeMap) Sets the ILcdGDFFeatureThemeMap to be used by this decoder.
void	setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory) Sets the factory that will create input streams from which models can be decoded.
void	setTextTypeCodes(String[] aTextTypeCodes) Sets the array of type codes whose attribute value is a pointer to a text record.
void	setTimeDomainTypeCodes(String[] aTimeDomainTypeCodes) Sets the array of type codes whose attribute value is a pointer to a time domain record.

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, decodeModelMetadata, decodeSource, discoverDataSources

Constructor Detail

TLcdGDFModelDecoder

public TLcdGDFModelDecoder()

Method Detail

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 factory that creates an input stream based on a source name.

See Also:

getInputStreamFactory()

getInputStreamFactory

public ILcdInputStreamFactory getInputStreamFactory()

Returns the factory that is used to create input streams from which models are decoded.

Specified by:

getInputStreamFactory in interface ILcdInputStreamFactoryCapable

Returns:

the factory that is used to create input streams from which models are decoded.

See Also:

setInputStreamFactory(com.luciad.io.ILcdInputStreamFactory)

setFeatureFilter

public void setFeatureFilter(ILcdFilter aFeatureFilter)

Sets a filter to select which features will be added to the decoded models and which not. The filter influences only which features will be directly contained in the models. Features which are filtered can still be present in the model via a reference from another feature (e.g. a road element that has been filtered can still be present via a complex feature from which it is part of).

Parameters:

aFeatureFilter - the filter to apply, or null if no filter should be used.

See Also:

getFeatureFilter()

getFeatureFilter

public ILcdFilter getFeatureFilter()

Returns the feature filter used in this model decoder, or null if none is used.

Returns:

the feature filter used in this model decoder, or null if none is used.

See Also:

setFeatureFilter(com.luciad.util.ILcdFilter)

setFeatureThemeMap

public void setFeatureThemeMap(ILcdGDFFeatureThemeMap aFeatureThemeMap)

Sets the ILcdGDFFeatureThemeMap to be used by this decoder. A model is created per theme in the feature theme map - and all features will be put in the appropriate model, according to the feature theme map. If null, all features will be put in one model. By default, the TLcdGDFDefaultFeatureThemeMap is used.

Parameters:

aFeatureThemeMap - the ILcdGDFFeatureThemeMap that is to be used by this decoder.

See Also:

getFeatureThemeMap()

getFeatureThemeMap

public ILcdGDFFeatureThemeMap getFeatureThemeMap()

Returns the ILcdGDFFeatureThemeMap used by this decoder.

Returns:

the ILcdGDFFeatureThemeMap used by this decoder.

See Also:

setFeatureThemeMap(com.luciad.format.gdf.ILcdGDFFeatureThemeMap)

setDecodeZCoordinate

public void setDecodeZCoordinate(boolean aDecodeZCoordinate)

Sets a flag indicating whether the Z value of coordinates should be taken into account or not. Setting this flag to false will result in a slightly better memory usage.

The default value is false.

Parameters:

aDecodeZCoordinate - boolean indicating whether the Z value of coordinates should be taken into account or not.

isDecodeZCoordinate

public boolean isDecodeZCoordinate()

Returns true if the z coordinate decoding flag is set, falseotherwise.

Returns:

true if the z coordinate decoding flag is set, falseotherwise.

setDecodeAttributes

public void setDecodeAttributes(boolean aDecodeAttributes)

Sets a flag indicating whether attributes should be decoded or not. Setting this flag to false will result in a slightly faster decoding and will require less memory, but not all information (e.g. road classes, names, ...) will be available in the model.

The default value is true.

Parameters:

aDecodeAttributes - boolean indicating whether to decode attributes or not.

isDecodeAttributes

public boolean isDecodeAttributes()

Returns true if the attribute decoding flag is set, falseotherwise.

Returns:

true if the attribute decoding flag is set, falseotherwise.

setDecodeRelationships

public void setDecodeRelationships(boolean aDecodeRelationships)

Sets a flag indicating whether relationships should be decoded or not. Setting this flag to false will result in a slightly faster decoding and will require less memory, but not all information (e.g. turn restrictions) will be available in the model.

The default value is true.

Parameters:

aDecodeRelationships - boolean indicating whether to decode relationships or not.

isDecodeRelationships

public boolean isDecodeRelationships()

Returns true if the relationship decoding flag is set, falseotherwise.

Returns:

true if the relationship decoding flag is set, falseotherwise.

setDecodeComplexFeatures

public void setDecodeComplexFeatures(boolean aDecodeComplexFeatures)

Sets a flag indicating whether complex features should be decoded or not. Setting this flag to false will result in a slightly faster decoding and will require less memory. All features constituting a complex feature will be available in the model, but the complex feature itself will not.

The default value is true.

Parameters:

aDecodeComplexFeatures - boolean indicating whether to decode complex features or not.

isDecodeComplexFeatures

public boolean isDecodeComplexFeatures()

Returns true if the complex features decoding flag is set, falseotherwise.

Returns:

true if the complex features decoding flag is set, falseotherwise.

setTextTypeCodes

public void setTextTypeCodes(String[] aTextTypeCodes)

Sets the array of type codes whose attribute value is a pointer to a text record.

The default list of type codes is based on the GDF 4 specification (ISO/DIS 14825 p333):

Description	Attribute Type Code
Official Name Prefix	OX
Official Name Text	ON
Alternate Name Text	AN
Multi-media Attachment Name	MN
Directional Prefix	DP
Street Type Prefix	SX
Official Street Name Text	OF
Alternate Street Name TExt	AL
Street Type Suffix	ST
Directional Suffix	DS
Pronunciation	PO
Exit Number	EN
Route Number	RN
Route Number on Sign	RX
Building Class Name	BC
Destination Location	DL
Other Textual Content on Traffic Sign	CT
Brand Name	BA
Place Name	PE
Street Name	SN
Telefax Number	TX
Telephone Number	TL

Parameters:

aTextTypeCodes - array of type codes whose attribute value is a pointer to a text record.

getTextTypeCodes

public String[] getTextTypeCodes()

Returns the list of type codes whose attribute value is a pointer to a name record.

Returns:

the list of type codes whose attribute value is a pointer to a name record.

setTimeDomainTypeCodes

public void setTimeDomainTypeCodes(String[] aTimeDomainTypeCodes)

Sets the array of type codes whose attribute value is a pointer to a time domain record.

The default list of type codes is based on the GDF 4 specification (ISO/DIS 14825 p333):

Description	Attribute Type Code
Validity Period	VP
Opening Record	OP

Parameters:

aTimeDomainTypeCodes - array of type codes whose attribute value is a pointer to a time domain record.

getTimeDomainTypeCodes

public String[] getTimeDomainTypeCodes()

Returns the list of type codes whose attribute value is a pointer to a time domain record.

Returns:

the list of type codes whose attribute value is a pointer to a time domain record.

getDefaultExtension

public String getDefaultExtension()

Returns the default extension for GDF files.

Returns:

"gdf".

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

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:

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