Class: TDiskDictionaryOf

Declaration: DiskDictionary.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

Provides a storage mechanism (dictionary) for persistent objects. You give the TDiskDictionaryOf two objects representing the key and value of a dictionary association and TDiskDictionaryOf stores the appropriate information on disk so that the dictionary can be used between different sessions.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TDiskDictionaryOf::TDiskDictionaryOf

TDiskDictionaryOf (const TDirectory & theDirectory, const TText & theDictionaryName, TComparator < AKey > * adoptedComparator, TStreamer < AKey > * adoptedKeyStreamer, TStreamer < AValue > * adoptedValueStreamer)
TDiskDictionaryOf (const TDirectory & theDirectory, const TText & theDictionaryName, EOpenPermissions permissions =kReadWrite)

Interface Category:

API.

Purpose:

Constructor. Creates a new TDiskDictionaryOf, creating and opening the associated disk files.
Constructor. Creates a new TDiskDictionaryOf, opening the associated disk files.

Calling Context:

Called at construction to create and open the associated disk files.
Called at construction to open the associated disk files.

Parameters:

const TDirectory & theDirectory -Specifies the TDirectory in which to locate the theDictionaryName.
const TText & theDictionaryName -Specifies the TText that contains the name of the file to locate in theDirectory.
TComparator < AKey > * adoptedComparator -Specifies an object that can perform comparison operations with the key object.
TStreamer < AKey > * adoptedKeyStreamer -Specifies an object that can perform streaming operations with the key object.
TStreamer < AValue > * adoptedValueStreamer -Specifies an object that can perform streaming operations with the value object.
const TDirectory & theDirectory -Specifies the TDirectory in which to locate the theDictionaryName.
const TText & theDictionaryName -Specifies the TText that contains the name of the file to locate in theDirectory.
EOpenPermissions permissions =kReadWrite -Specifies the TDiskDictionaryOf's opening permission, the default is read/write access.

Return Value:

None.

Exceptions:

Throws TRecordManagerStoreDoesNotExistException::kDoesNotExist if a recordfile could not be found in theDirectory and you were trying to open it. Throws TRecordManagerStoreAlreadyExistsException::kAlreadyExists if a recordfile already existed in theDirectory, when you wanted to create it. Throws TRecordManagerPermissionsException::kWrongPermissions if a recordfile is being accessed with an invalid permission. Throws TStandardRecordManagerException if an internal error occurred. Throws TDiskDictionaryInvalidArgumentsException::kInvalidArguments if bad parameters were used in the constructor. Throws TDiskDictionaryInvalidArgumentsException::kTypeMismatchForKeyOrValue if the open constructor detects a type mismatch for key or value. Throws TStandardDiskDictionaryException if an internal error occurs.

Concurrency:

Not multithread safe.

Other Considerations:

TPersistentStorageException could be caught to catch all of the above exceptions.

Member Function: TDiskDictionaryOf::~TDiskDictionaryOf

~ TDiskDictionaryOf ()

Interface Category:

API.

Purpose:

Destructor. Releases the resources associated with theTDiskDictionaryOf.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions.

Concurrency:

Not multithread safe.

Other Considerations:

Because destructors must NOT throw exceptions, it is possible that files that should have been removed from disk were not removed due to file system exceptions. SetDestroyFileOnDelete must have been called with true in order to delete the associated disk files.

Member Function: TDiskDictionaryOf::Add

bool Add (const AKey & key, const AValue & value, bool replaceExistingValue =false)

Interface Category:

API.

Purpose:

Adds a (key, value) pair of objects to the disk dictionary.

Calling Context:

Called to add an object to the disk dictionary

Parameters:

const AKey & key -Specifies the key object to be added.
const AValue & value -Specifies the value object to be added.
bool replaceExistingValue =false -If the replace flag is false and there is a key that is equal to the passed-in key, then return false. If the replace flag is true and there is a key that is equal to the passed-in key, then replace the value with the passed-in value. If there is no existing record, then add the record regardless of the replace flag. The default is set false.

Return Value:

Returns true if an add/replace operation succeeded, false otherwise.

Exceptions:

Throws TDiskDictionaryPermissionsException::kReadOnly if the TDiskDictionaryOf was instantiated ReadOnly. Throws a derived class of TPersistentStoreInvalidArgumentsException if the parameters are bad. Throws a derived class of TPersistentStorageException if an internal failure occurred.

Concurrency:

Not multithread safe.

Other Considerations:

Difference in sizes between the value object being replaced and the newer one need not be the same.

Member Function: TDiskDictionaryOf::Remove

bool Remove (const AKey & key)

Interface Category:

API.

Purpose:

Removes an object pair from the disk dictionary.

Calling Context:

Called to remove an object pair from the disk dictionary.

Parameters:

const AKey & key -Specifies the key of the object to be removed.

Return Value:

Returns true if the key was actually in the disk dictionary.

Exceptions:

Throws TDiskDictionaryPermissionsException::kReadOnly if the TDiskDictionaryOf was instantiated ReadOnly. Throws a derived class of TPersistentStoreInvalidArgumentsException if the parameter is bad. Throws a derived class of TPersistentStorageException if an internal failure occurred.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDiskDictionaryOf::Member

bool Member (const AKey & key) const

Interface Category:

API.

Purpose:

Checks if a key is in the disk dictionary.

Calling Context:

Called to check if a key is in the disk dictionary.

Parameters:

const AKey & key -Specifies the key to be checked for existence.

Return Value:

Returns true if the specified key exists in the dictionary, otherwise returns false.

Exceptions:

Throws a derived class of TPersistentStorageException if an internal failure occurred.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDiskDictionaryOf::CopyKey

AKey * CopyKey (const AKey & key) const

Interface Category:

API.

Purpose:

Retrieves a key object from the disk dictionary according to the specified key.

Calling Context:

Called to retrieve a key object from the disk dictionary.

Parameters:

const AKey & key -Specifies the key of the record to be retrieved.

Return Value:

Returns the stored key object if the specified key is in the disk dictionary, otherwise returns NIL.

Exceptions:

Throws a derived class of TPersistentStorageException if an internal failure occurred.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDiskDictionaryOf::Copy

AValue * Copy (const AKey & key) const

Interface Category:

API.

Purpose:

Retrieves a value object from the disk dictionary according to the specified key.

Calling Context:

Called to retrieve a value object from the disk dictionary.

Parameters:

const AKey & key -Specifies the key of the record to be retrieved.

Return Value:

Returns the value object associated with this key. NIL is returned if no key or value is found.

Exceptions:

Throws a derived class of TPersistentStorageException if an internal failure occurred.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDiskDictionaryOf::Count

unsigned long Count ()

Interface Category:

API.

Purpose:

Obtains the number of records that are in the disk dictionary.

Calling Context:

Called to get the number of records that are stored in the disk dictionary.

Parameters:

Takes no parameters.

Return Value:

Returns the number of records that are in the disk dictionary.

Exceptions:

Throws a derived class of TPersistentStorageException if an internal failure occurred.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDiskDictionaryOf::SetDestroyFileOnDelete

void SetDestroyFileOnDelete (bool doIt =false)

Interface Category:

API.

Purpose:

Specifies if the TDiskDictionaryOf should remove all associated disk files and stored objects after destructor terminates.

Calling Context:

Called to tell the TDiskDictionaryOf should remove all associated disk files and stored objects after destructor terminates.

Parameters:

bool doIt =false -If the doIt flag is set true, all associated disk files are removed. The default is set to false.

Return Value:

None.

Exceptions:

Throws no exceptions.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.