Detailed Description

This class is used for loading GML instance data into a MapLink TSLStandard DataLayer.

There are 3 main ways of loading a GML instance data document:

Pre-loading the application schema A pre-loaded application schema is provided along with the location of the application schema. The application schema should be pre-loaded using the TSLGMLApplicationSchemaLoader class.
Loading the referenced application schema The location of the application schema is extracted from the instance data document and loaded before the instance data is parsed.
Loading without an application schema The instance data document can be loaded without an application schema. This is not advised but may be necessary when the instance data does not conform to the application schema or the schema is not accessible.

Furthermore, the instance data can be provided in one of the following 3 ways:

As a file path
As a URL
In the form of a buffer

Through the other methods of this class, certain other aspects of the loading may be altered. These include:

Altering the MU to TMC scaling and translation.
A TSLGMLUnhandledFeatureCallback may optionally be provided to an instance of this class which allows feature instances that are not supported to be returned to the caller. Refer to the documentation for the unhandledFeature Callback method for details of this callbacks use and the cases in which it will be invoked.
A TSLGMLPropertyMapping or TSLGMLPropertyMappingSet may be provided to the load call that alters how properties of the a GML feature are stored on the MapLink geometry object that represents the feature.

Public Member Functions
	TSLGMLInstanceDataLoader ()

void	destroy ()

bool	getTransverseMercatorJHSFormula () const

bool	load (const char location, const TSLGMLApplicationSchema schema, TSLStandardDataLayer destination, TSLCoordinateSystem &coordinateSystem)

bool	load (const char location, TSLStandardDataLayer destination, TSLCoordinateSystem &coordinateSystem, TSLGMLApplicationSchemaLoader schemaLoader, TSLGMLApplicationSchema **schema=0)

bool	load (const char location, TSLStandardDataLayer destination, TSLCoordinateSystem *&coordinateSystem)

bool	loadFromBuffer (const unsigned char buffer, unsigned int bufferLen, const TSLGMLApplicationSchema schema, TSLStandardDataLayer destination, TSLCoordinateSystem &coordinateSystem)

bool	loadFromBuffer (const unsigned char buffer, unsigned int bufferLen, TSLStandardDataLayer destination, TSLCoordinateSystem &coordinateSystem, const char location, TSLGMLApplicationSchemaLoader schemaLoader, TSLGMLApplicationSchema *schema=0)

bool	loadFromBuffer (const unsigned char buffer, unsigned int bufferLen, TSLStandardDataLayer destination, TSLCoordinateSystem *&coordinateSystem)

void	mapUnitShiftX (double value)

double	mapUnitShiftX () const

void	mapUnitShiftY (double value)

double	mapUnitShiftY () const

const TSLGMLPropertyMapping *	propertyMapping () const

void	propertyMapping (const TSLGMLPropertyMapping *newMapping)

const TSLGMLPropertyMappingSet *	propertyMappingSet () const

void	propertyMappingSet (const TSLGMLPropertyMappingSet *newMappingSet)

void	setTransverseMercatorJHSFormula (bool jhs)

bool	swapXandY () const

void	swapXandY (bool value)

void	tmcPerMU (double value)

double	tmcPerMU () const

void	unhandledFeatureCallback (TSLGMLUnhandledFeatureCallback *callback)

const TSLGMLUnhandledFeatureCallback *	unhandledFeatureCallback () const

void	useDynamicArcForWGS84 (bool useDynamicArc)

void *	operator new (size_t size)

void *	operator new (size_t size, char *filename, int line)

Constructor & Destructor Documentation

◆ TSLGMLInstanceDataLoader()

TSLGMLInstanceDataLoader::TSLGMLInstanceDataLoader ( )

Member Function Documentation

◆ destroy()

void TSLGMLInstanceDataLoader::destroy ( )

Destroy this object.

This method must be used instead of delete.

◆ getTransverseMercatorJHSFormula()

bool TSLGMLInstanceDataLoader::getTransverseMercatorJHSFormula ( ) const

Queries if the Transverse Mercator JHS formula is to be used when data is in a Transverse Mercator projection.

The setting will be used to create a local Coordinate System to place the retrieved data. If the setting is changed after the layer has been configured or during layer configuration you may either end up using the USGS Snyder or JHS formula, which you end up with is undefined in these cases.

The default setting is to use the USGS Snyder formula.

Returns true if the layer is set to use the JHS formula for Transverse Mercator.

◆ load() [1/3]

bool TSLGMLInstanceDataLoader::load	(	const char *	location,
		const TSLGMLApplicationSchema *	schema,
		TSLStandardDataLayer *	destination,
		TSLCoordinateSystem *&	coordinateSystem )

Loads the instance data from the path specified in the location parameter. The TSLStandardDataLayer passed in the destination parameter will be populated with the data imported from the instance data. The pre-parsed schema definition passed in the schema parameter will be used when loading the data - regardless of whether the instance data contains a schema reference.

The schema definition will be added to the standard data layer's data handler and feature class list if this has not already occurred.

Parameters

location	The location to load the schema from. This may be a file system path or a url.
schema	The pre-parsed schema that the instance data conforms to.
destination	This standard data layer will be populated with the feature instance data and feature definitions.
coordinateSystem	This parameter will be populated with the common coordinate system used in the instance data. The user assumes ownership of the coordinate system and should call its destroy method when it is no longer required.

Returns: true on success, false otherwise.

◆ load() [2/3]

bool TSLGMLInstanceDataLoader::load	(	const char *	location,
		TSLStandardDataLayer *	destination,
		TSLCoordinateSystem *&	coordinateSystem )

Loads the instance data from the path specified in the location parameter. The TSLStandardDataLayer passed in the destination parameter will be populated with the data imported from the instance data.

Regardless of whether the instance data contain a reference to a schema, no schema shall be used when loading the instance data.

Parameters

location	The location to load the schema from. This may be a file system path or a url.
destination	This standard data layer will be populated with the feature instance data and feature definitions.
coordinateSystem	This parameter will be populated with the common coordinate system used in the instance data. The user assumes ownership of the coordinate system and should call its destroy method when it is no longer required.

Returns: true on success, false otherwise.

◆ load() [3/3]

bool TSLGMLInstanceDataLoader::load	(	const char *	location,
		TSLStandardDataLayer *	destination,
		TSLCoordinateSystem *&	coordinateSystem,
		TSLGMLApplicationSchemaLoader *	schemaLoader,
		TSLGMLApplicationSchema **	schema = 0 )

Loads the instance data from the path specified in the location parameter. The TSLStandardDataLayer passed in the destination parameter will be populated with the data imported from the instance data.

Should the instance data contain a reference to a schema, then it will be loaded using the passed schema loader and returned to the user in the schema parameter.

Parameters

location	The location to load the schema from. This may be a file system path or a url.
destination	This standard data layer will be populated with the feature instance data and feature definition.
coordinateSystem	This parameter will be populated with the common coordinate system used in the instance data. The user assumes ownership of the coordinate system and should call its destroy method when it is no longer required.
schemaLoader	This schema loader will be used when loading the schema should the instance data reference one. If the user does not provide a schema loader, a stock loader shall be used.
schema	Should the user wish to retain the schema definition for the loading of additional instance data, then they should pass a pointer to be populated with the definition loaded. The user assumes ownership of the schema definition and should delete it when it is no longer needed. If the instance data does not contain a reference to a schema, then the passed pointer will be pointed at NULL.

Returns: true on success, false otherwise.

◆ loadFromBuffer() [1/3]

bool TSLGMLInstanceDataLoader::loadFromBuffer	(	const unsigned char *	buffer,
		unsigned int	bufferLen,
		const TSLGMLApplicationSchema *	schema,
		TSLStandardDataLayer *	destination,
		TSLCoordinateSystem *&	coordinateSystem )

Loads the instance data from the passed buffer. The TSLStandardDataLayer passed in the destination parameter will be populated with the data imported from the instance data. The pre-parsed schema definition passed in the schema parameter will be used when loading the data - regardless of whether the instance data contains a schema reference.

The schema definition will be added to the standard data layer's data handler and feature class list if this has not already occurred.

Parameters

buffer	The buffer containing the instance data.
bufferLen	The length of the buffer passed.
schema	The pre-parsed schema that the instance data conforms to.
destination	This standard data layer will be populated with the feature instance data and feature definitions.
coordinateSystem	This parameter will be populated with the common coordinate system used in the instance data. The user assumes ownership of the coordinate system and should call its destroy method when it is no longer required.

Returns: true on success, false otherwise.

◆ loadFromBuffer() [2/3]

bool TSLGMLInstanceDataLoader::loadFromBuffer	(	const unsigned char *	buffer,
		unsigned int	bufferLen,
		TSLStandardDataLayer *	destination,
		TSLCoordinateSystem *&	coordinateSystem )

Loads the instance data from the passed buffer. The TSLStandardDataLayer passed in the destination parameter will be populated with the data imported from the instance data.

Regardless of whether the instance data contain a reference to a schema, no schema shall be used when loading the instance data.

Parameters

buffer	The buffer containing the instance data.
bufferLen	The length of the buffer passed.
destination	This standard data layer will be populated with the feature instance data and feature definitions.
coordinateSystem	This parameter will be populated with the common coordinate system used in the instance data. The user assumes ownership of the coordinate system and should call its destroy method when it is no longer required.

Returns: true on success, false otherwise.

◆ loadFromBuffer() [3/3]

bool TSLGMLInstanceDataLoader::loadFromBuffer	(	const unsigned char *	buffer,
		unsigned int	bufferLen,
		TSLStandardDataLayer *	destination,
		TSLCoordinateSystem *&	coordinateSystem,
		const char *	location,
		TSLGMLApplicationSchemaLoader *	schemaLoader,
		TSLGMLApplicationSchema **	schema = 0 )

Loads the instance data from the passed buffer. The TSLStandardDataLayer passed in the destination parameter will be populated with the data imported from the instance data.

Should the instance data contain a reference to a schema, then it will be loaded using the passed schema loader and returned to the user in the schema parameter.

Parameters

buffer	The buffer containing the instance data.
bufferLen	The length of the buffer passed.
destination	This standard data layer will be populated with the feature instance data and feature definition.
coordinateSystem	This parameter will be populated with the common coordinate system used in the instance data. The user assumes ownership of the coordinate system and should call its destroy method when it is no longer required.
location	If the instance data contains a relative path to the schema location, this location will be used to location it. Its value should be the original location that the instance data was retrieved from. Null may be passed for this argument, but should the instance data used a relative path then the call will fail.
schemaLoader	This schema loader will be used when loading the schema should the instance data reference one. If the user does not provide a schema loader, a stock loader shall be used.
schema	Should the user wish to retain the schema definition for the loading of additional instance data, then they should pass a pointer to be populated with the definition loaded. The user assumes ownership of the schema definition and should delete it when it is no longer needed. If the instance data does not contain a reference to a schema, then the passed pointer will be pointed at NULL.

Returns: true on success, false otherwise.

◆ mapUnitShiftX() [1/2]

double TSLGMLInstanceDataLoader::mapUnitShiftX ( ) const

Get the number of number of Map Units to offset the x-origin of TMC space, when importing instance data.

By default, this value will be 0.

◆ mapUnitShiftX() [2/2]

void TSLGMLInstanceDataLoader::mapUnitShiftX ( double value )

Set the number of number of Map Units to offset the x-origin of TMC space, when importing instance data.

By default, this value will be 0.

Parameters

value The new value to use.

◆ mapUnitShiftY() [1/2]

double TSLGMLInstanceDataLoader::mapUnitShiftY ( ) const

Get the number of number of Map Units to offset the y-origin of TMC space, when importing instance data.

By default, this value will be 0.

◆ mapUnitShiftY() [2/2]

void TSLGMLInstanceDataLoader::mapUnitShiftY ( double value )

Set the number of number of Map Units to offset the y-origin of TMC space, when importing instance data.

By default, this value will be 0.

Parameters

value The new value to use.

◆ operator new() [1/2]

void * TSLGMLInstanceDataLoader::operator new ( size_t size )

◆ operator new() [2/2]

void * TSLGMLInstanceDataLoader::operator new	(	size_t	size,
		char *	filename,
		int	line )

When included in an MFC application in debug mode, the debug new expects this to be here. Override it and return the same as the normal one. The library must include it when compiled in release mode, since the user's application may be in debug mode.

◆ propertyMapping() [1/2]

const TSLGMLPropertyMapping * TSLGMLInstanceDataLoader::propertyMapping ( ) const

Queries the current property mapping object set on the loader. The current property mapping can be set via the other propertyMapping method.

Rather than adding the properties of each GML feature instance as attributes to the corresponding MapLink entity's data sets, a mapping can be provide so that they are instead used to populated rendering attributes or property of the entity, such as its name or entity id.

There are 3 possible ways of using a mapping or mapping set:

Use neither. All attributes are are added to the MapLink entity's data set
Set a TSLGMLPropertyMapping instance on the loader using the property Mapping method. The same mapping is performed for all feature types.
Set a TSLGMLPrropertyMappingSet instance on the loader using the property Mapping method. Different mappings can be performed for each feature type and not all features types need have a mapping defined.

◆ propertyMapping() [2/2]

void TSLGMLInstanceDataLoader::propertyMapping ( const TSLGMLPropertyMapping * newMapping )

Sets the current property mapping object set on the loader. The current property mapping can be queried via the other propertyMapping method.

By setting a property mapping, and previously set property mapping or property mapping set will be cleared.

Rather than adding the properties of each GML feature instance as attributes to the corresponding MapLink entity's data sets, a mapping can be provide so that they are instead used to populated rendering attributes or property of the entity, such as its name or entity id.

There are 3 possible ways of using a mapping or mapping set:

Use neither. All attributes are are added to the MapLink entity's data set
Set a TSLGMLPropertyMapping instance on the loader using the property Mapping method. The same mapping is performed for all feature types.
Set a TSLGMLPrropertyMappingSet instance on the loader using the property Mapping method. Different mappings can be performed for each feature type and not all features types need have a mapping defined.

Parameters

newMapping The new mapping to set. A copy of the object passed will be taken if the object is valid. Null may be passed to clear the current property mapping.

◆ propertyMappingSet() [1/2]

const TSLGMLPropertyMappingSet * TSLGMLInstanceDataLoader::propertyMappingSet ( ) const

Queries the current property mapping set object held on the loader. The current property mapping set can be set via the other propertyMappingSet method.

Rather than adding the properties of each GML feature instance as attributes to the corresponding MapLink entity's data sets, a mapping can be provide so that they are instead used to populated rendering attributes or property of the entity, such as its name or entity id.

There are 3 possible ways of using a mapping or mapping set:

Use neither. All attributes are are added to the MapLink entity's data set
Set a TSLGMLPropertyMapping instance on the loader using the property Mapping method. The same mapping is performed for all feature types.
Set a TSLGMLPrropertyMappingSet instance on the loader using the property Mapping method. Different mappings can be performed for each feature type and not all features types need have a mapping defined.

◆ propertyMappingSet() [2/2]

void TSLGMLInstanceDataLoader::propertyMappingSet ( const TSLGMLPropertyMappingSet * newMappingSet )

Sets the current property mapping set object held on the loader. The current property mapping set can be queried via the other propertyMappingSet method.

By setting a property mapping set, any previously set property mapping or property mapping set will be cleared.

Rather than adding the properties of each GML feature instance as attributes to the corresponding MapLink entity's data sets, a mapping can be provide so that they are instead used to populated rendering attributes or property of the entity, such as its name or entity id.

There are 3 possible ways of using a mapping or mapping set:

Use neither. All attributes are are added to the MapLink entity's data set
Set a TSLGMLPropertyMapping instance on the loader using the property Mapping method. The same mapping is performed for all feature types.
Set a TSLGMLPrropertyMappingSet instance on the loader using the property Mapping method. Different mappings can be performed for each feature type and not all features types need have a mapping defined.

Parameters

newMappingSet The new mapping set to set. A copy of the object passed will be taken if the object is valid. Null may be passed to clear the current property mapping set.

◆ setTransverseMercatorJHSFormula()

void TSLGMLInstanceDataLoader::setTransverseMercatorJHSFormula ( bool jhs )

If passed true then the Transverse Mercator JHS formula will be used when using processing data in a Transverse Mercator projection.

The setting will be used to create the Coordinate System returned as part of the load method.

The default setting is to use the USGS Snyder formula.

Parameters

jhs	pass true to use the JHS formula, pass false to use the USGS Snyder formula.

◆ swapXandY() [1/2]

bool TSLGMLInstanceDataLoader::swapXandY ( ) const

if the swapXandY flag is true, then GML geometry will be loaded with the X and Y positions swapped around. By default this flag's value is false.

This method queries the value of the flag.

◆ swapXandY() [2/2]

void TSLGMLInstanceDataLoader::swapXandY ( bool value )

if the swapXandY flag is true, then GML geometry will be loaded with the X and Y positions swapped around. By default this flag's value is false.

This method sets the value of the flag.

◆ tmcPerMU() [1/2]

double TSLGMLInstanceDataLoader::tmcPerMU ( ) const

Get the number of TMCs per Map Unit that will be used when importing instance data.

By default, this value will be 50.

◆ tmcPerMU() [2/2]

void TSLGMLInstanceDataLoader::tmcPerMU ( double value )

Set the number of TMCs per Map Unit that will be used when importing instance data.

By default, this value will be 50.

Parameters

value The new value to use.

If new value provided is 0.0 or negative, then the call will be ignored.

◆ unhandledFeatureCallback() [1/2]

const TSLGMLUnhandledFeatureCallback * TSLGMLInstanceDataLoader::unhandledFeatureCallback ( ) const

Get the unhandled feature callback used by the instance data loader.

The callback instance's method will be called whenever the loader encounters a feature that it cannot process. This may occur in the following scenarios:

The feature is an instance of a feature type that the schema loader reported as being unsupported.
The feature type is supported, but this instance contains a GML geometry type that is not supported.
When loading instance data without a schema, a feature instance was encountered that was more complex than SF-0 permits.

When one of these scenarios occurs, a subset of the original instance data containing the feature instance in question is passed to the user. The XML instance data will be fully formatted.

◆ unhandledFeatureCallback() [2/2]

void TSLGMLInstanceDataLoader::unhandledFeatureCallback ( TSLGMLUnhandledFeatureCallback * callback )

Set the unhandled feature callback used by the instance data loader.

The callback instance's method will be called whenever the loader encounters a feature that it cannot process. This may occur in the following scenarios:

The feature is an instance of a feature type that the schema loader reported as being unsupported.
The feature type is supported, but this instance contains a GML geometry type that is not supported.
When loading instance data without a schema, a feature instance was encountered that was more complex than SF-0 permits.

When one of these scenarios occurs, a subset of the original instance data containing the feature instance in question is passed to the user. The XML instance data will be fully formatted.

NOTE: The user retains ownership of the callback instance.

Parameters

callback The new callback to set. Pass null to clear the existing callback.

◆ useDynamicArcForWGS84()

void TSLGMLInstanceDataLoader::useDynamicArcForWGS84 ( bool useDynamicArc )

Controls whether the instance loader should treat EPSG:4326 and CRS:84 coordinate systems as Dynamic Arc.

If true, when loading data in either the EPSG:4326 or CRS:84 coordinate systems the instance loader will use a Dynamic Arc coordinate system when converting the GML to MapLink entities and the returned coordinate system from the coordinateSystem argument of the load() methods will be a Dynamic Arc coordinate system. If false, the instance loader will create and return a WGS84 coordinate system instead.

The default is to use a Dynamic Arc coordinate system to represent EPSG:4326 and CRS:84.

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

◆ TSLGMLInstanceDataLoader()

Member Function Documentation

◆ destroy()

◆ getTransverseMercatorJHSFormula()

◆ load() [1/3]

◆ load() [2/3]

◆ load() [3/3]

◆ loadFromBuffer() [1/3]

◆ loadFromBuffer() [2/3]

◆ loadFromBuffer() [3/3]

◆ mapUnitShiftX() [1/2]

◆ mapUnitShiftX() [2/2]

◆ mapUnitShiftY() [1/2]

◆ mapUnitShiftY() [2/2]

◆ operator new() [1/2]

◆ operator new() [2/2]

◆ propertyMapping() [1/2]

◆ propertyMapping() [2/2]

◆ propertyMappingSet() [1/2]

◆ propertyMappingSet() [2/2]

◆ setTransverseMercatorJHSFormula()

◆ swapXandY() [1/2]

◆ swapXandY() [2/2]

◆ tmcPerMU() [1/2]

◆ tmcPerMU() [2/2]

◆ unhandledFeatureCallback() [1/2]

◆ unhandledFeatureCallback() [2/2]

◆ useDynamicArcForWGS84()