Class: TRecordManagerOf

Declaration: DiskDictionary.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

Represents a managed collection of objects that have been prepared for persistent storage. You give the TRecordManagerOf an object and it finds space in the file and returns a RecordHandle. Objects are retrieved from the TRecordManagerOf by presenting the appropriate RecordHandle. The client of TRecordManagerOf is expected to handle the access mechanisms to associate a name or other object with the RecordHandle, for example, a hash table could associate a name with a record handle and the TRecordManagerOf could then be used to obtain the actual record. TRecordManager is not part of a framework. It is a library.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

Client must provide their own indexing mechanism to associate with the RecordHandle returned from the Add member function. Only Homogenous values are allowed.

Member Function: TRecordManagerOf::TRecordManagerOf

TRecordManagerOf (const TDirectory & theDirectory, const TText & recordfile, ERecordCreation create =kCreateOrOpen, unsigned long blockSize =kRecordManagerBlockSize)

Interface Category:

API.

Purpose:

Constructor. Creates a new TRecordManagerOf object, and the disk files associated with the TRecordManagerOf will be opened at this time.

Calling Context:

Called at construction.

Parameters:

const TDirectory & theDirectory -Specifies the TDirectory in which to locate the recordfile for opening or creating.
const TText & recordfile -Specifies the TText that contains the name of the file to locate in theDirectory
ERecordCreation create =kCreateOrOpen -Specifies the Record Manager's opening behavior. kCreateOrOpen is the default behavior.
unsigned long blockSize =kRecordManagerBlockSize -The default block size.

Return Value:

None.

Exceptions:

Throws TStandardRecordManagerException if an internal error occurs. Throws TRecordManagerStoreDoesNotExistException if a recordfile could not be found in theDirectory and the client specified open behavior. Throws TRecordManagerStoreAlreadyExistsException 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. The files access permissions did not match the create parameter passed by client.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordManagerOf::~TRecordManagerOf

virtual ~ TRecordManagerOf ()

Interface Category:

API.

Purpose:

Destructor. Releases the resources associated with the Record Manager.

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: TRecordManagerOf::DidExistAlready

bool DidExistAlready () const

Interface Category:

API.

Purpose:

Checks if the RecordManagerOf file was previously created.

Calling Context:

Called to check if the Record Manager file was previously created.

Parameters:

Takes no parameters.

Return Value:

Returns true if the Record Manager was previously created.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordManagerOf::Add

RecordHandle Add (const AType & aRecord, TStreamer < AType > * theStreamer)

Interface Category:

API.

Purpose:

Adds an object into the record file.

Calling Context:

Called to add an object into the record file.

Parameters:

const AType & aRecord -Specifies the object to be added to the record file.
TStreamer < AType > * theStreamer -Specifies the streamer, which has enough information about an object in order to stream it to disk.

Return Value:

Returns the RecordHandle to the object just added.

Exceptions:

Throws TRecordManagerInvalidArgumentsException::kInvalidArguments if theStreamer is NIL. Throws TRecordManagerPermissionsException::kReadOnly if the RecordManagerOf was instantiated ReadOnly. Throws TStandardRecordManagerException::kInternalAddFailure if an internal failure occurred.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordManagerOf::Retrieve

AType * Retrieve (RecordHandle where, TStreamer < AType > * theStreamer)
void Retrieve (RecordHandle where, TStream & stream)

Interface Category:

API.

Purpose:

Retrieves the value object based on the passed-in RecordHandle. Fills stream with data from disk associated with RecordHandle passed.

Calling Context:

Called to retrieve the value object based on the passed-in RecordHandle. Called to retrieve the data into a passed in stream based on the passed-in RecordHandle.

Parameters:

RecordHandle where -Specifies the record handle of the value object to be retrieved.
TStreamer < AType > * theStreamer -Specifies the streamer, which has enough information about an object in order to stream it from disk.
RecordHandle where -Specifies the record handle of the value object to be retrieved
TStream & stream -Specifies the stream in which to receive the data from disk.

Return Value:

Returns the value object.

Exceptions:

Throws TRecordManagerInvalidArgumentsException::kInvalidArguments if theStreamer is NIL, or the where parameter is a value smaller than the first record boundary. Throws TStandardRecordManagerException::kCouldNotRetrieve if object could not be streamed in.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordManagerOf::Replace

RecordHandle Replace (RecordHandle oldLocation, const AType & aRecord, TStreamer < AType > * theStreamer)

Interface Category:

API.

Purpose:

Replaces the old value object with the new passed-in object.

Calling Context:

Called to replace the old value object with the new passed-in object.

Parameters:

RecordHandle oldLocation -Specifies the RecordHandle to the old value object.
const AType & aRecord -Specifies the new value object to replace the old one.
TStreamer < AType > * theStreamer -Specifies the streamer, which has enough information about an object in order to stream it to disk.

Return Value:

Returns a new RecordHandle to the object just being added.

Exceptions:

Throws TRecordManagerPermissionsException::kReadOnly if the RecordManagerOf was instantiated ReadOnly. Throws TRecordManagerInvalidArgumentsException::kInvalidArguments if theStreamer is NIL. Throws TStandardRecordManagerException::kInternalAddFailure if an internal failure occurred.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordManagerOf::SetDestroyFileOnDelete

void SetDestroyFileOnDelete (bool doIt =false)

Interface Category:

API.

Purpose:

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

Calling Context:

Called to tell if the Record Manager should remove all associated disk files and stored value objects when its destructor is called.

Parameters:

bool doIt =false -If the doIt flag is set true, the Record Manager removes all stored value objects when the destructor is called; otherwise it does not. The default is set to false.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Calling this member function with doIt =false, is the same as not calling it at all (only if doIt was never set to true).

Member Function: TRecordManagerOf::Remove

void Remove (RecordHandle where)

Interface Category:

API.

Purpose:

Removes the value object located by the passed-in RecordHandle.

Calling Context:

Called to remove the value object located by the passed-in RecordHandle.

Parameters:

RecordHandle where -Specifies the RecordHandle to the object to be removed.

Return Value:

None.

Exceptions:

Throws TRecordManagerPermissionsException::kReadOnly if the RecordManagerOf was instantiated ReadOnly. Throws TRecordManagerInvalidArgumentsException::kInvalidArguments if the RecordHandle is less than the smallest possible RecordHandle. Throws TStandardRecordManagerException::kInternalReadFailure if an internal failure occurred.

Concurrency:

Not multithread safe.

Other Considerations:

None.

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