1 mike  1.9 //%/////////////////////////////////////////////////////////////////////////////
  2           //

  3 kumpf 1.14 // Copyright (c) 2000, 2001, 2002 BMC Software, Hewlett-Packard Company, IBM,
  4            // The Open Group, Tivoli Systems

  5 mike  1.9  //
  6            // Permission is hereby granted, free of charge, to any person obtaining a copy

  7 kumpf 1.14 // of this software and associated documentation files (the "Software"), to
  8            // deal in the Software without restriction, including without limitation the
  9            // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or

 10 mike  1.9  // sell copies of the Software, and to permit persons to whom the Software is
 11            // furnished to do so, subject to the following conditions:
 12            // 

 13 kumpf 1.14 // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN

 14 mike  1.9  // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
 15            // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT

 16 kumpf 1.14 // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 17            // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 18            // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN

 19 mike  1.9  // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 20            // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 21            //
 22            //==============================================================================
 23            //
 24            // Author: Mike Brasher (mbrasher@bmc.com)
 25            //

 26 mike  1.11 // Modified By: Jenny Yu, Hewlett-Packard Company (jenny_yu@hp.com)
 27            // Modified By: Michael Brasher (mbrasher@bmc.com)

 28 mike  1.9  //
 29            //%/////////////////////////////////////////////////////////////////////////////
 30            
 31            #ifndef Pegasus_InstanceIndexFile_h
 32            #define Pegasus_InstanceIndexFile_h
 33            
 34            #include <Pegasus/Common/Config.h>
 35            #include <Pegasus/Common/String.h>

 36 kumpf 1.16 #include <Pegasus/Common/InternalException.h>

 37 kumpf 1.13 #include <Pegasus/Common/CIMObjectPath.h>

 38 kumpf 1.15 #include <Pegasus/Repository/Linkage.h>

 39 mike  1.9  
 40            PEGASUS_NAMESPACE_BEGIN
 41            

 42 mike  1.11 /** This class manages access to an "instance index file" which maps
 43                instance names to offsets of the instances contained in the "instance 
 44                data file". 
 45            
 46                The first line of this file is a free count, expressed as eight hex 
 47                digits followed by a newline. The free count indicates how many instances 
 48                are free (but not reclaimed). When instances are deleted or modified, the 
 49                corresponding entry in this index file is marked as free (by changing the
 50                first column of the entry from '0' to '1'). When the free count reaches 
 51                some upper bound, reclamation is performed which involves removing free
 52                entries (from both the index file and the data file).
 53            
 54                All subsequent lines contain an entry with the following form:

 55 mike  1.10   

 56 mike  1.9      <pre>

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

 58 mike  1.9      </pre>
 59            

 60 mike  1.11     The free column is a flag (either '0' or '1') which indicates whether
 61                the entry is no longer used (in which case it can be removed during
 62                reclamation).
 63            
 64                The hash-code is an eight digit hex number, the index is the byte

 65 mike  1.10     location of the instance record in the instance file, the size is the
 66                record size of the instance record, and instance name is a CIM style
 67                object name.
 68            

 69 mike  1.11     Here's an example of an index file:

 70 mike  1.9  
 71                <pre>

 72 mike  1.11 	00000001
 73            	0 A6B275A9 0 1425 Employee.ssn=444332222 
 74            	1 A6BA08B1 1425 1430 Employee.ssn=555667777 

 75 mike  1.9      </pre>
 76            

 77 mike  1.11     To lookup an entry in the index file, first take the hash code of the
 78                target key. Then find the first non-free entry whose hash code and key
 79                are the same as the target hash code and key. Note that an entry may
 80                usually be ruled out by comparing the hash codes (except in the case of
 81                clashes).
 82                

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

 84 mike  1.10     removing, and modifying.

 85 mike  1.9  */
 86            class PEGASUS_REPOSITORY_LINKAGE InstanceIndexFile
 87            {
 88            public:
 89                

 90 mike  1.10     /** Searches the instance index file for the given instance name. Sets 
 91                    the index parameter to the corresponding index, and sets the size
 92                    parameter to the corresponding instance record size.  Returns true
 93                    on success.
 94            

 95 mike  1.11         @param path the file path of the instance index file
 96                    @param instanceName the name of the instance
 97                    @param indexOut the index of the instance record found
 98                    @param sizeOut the size of the instance record found
 99                    @return true if the instance is found; false otherwise.

100 mike  1.9      */

101 mike  1.11     static Boolean lookupEntry(

102 mike  1.9  	const String& path, 

103 kumpf 1.13 	const CIMObjectPath& instanceName,

104 mike  1.11 	Uint32& indexOut,
105            	Uint32& sizeOut);

106 mike  1.9  

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

108 mike  1.10         size of the instance record passed in.  This method assumes that the
109            	keys in the instance name are in sorted order. This must be done
110                    prior to calling the method.  Returns true on success.
111            

112 mike  1.11         @param path the file path of the instance index file
113                    @param instanceName the name of the instance
114                    @param indexIn the index of the new instance record
115                    @param sizeIn the size of the new instance record 
116                    @return true if successful; false otherwise.

117 mike  1.9      */

118 mike  1.11     static Boolean createEntry(

119 mike  1.9  	const String& path, 

120 kumpf 1.13 	const CIMObjectPath& instanceName,

121 mike  1.11 	Uint32 indexIn,
122                    Uint32 sizeIn);

123 mike  1.10 

124 mike  1.11     /** Deletes the entry with the given instance name.
125                    @param path path of the instance index file
126                    @param instanceName name of the instance
127                    @return true on success

128 mike  1.9      */

129 mike  1.11     static Boolean deleteEntry(

130 mike  1.9  	const String& path, 

131 kumpf 1.13 	const CIMObjectPath& instanceName,

132 mike  1.11 	Uint32& freeCount);

133 mike  1.9  

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

135 mike  1.11         a new entry at the end of the file.

136 mike  1.10 

137 mike  1.11         @param path the file path of the instance index file.
138                    @param instanceName the name of the instance.
139                    @param indexIn the index of the modified instance record.
140                    @param sizeIn the size of the modified instance record.
141                    @return true on success.

142 mike  1.10     */

143 mike  1.11     static Boolean modifyEntry(

144 mike  1.10 	const String& path, 

145 kumpf 1.13 	const CIMObjectPath& instanceName,

146 mike  1.11 	Uint32 indexIn,

147 mike  1.10         Uint32 sizeIn,

148 mike  1.11 	Uint32& freeCount);

149 mike  1.10 
150                /** Gets the information stored in the index file for all the instances
151                    of the given class.  Appends the instance names, indices and sizes 
152                    to the given arrays (does not clear the arrays first).  Returns
153                    true on success.
154            

155 mike  1.11         @param path path of the instance index file.
156                    @param instanceNames array to hold the instance names.
157                    @param indices array to hold the indices of the instance records.
158                    @param sizes an array to hold the sizes of the instance records.
159                    @return true on success.

160 mike  1.9      */

161 mike  1.11     static Boolean enumerateEntries(

162 mike  1.9  	const String& path,

163 mike  1.11 	Array<Uint32>& freeFlags,
164            	Array<Uint32>& indices,
165                    Array<Uint32>& sizes,

166 kumpf 1.13 	Array<CIMObjectPath>& instanceNames,

167 mike  1.11 	Boolean includeFreeEntries);
168            

169 kumpf 1.12 

170 mike  1.11     /** Returns true if this index file has any non-free entries:
171                */
172                static Boolean hasNonFreeEntries(const String& path);
173            
174                /** Begin a transaction to modify this file. The effect of subsequent
175            	modifications can be rolled back by calling rollbackTransaction().
176            	The current implementation simply copies the index file to a a file
177            	with the same name but with ".rollback" appended to it.
178                */
179                static Boolean beginTransaction(const String& path);
180            
181                /** Roll back any changes to the file since the last time 
182                    beginTransaction() was called. The current implementation deletes
183            	the current file and renames the rollback file to the same name.
184                */
185                static Boolean rollbackTransaction(const String& path);
186            
187                /** Commit changes made after beginTransaction() was called. The curent
188            	implementation simply removes the .rollback file.
189                */
190                static Boolean commitTransaction(const String& path);
191 mike  1.11 
192                /** Compact the file by removing entries which are marked as free.
193                */
194                static Boolean compact(
195                    const String& path);

196 mike  1.10 
197            private:

198 mike  1.11 
199                /** Open the index file and position the file pointer on the first
200            	entry (immediately after the free count). Create the file if it

201 kumpf 1.12 	does not exist and if the create flag is true (writing a free 
202                    count of zero).

203 mike  1.11     */
204                static Boolean _openFile(
205            	const String& path, 

206 kumpf 1.12         PEGASUS_STD(fstream)& fs,
207                    Boolean create = false);

208 mike  1.10     

209 mike  1.11     /** Appends a new entry to the index file; called by both createEntry()
210                    and modifyEntry().

211 mike  1.10     */

212 mike  1.11     static Boolean _appendEntry(
213                    PEGASUS_STD(fstream)& fs,

214 kumpf 1.13         const CIMObjectPath& instanceName,

215 mike  1.11         Uint32 indexIn,
216                    Uint32 sizeIn);

217 mike  1.10     

218 mike  1.11     /** Increment the index file's free count; called by _markEntryFree().
219            	The resulting value is left in the freeCount parameter.
220                */
221                static Boolean _incrementFreeCount(
222            	PEGASUS_STD(fstream)& fs,
223            	Uint32& freeCount);

224 mike  1.10 

225 mike  1.11     /** Marks the entry matching the given instanceName as free; called by both
226            	deleteEntry() and modifyEntry().
227                */
228                static Boolean _markEntryFree(
229                    PEGASUS_STD(fstream)& fs,

230 kumpf 1.13         const CIMObjectPath& instanceName);

231 mike  1.11 
232                /** Helper method for lookupEntry() which takes a file stream rather than
233            	a path.
234                */
235                static Boolean _lookupEntry(
236            	PEGASUS_STD(fstream)& fs,

237 kumpf 1.13 	const CIMObjectPath& instanceName,

238 mike  1.11 	Uint32& indexOut,
239            	Uint32& sizeOut,
240            	Uint32& entryOffset);

241 mike  1.9  };
242            
243            PEGASUS_NAMESPACE_END
244            
245            #endif /* Pegasus_InstanceIndexFile_h */