pegasus/src/Pegasus/Repository/InstanceIndexFile.h - diff

Return to InstanceIndexFile.h CVS log

Up to [Pegasus] / pegasus / src / Pegasus / Repository

Diff for /pegasus/src/Pegasus/Repository/InstanceIndexFile.h between version 1.10 and 1.11

version 1.10, 2001/12/13 14:54:27

version 1.11, 2002/03/19 22:56:01

Line 22

// Author: Mike Brasher (mbrasher@bmc.com)

// Modified By:

// Modified By: Jenny Yu, Hewlett-Packard Company (jenny_yu@hp.com)

// Jenny Yu, Hewlett-Packard Company (jenny_yu@hp.com)

// Modified By: Michael Brasher (mbrasher@bmc.com)

//%/////////////////////////////////////////////////////////////////////////////

Line 37

PEGASUS_NAMESPACE_BEGIN

/** This class manages access to an 'instance index file' which maps

/** This class manages access to an "instance index file" which maps

instance names to the index (or location) of the instances in an

instance names to offsets of the instances contained in the "instance

'instance file'. Lines of this file have the following form:

data file".

The first line of this file is a free count, expressed as eight hex

digits followed by a newline. The free count indicates how many instances

are free (but not reclaimed). When instances are deleted or modified, the

corresponding entry in this index file is marked as free (by changing the

first column of the entry from '0' to '1'). When the free count reaches

some upper bound, reclamation is performed which involves removing free

entries (from both the index file and the data file).

All subsequent lines contain an entry with the following form:

<pre>

<hash-code> <index> <size> ClassName.key1=value1,...,keyN=valueN

<free> <hash-code> <index> <size> ClassName.key1=val1,...,keyN=valN

</pre>

Where the hash-code is an eight digit hex number, the index is the byte

The free column is a flag (either '0' or '1') which indicates whether

the entry is no longer used (in which case it can be removed during

reclamation).

The hash-code is an eight digit hex number, the index is the byte

location of the instance record in the instance file, the size is the

record size of the instance record, and instance name is a CIM style

object name.

Here's an example:

Here's an example of an index file:

<pre>

A6B275A9 0 1425 Employee.ssn=444332222

A6BA08BE 1425 1430 Employee.ssn=555667777

</pre>

Each instance in Pegasus is represented as a record in the instance

file for the CIM class. Each instance record contains the CIM/XML

encoding of the instance. Information about each instance record in

an instance file is kept in an instance index file. The name of

an instance index file has the following form:

<pre>

ClassName.idx

00000001

0 A6B275A9 0 1425 Employee.ssn=444332222

1 A6BA08B1 1425 1430 Employee.ssn=555667777

</pre>

Here's an example:

To lookup an entry in the index file, first take the hash code of the

target key. Then find the first non-free entry whose hash code and key

<pre>

are the same as the target hash code and key. Note that an entry may

Employee.idx

usually be ruled out by comparing the hash codes (except in the case of

</pre>

clashes).

An instance can be obtained from an instance name by searching all entries

in the instance index file with the same hash code (to account for hash

clashes), comparing the instance names, and obtaining the index and size

of the instance record in the corresponding instance file.

Methods are provided for managing the instance index file: adding,

removing, and modifying.

It is very important to keep both the instance and index file in a

consistent state. In order to minimize the window in which the

instance and index file can be left in an inconsistent state (after

an unexpected system termination or failure), all updates to the

instance and index files are done first to the temporary files. After

an update operation is successful on BOTH the instance and index files,

the temporary files are renamed back to the original files.

class PEGASUS_REPOSITORY_LINKAGE InstanceIndexFile

{

public:

Line 102

Line 92

@param path the file path of the instance index file

@param instanceName the name of the instance

@param sizeOut the size of the instance record found

@param indexOut the index of the instance record found

@param sizeOut the size of the instance record found

@return true if the instance is found

@return true if the instance is found; false otherwise.

false if the instance cannot be found

static Boolean lookup(

static Boolean lookupEntry(

const String& path,

const CIMReference& instanceName,

Uint32& sizeOut,

Uint32& indexOut,

Uint32& indexOut);

Uint32& sizeOut);

/** Inserts a new entry into the instance index file. Saves the index and

/** Creates a new entry in the instance index file. Saves the index and

size of the instance record passed in. This method assumes that the

keys in the instance name are in sorted order. This must be done

prior to calling the method. Returns true on success.

@param path the file path of the instance index file

@param instanceName the name of the instance

@param sizeIn the size of the new instance record

@param indexIn the index of the new instance record

@param sizeIn the size of the new instance record

@return true if successful

@return true if successful; false otherwise.

false if an error occurs in inserting the entry

static Boolean insert(

static Boolean createEntry(

const String& path,

const CIMReference& instanceName,

Uint32 sizeIn,

Uint32 indexIn,

Uint32 indexIn);

Uint32 sizeIn);

/** Removes the entry with the given instance name. Returns true on

success.

@param path the file path of the instance index file

/** Deletes the entry with the given instance name.

@param instanceName the name of the instance

@param path path of the instance index file

@param instanceName name of the instance

@return true if successful

@return true on success

false if an error occurs in removing the entry

static Boolean remove(

static Boolean deleteEntry(

const String& path,

const CIMReference& instanceName);

const CIMReference& instanceName,

Uint32& freeCount);

/** Modifies an entry by first removing the old entry and then inserting

a new entry at the end of the file. Returns true on success.

a new entry at the end of the file.

@param path the file path of the instance index file

@param instanceName the name of the instance

@param sizeIn the size of the modified instance record

@param indexIn the index of the modified instance record

@return true if successful

@param path the file path of the instance index file.

false if an error occurs in modifying the entry

@param instanceName the name of the instance.

@param indexIn the index of the modified instance record.

@param sizeIn the size of the modified instance record.

@return true on success.

static Boolean modify(

static Boolean modifyEntry(

const String& path,

const CIMReference& instanceName,

Uint32 indexIn,

Uint32 sizeIn,

Uint32 indexIn);

Uint32& freeCount);

/** Gets the information stored in the index file for all the instances

of the given class. Appends the instance names, indices and sizes

to the given arrays (does not clear the arrays first). Returns

true on success.

@param path the file path of the instance index file

@param path path of the instance index file.

@param instanceNames an array to hold the instance names

@param instanceNames array to hold the instance names.

@param indices an array to hold the indices of the instance

@param indices array to hold the indices of the instance records.

records

@param sizes an array to hold the sizes of the instance records.

@param sizes an array to hold the sizes of the instance

@return true on success.

records

@return true if successful

false if an error occurs in loading information from

the instance index file

static Boolean appendInstanceNamesTo(

static Boolean enumerateEntries(

const String& path,

Array<CIMReference>& instanceNames,

Array<Uint32>& freeFlags,

Array<Uint32>& indices,

Array<Uint32>& sizes);

Array<Uint32>& sizes,

Array<CIMReference>& instanceNames,

Boolean includeFreeEntries);

private:

/** Returns true if this index file has any non-free entries:

static Boolean hasNonFreeEntries(const String& path);

/** Appends a new entry to the temporary index file. Returns true

/** Begin a transaction to modify this file. The effect of subsequent

on success.

modifications can be rolled back by calling rollbackTransaction().

The current implementation simply copies the index file to a a file

with the same name but with ".rollback" appended to it.

static Boolean beginTransaction(const String& path);

@param os the ofstream of the temporary index file

/** Roll back any changes to the file since the last time

@param instanceName the name of the instance

beginTransaction() was called. The current implementation deletes

@param sizeIn the size of the new instance record

the current file and renames the rollback file to the same name.

@param indexIn the index of the new instance record

static Boolean rollbackTransaction(const String& path);

@return true if successful

/** Commit changes made after beginTransaction() was called. The curent

false if an error occurs in appending the entry

implementation simply removes the .rollback file.

static void _appendEntry(

static Boolean commitTransaction(const String& path);

PEGASUS_STD(ofstream)& os,

const CIMReference& instanceName,

Uint32 sizeIn,

Uint32 indexIn);

/** Removes an entry from the temporary instance index file. Returns

/** Compact the file by removing entries which are marked as free.

true on success.

static Boolean compact(

const String& path);

@param os the ofstream of the temporary index file

private:

@param path the file path of the original instance index file

@param instanceName the name of the instance

@return true if successful

/** Open the index file and position the file pointer on the first

false if an error occurs in removing the entry

entry (immediately after the free count). Create the file if it

does not exist (writing a free count of zero).

static Boolean _removeEntry(

static Boolean _openFile(

PEGASUS_STD(ofstream)& os,

const String& path,

PEGASUS_STD(fstream)& fs);

/** Appends a new entry to the index file; called by both createEntry()

and modifyEntry().

static Boolean _appendEntry(

PEGASUS_STD(fstream)& fs,

const CIMReference& instanceName,

Uint32 indexIn,

Uint32 sizeIn);

/** Increment the index file's free count; called by _markEntryFree().

The resulting value is left in the freeCount parameter.

static Boolean _incrementFreeCount(

PEGASUS_STD(fstream)& fs,

Uint32& freeCount);

/** Marks the entry matching the given instanceName as free; called by both

deleteEntry() and modifyEntry().

static Boolean _markEntryFree(

PEGASUS_STD(fstream)& fs,

const CIMReference& instanceName);

/** Helper method for lookupEntry() which takes a file stream rather than

a path.

static Boolean _lookupEntry(

PEGASUS_STD(fstream)& fs,

const CIMReference& instanceName,

Uint32& indexOut,

Uint32& sizeOut,

Uint32& entryOffset);

};

PEGASUS_NAMESPACE_END

Legend:

Removed from v.1.10
changed lines
	Added in v.1.11

No CVS admin address has been configured