TSLSLMEntityRefHandler Class Reference

Inheritance diagram for TSLSLMEntityRefHandler:

Detailed Description

An EntityRefHandler stores references for the entities in a particular layer.

An EntityRefHandler is layer specific - that is, there is one EntityRefHandler per layer, and querying for entities will only return successfully if those entities are in the given layer.

Copying and assignment are prohibited.

Public Member Functions
TSLSLMEntityRef *	addEntityRef (const TSLEntity *entity)
void	clearEntityRefFoundStatus ()
TSLSeamlessLayerConfig *	config ()
void	destroy ()
TSLSLMEntityRef *	getEntityRef (const TSLEntityID &entityID)
TSLSLMEntityRef *	getEntityRef (const TSLEntity *entity)
bool	getOrphanEntityRefs (TSLSLMEntityRef ***references, int &number)
const char *	layerName () const
const TSLSeamlessLayerManager *	manager () const
bool	removeEntityRef (const TSLEntityID &entityID)
TSLSLMEntityRefHandlerType	type ()
bool	updateEntityRef (TSLSLMEntityRef *entityRef)
TSLSLMEntityRefValidationEnum	validateEntityRef (TSLEntityID entityID, TSLVersion version)
bool	validateEntityRefsFromFiles (const TSLSLMEntityRef **references, int referenceCount, const TSLSimpleString &path, TSLSLMEntityRef **&failures, int &failuresCount)
void	cacheSize (long size)

Protected Member Functions
	TSLSLMEntityRefHandler ()
	~TSLSLMEntityRefHandler ()

Constructor & Destructor Documentation

TSLSLMEntityRefHandler()

TSLSLMEntityRefHandler::TSLSLMEntityRefHandler ( )

inlineprotected

Protected constructor to prevent user instantiation of abstract base class.

~TSLSLMEntityRefHandler()

TSLSLMEntityRefHandler::~TSLSLMEntityRefHandler ( )

inlineprotected

Protected destructor to stop being instantiated on the stack. Forces user to use new operator and destroy method.

Member Function Documentation

addEntityRef()

TSLSLMEntityRef * TSLSLMEntityRefHandler::addEntityRef

(

const TSLEntity *

entity

)

Given an entity, adds a reference to that entity to the entity reference 'database'.

Parameters

entity

A pointer to the entity.

Returns

the added reference if it was successfully added. It will not be added if it already exists.

cacheSize()

void TSLSLMEntityRefHandler::cacheSize

(

long

size

)

Set a new cache size.

Parameters

size	cache size.

clearEntityRefFoundStatus()

void TSLSLMEntityRefHandler::clearEntityRefFoundStatus

(

)

Clears the 'found' status of all TSLSLMEntityRef objects in this seamless layer.

config()

TSLSeamlessLayerConfig * TSLSLMEntityRefHandler::config

(

)

Returns the associated seamless layer configuration.

destroy()

void TSLSLMEntityRefHandler::destroy

(

)

Deletes the object.

getEntityRef() [1/2]

TSLSLMEntityRef * TSLSLMEntityRefHandler::getEntityRef

(

const TSLEntity *

entity

)

Query method for the entity reference of an entity.

Parameters

entity

A pointer to the entity.

Returns

the SLMEntityReference for the associated entity if one exists within the entity reference 'database'.

The caller assumes ownership of the returned entity reference object.

getEntityRef() [2/2]

TSLSLMEntityRef * TSLSLMEntityRefHandler::getEntityRef

(

const TSLEntityID &

entityID

)

Query method for the entity reference of an entity given its ID.

Parameters

entityID

The ID of the entity.

Returns

the SLMEntityReference for the associated entity if one exists within the entity reference 'database'.

The caller assumes ownership of the returned entity reference object.

getOrphanEntityRefs()

bool TSLSLMEntityRefHandler::getOrphanEntityRefs	(	TSLSLMEntityRef ***	references,
		int &	number )

This method returns a list of all entity references that do not have the 'found' status flag set. It is used to identify entities that should not be present in a map after an update.

Parameters

references	This will be set to an array of pointers to any TSLSLMEntityRef objects in the map that do not have the 'found' flag set. Note that these objects are owned by the reference handler and should not be deleted.
number	The size of the array returned.

Returns

true on success, or false if an error was encountered. Calling this method more than once will invalidate the previous list returned.

layerName()

const char * TSLSLMEntityRefHandler::layerName

(

)

const

Returns the name of the associated layer. If this does not exist, returns 0.

manager()

const TSLSeamlessLayerManager * TSLSLMEntityRefHandler::manager

(

)

const

Returns the associated seamless layer manager.

removeEntityRef()

bool TSLSLMEntityRefHandler::removeEntityRef

(

const TSLEntityID &

entityID

)

Given an entity ID, removes the corresponding entity from the entity reference 'database'.

Parameters

entityID

The ID of the entity.

Returns

true if successful, false otherwise.

type()

TSLSLMEntityRefHandlerType TSLSLMEntityRefHandler::type

(

)

Returns the type of TSLSLMEntityRefHandler.

updateEntityRef()

bool TSLSLMEntityRefHandler::updateEntityRef

(

TSLSLMEntityRef *

entityRef

)

Instructs the handler to update its internal value of the entity reference based on the supplied value.

Parameters

entityRef

The new entity reference.

Returns

true if successful, false otherwise.

validateEntityRef()

TSLSLMEntityRefValidationEnum TSLSLMEntityRefHandler::validateEntityRef	(	TSLEntityID	entityID,
		TSLVersion	version )

This method compares the last imported version of the entity specified by the given entity ID in the map against the provided version number. It is used to validate that updates to a map have been correctly processed.

Parameters

entityID	The ID of the entity to validate.
version	The last imported version that the entity should have.

Returns

a TSLSLMEntityRefValidationEnum corresponding to the result of the validation process. See the documentation for this enum for the possible values.

Should the return value from this method be TSLSLMEntityRefValidationValid, then the entity reference will have its found flag set to true.

validateEntityRefsFromFiles()

bool TSLSLMEntityRefHandler::validateEntityRefsFromFiles	(	const TSLSLMEntityRef **	references,
		int	referenceCount,
		const TSLSimpleString &	path,
		TSLSLMEntityRef **&	failures,
		int &	failuresCount )

Given a list of entity IDs and version numbers and a directory containing TMF files, this method will scan each of the files in the given directory for each entity ID and compare the versions of the entity in the file against the version passed in. It returns a list of entity IDs that are are present in the list passed in and either not present in any of the files, or have differing version numbers.

This method can be used to check entity IDs that failed validation via validateEntityRef() or getOrphanEntityRefs() against an external data source in case the map has not been updated with all pending changes.

Parameters

references	An array of TSLSLMEntityRef objects that describe the entities to check.
referenceCount	The size of the references array.
path	Path to the directory containing TMF files to use.
failures	This will be set to an array of TSLSLMEntityRef objects that failed the validation rules.
failuresCount	The size of the failures array.

Returns

true on success, or false on failure. Calling this method again will invalidate the previous list returned.