Detailed Description

This component allows the import, export and updating of data to & from the MapLink TMF/TCF seamless tile based format.

Note : this class has a private destructor, to destroy instances of this class call the public function destroy()

Public Member Functions
	TSLSeamlessLayerManager ()

bool	addLayerToMap (const char *renditionFile=NULL)

bool	cacheSize (int size)

int	cacheSize ()

bool	checkpointCurrentArchive (TSLHistoryTimestamp timestamp, TSLHistoryVersion &nextArchiveVersion)

const TSLSeamlessLayerConfig *	configuration () const

bool	destroy ()

void	enablePublishing (bool enabled, const char *directory=0)

bool	entityRefHandler (TSLSLMEntityRefHandler *handler)

TSLSLMEntityRefHandler *	entityRefHandler ()

const TSLSeamlessLayerTileList *	finalise ()

bool	importCompatibleData (TSLStandardDataLayer layer, TSLSLMImportResult results, bool allowRegression=false, TSLSLMEntityStoreHandler *storeHandler=0, bool updateTiles=true)

bool	ingestData (TSLStandardDataLayer layer, bool allowRegression=false, TSLSLMEntityStoreHandler storeHandler=0, bool updateTiles=true, TSLSeamlessLayerEntityChangeCallback entityChangeCallback=NULL, void *arg=NULL)

bool	initialiseExistingLayerForIngest (const char baseDirectory, const char layerName, const char *mapFilename=NULL)

bool	initialiseNewDetailLayer (const TSLSeamlessLayerConfig config, const char mapFilename="")

bool	initialiseNewReplication ()

bool	isLayerLocked () const

bool	lockLayer ()

bool	publish ()

bool	publishAndArchive (const char *archiveDirectory, TSLHistoryTimestamp timestamp, bool maintainCurrentArchiveVersion=false, bool archiveEntityReferences=false)

bool	publishingEnabled () const

bool	removeLayerFromMap (char const layerName, char const mapPath)

bool	replaceLayerInMap (const char *renditionFile=NULL, bool addIfMissing=true)

bool	replicate (const char *destinationDirectory)

int	requiredCacheSize ()

void	requiredCacheSize (int size)

bool	rollback (const char *archiveDirectory)

void	setProgressListener (TSLSLMProgress *listener)

bool	unlockLayer ()

bool	update ()

bool	updateLayerExtent ()

bool	updateLayerExtent (double x, double y)

void *	operator new (size_t size) TSL_NO_THROW

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

Static Public Member Functions
static void	setMapLinkVersion (TSLMapLinkVersion version)

Constructor & Destructor Documentation

◆ TSLSeamlessLayerManager()

TSLSeamlessLayerManager::TSLSeamlessLayerManager ( )

Default Constructor

Member Function Documentation

◆ addLayerToMap()

bool TSLSeamlessLayerManager::addLayerToMap ( const char * renditionFile = NULL )

Adds the current layer being managed by the manager to the map.

Parameters

renditionFile A path to a rendition file. This file will be merged with the current rendition information contained within the map and, where conflicts occur, take precedence over any entries which are already present.

Returns: true on success, false otherwise.

◆ cacheSize() [1/2]

int TSLSeamlessLayerManager::cacheSize ( )

Returns the size, in kilobytes, of the cache used by the Seamless Layer Manager.

◆ cacheSize() [2/2]

bool TSLSeamlessLayerManager::cacheSize ( int size )

Defines the Seamless Layer Manager's cache size in kilobytes. By default this is set to 32MB. Note that the amount of memory used is approximately double the amount specified here.

Parameters

size	cache size in kilobytes.

Returns: true on success, false otherwise.

◆ checkpointCurrentArchive()

bool TSLSeamlessLayerManager::checkpointCurrentArchive	(	TSLHistoryTimestamp	timestamp,
		TSLHistoryVersion &	nextArchiveVersion )

This method updates the timestamp of the current archive version and then increments this version number so that the next archive will be assigned the updated version number.

Parameters

timestamp	the timestamp to attach to the archive.
nextArchiveVersion	the version number that will be assigned to the next archive.

Returns: true if successful, false otherwise - in this case, the value of 'nextArchiveVersion' must be ignored.

◆ configuration()

const TSLSeamlessLayerConfig * TSLSeamlessLayerManager::configuration ( ) const

Returns a pointer to the current configuration.

◆ destroy()

bool TSLSeamlessLayerManager::destroy ( )

deletes the object from memory, call this function instead of using delete

◆ enablePublishing()

void TSLSeamlessLayerManager::enablePublishing	(	bool	enabled,
		const char *	directory = 0 )

Allows the user to set whether or not publishing is enabled.

Parameters

enabled	boolean value indicating enabled (true) or disabled (false).
directory	The (temporary) directory which will hold the layer contents prior to publishing. If the layer is published, the contents of this directory will be transferred to the actual layer directory. This must be specified if enabled is set to 'true'.

◆ entityRefHandler() [1/2]

TSLSLMEntityRefHandler * TSLSeamlessLayerManager::entityRefHandler ( )

Returns a pointer to the entity reference handler which is currently in use.

Note: This reference handler is still owned by the Seamless Layer Manager and should not be deleted by the user.

◆ entityRefHandler() [2/2]

bool TSLSeamlessLayerManager::entityRefHandler ( TSLSLMEntityRefHandler * handler )

Set the entity ref handler for the manager. Returns true if handler set successfully.

Parameters

handler the handler to set

◆ finalise()

const TSLSeamlessLayerTileList * TSLSeamlessLayerManager::finalise ( )

Completes the import or update phase of the SeamlessDataManager to provide a baseline set of tiles with duplicate and deleted entities removed. Until finalise is called the SeamlessDataManager will maintain information on the import or update process. At this stage it is possible that duplicate entities may exist within the dataset and/or deleted entities may not have been removed.

The const TSLSeamlessLayerTileList returned by this method should not be deleted by the user.

none

Returns: a constant pointer to a TSLSeamlessLayerList if successful, null otherwise.

◆ importCompatibleData()

bool TSLSeamlessLayerManager::importCompatibleData	(	TSLStandardDataLayer *	layer,
		TSLSLMImportResult *	results,
		bool	allowRegression = false,
		TSLSLMEntityStoreHandler *	storeHandler = 0,
		bool	updateTiles = true )

The behaviour of this method is similar to that of importData, however it has a few distinct differences.

This method imports all data from the given TSLStandardDataLayer provided that all entities contained within the layer are present in the data store and that the source id of each entity matches the version of the corresponding entity in the data store.

Any entities which conflict will be recorded in the TSLSLMImportResult set and will not be imported.

TOIDs can revert to earlier versions, by setting the allowRegression flag to true. If this is done it is the user's responsibility to ensure that the import data set is correct, and contains only out-of-date TOIDs that are required to facilitate the regression.

Returns the TSLSLMImportResult. If this has a size of zero the import has succeeded.

Parameters

layer	the standard data layer to import data from
results	the TSLSLMImportResult
allowRegression	flag to indicate if TOID version regression is allowed - defaults to false.
storeHandler	An optional entity store handler to allow storage of entities to other persistent stores.
updateTiles	This is only valid if storeHandler is not NULL. If true (default), then the map tiles will be updated.

◆ ingestData()

bool TSLSeamlessLayerManager::ingestData	(	TSLStandardDataLayer *	layer,
		bool	allowRegression = false,
		TSLSLMEntityStoreHandler *	storeHandler = 0,
		bool	updateTiles = true,
		TSLSeamlessLayerEntityChangeCallback	entityChangeCallback = NULL,
		void *	arg = NULL )

Import data from a TSLStandardDataLayer generated from data using the import data functionality in TSLUtilityFunctions. This will then convert it to use the TCF seamless tiles.

TOIDs can revert to earlier versions, by setting the allowRegression flag to true. If this is done it is the user's responsibility to ensure that the import data set is correct, and contains only out-of-date TOIDs that are required to facilitate the regression.

Parameters

layer	the layer with imported data
allowRegression	flag to indicate if TOID version regression is allowed - defaults to false.
storeHandler	An optional entity store handler to allow storage of entities to other persistent stores.
updateTiles	This is only valid if storeHandler is not NULL. If true (default), then the map tiles will be updated.
entityChangeCallback	This callback will be invoked for each entity process by the seamless layer manager during an ingest. See the documentation for TSLSeamlessLayerEntityChangeCallback for more information.
arg	A user-defined argument. This will be passed to the callback.

Returns: true on success, false otherwise.

◆ initialiseExistingLayerForIngest()

bool TSLSeamlessLayerManager::initialiseExistingLayerForIngest	(	const char *	baseDirectory,
		const char *	layerName,
		const char *	mapFilename = NULL )

Prepares the SeamlessLayerManager for import or update of data into the existing seamless detail layer. It loads the necessary information from the base directory where the seamless detail layer (and associated information) is stored.

Parameters

baseDirectory	The location of the base directory where the existing seamless detail layer resides.
layerName	The name of the existing seamless layer to prepare for ingest.
mapFilename	This argument is optional. If set, it specifies the name of the map file that contains the seamless layer to update. This argument should be set if the map file being updated is different to the one originally given to initialseNewDetailLayer when the layer was created, e.g. if the map has been renamed since being created. If the full path to the map to use is passed, only the filename will be used. It is expected that the map file resides within the directory provided in the baseDirectory argument.

Returns: true on success, false otherwise. A failure will occur if the seamless detail layer and it associated information does not exist.

◆ initialiseNewDetailLayer()

bool TSLSeamlessLayerManager::initialiseNewDetailLayer	(	const TSLSeamlessLayerConfig *	config,
		const char *	mapFilename = "" )

Initialises a seamless detail layer in preparation for importing or updating data to the specified layer.

Note: This method should not be used if you wish to create a new seamless layer which has the same name as one present in the map, but with a different configuration file. This is because the manager will use the file present on disk, rather than the one being passed in.

Parameters

config	A pointer to TSLSeamlessLayerConfig containing configuration settings for the grid and filename/path locations . n.b. see Class TSLSeamlessLayerConfig for more details. Note that the user is responsible for deleting this object.
mapFilename	optional map file name. This map file will be updated at the on final production of the detail layer to include new feature mappings and the EntityDataHandler to describe new attributes.

Returns: true on success, false otherwise. A failure will occur if the detail layer already exists and its parameters do not match those provided by TSLSeamlessLayerConfig.

◆ initialiseNewReplication()

bool TSLSeamlessLayerManager::initialiseNewReplication ( )

This method, called after initialiseLayer, prepares the seamless layer manager for a new replication session. It deletes any existing RPL file for the given layer, and resets the manager's replication features.

◆ isLayerLocked()

bool TSLSeamlessLayerManager::isLayerLocked ( ) const

Returns true if the layer is locked.

◆ lockLayer()

bool TSLSeamlessLayerManager::lockLayer ( )

Locks the layer.

Returns true if successful, false otherwise.

◆ operator new() [1/2]

void * TSLSeamlessLayerManager::operator new ( size_t size )

These are here to avoid being documented Allocation redirection for API.

◆ operator new() [2/2]

void * TSLSeamlessLayerManager::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.

◆ publish()

bool TSLSeamlessLayerManager::publish ( )

If publishing is enabled, the seamless layer manager does not directly overwrite existing map data when changes are made, instead storing it in a temporary directory hierarchy. This method provides a means of publishing any updates made by overwriting the existing map data with the contents of the temporary directories.

Returns true if successful, false otherwise.

◆ publishAndArchive()

bool TSLSeamlessLayerManager::publishAndArchive	(	const char *	archiveDirectory,
		TSLHistoryTimestamp	timestamp,
		bool	maintainCurrentArchiveVersion = false,
		bool	archiveEntityReferences = false )

If publishing is enabled, the seamless layer manager does not directly overwrite existing map data when changes are made, instead storing it in a temporary directory hierarchy. This method provides a means of publishing any updates made by overwriting the existing map data with the contents of the temporary directories.

Prior to being overwritten, the existing map data is archived by storing them at the specified location with the provided timestamp. This archiving technique allows a history of changes to be built up which can be useful if data needs to be 'rolled-back' at a later date.

Parameters

archiveDirectory	The directory which is to contain the archived layer files.
timestamp	A timestamp to associate with the archive.
maintainCurrentArchiveVersion	Flag to indicate whether the current archive version number stays the same after this method finishes. If this flag is true, then subsequent archiving will move updated data into the same archive location as the current location. Default value is false.
archiveEntityReferences	Flag to indicate if the map's entity reference (dbref) files that have been updated during an ingest should be archived alongside the updated map data. These files are only necessary if you wish to use the TSLMapDataLayer::findEntityID() method when flashed back to a historical version of the map contained within the archive. Archiving these files can significantly increase both the time taken to perform a publish and the size of the resulting archive, so this flag should only be set to true if the historical files will be needed. The default value is false.

Returns: true if successful, false otherwise.

◆ publishingEnabled()

bool TSLSeamlessLayerManager::publishingEnabled ( ) const

Returns whether or not publishing has been enabled for the manager.

◆ removeLayerFromMap()

bool TSLSeamlessLayerManager::removeLayerFromMap	(	char const *	layerName,
		char const *	mapPath )

Removes the given seamless layer from the given map.

Parameters

layerName	The name of the seamless layer to remove from the map.
mapPath	The path to the map file which the layer should be removed from.

Returns: true on success, false otherwise.

◆ replaceLayerInMap()

bool TSLSeamlessLayerManager::replaceLayerInMap	(	const char *	renditionFile = NULL,
		bool	addIfMissing = true )

Replaces the current layer in the map by the one currently being managed by the manager. If the layer is not in the map, it will be added, if the 'addIfMissing' flag is true.

Parameters

renditionFile	A path to a rendition file. This file will be merged with the current rendition information contained within the map and, where conflicts occur, take precedence over any entries which are already present.
addIfMissing	A boolean flag specifying whether a layer should be added if it is not already present.

Returns: true on success, false otherwise.

◆ replicate()

bool TSLSeamlessLayerManager::replicate ( const char * destinationDirectory )

This method copies all files which have been changed during the session and their associated entity references to the specified location.

Using the replication method allows updates to be identifiable from data which has remained unchanged during a session.

Parameters

destinationDirectory the directory to which updates and changes should be copied.

◆ requiredCacheSize() [1/2]

int TSLSeamlessLayerManager::requiredCacheSize ( )

Returns the minimum required cache size, in kilobytes.

◆ requiredCacheSize() [2/2]

void TSLSeamlessLayerManager::requiredCacheSize ( int size )

Sets the minimum required cache size.

Parameters

size	required cache size in kilobytes

◆ rollback()

bool TSLSeamlessLayerManager::rollback ( const char * archiveDirectory )

This method provides a means of rolling back a map after a publishing and archive call has been made.

The requirements are:

Publishing and archiving must be enabled.
This call can only be made after the publishAndArchive function has been called. If not then there is no reason to use rollback.
The 'archiveEntityReferences' parameter for the publishAndArchive call must be set to true.

This method will:

All tile and reference files in the archive folder will be copied back into the map's seamless layer folder structure, replacing existing files.
All newly added files will be removed.
All version history will be reverted back to previous versions, including the map's main version file.
The archive folder will be deleted.

This method does not:

delete or remove the seamless layer if it was inserted during the seamless layer manager's session.
revert back the feature class list.
delete any empty layer folders. note - it is the responsibility of the calling code to deal with the above situations.

Parameters

archiveDirectory The directory which contains the archived layer files.

Returns: true if successful, false otherwise.

◆ setMapLinkVersion()

static void TSLSeamlessLayerManager::setMapLinkVersion ( TSLMapLinkVersion version )

static

Sets the MapLink output format to use.

Parameters

version The version of MapLink to provide output for.

◆ setProgressListener()

void TSLSeamlessLayerManager::setProgressListener ( TSLSLMProgress * listener )

Attach a progress listener.

Parameters

listener The progress listener.

◆ unlockLayer()

bool TSLSeamlessLayerManager::unlockLayer ( )

Unlocks the layer.

Returns true if successful, false otherwise.

◆ update()

bool TSLSeamlessLayerManager::update ( )

Updates the processing phase of the SeamlessDataManager to provide a baseline set of tiles with duplicate and deleted entities removed. This should be called if the processing is performed in chunks at a time prior to finalisation.

Returns true if successful, false otherwise.

◆ updateLayerExtent() [1/2]

bool TSLSeamlessLayerManager::updateLayerExtent ( )

Updates the layer's extent based on the data it holds.

Returns true if successful, false otherwise.

◆ updateLayerExtent() [2/2]

bool TSLSeamlessLayerManager::updateLayerExtent	(	double	x,
		double	y )

Updates the layer's extent based on the given values.

Parameters

x,y	The top-right corner of the layer.

Returns: true if successful, false otherwise.

Detailed Description

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

◆ TSLSeamlessLayerManager()

Member Function Documentation

◆ addLayerToMap()

◆ cacheSize() [1/2]

◆ cacheSize() [2/2]

◆ checkpointCurrentArchive()

◆ configuration()

◆ destroy()

◆ enablePublishing()

◆ entityRefHandler() [1/2]

◆ entityRefHandler() [2/2]

◆ finalise()

◆ importCompatibleData()

◆ ingestData()

◆ initialiseExistingLayerForIngest()

◆ initialiseNewDetailLayer()

◆ initialiseNewReplication()

◆ isLayerLocked()

◆ lockLayer()

◆ operator new() [1/2]

◆ operator new() [2/2]

◆ publish()

◆ publishAndArchive()

◆ publishingEnabled()

◆ removeLayerFromMap()

◆ replaceLayerInMap()

◆ replicate()

◆ requiredCacheSize() [1/2]

◆ requiredCacheSize() [2/2]

◆ rollback()

◆ setMapLinkVersion()

◆ setProgressListener()

◆ unlockLayer()

◆ update()

◆ updateLayerExtent() [1/2]

◆ updateLayerExtent() [2/2]