1 karl  1.21 //%2006////////////////////////////////////////////////////////////////////////

  2 mike  1.9  //

  3 karl  1.19 // Copyright (c) 2000, 2001, 2002 BMC Software; Hewlett-Packard Development
  4            // Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems.
  5            // Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L.P.;

  6 karl  1.18 // IBM Corp.; EMC Corporation, The Open Group.

  7 karl  1.19 // Copyright (c) 2004 BMC Software; Hewlett-Packard Development Company, L.P.;
  8            // IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.

  9 karl  1.20 // Copyright (c) 2005 Hewlett-Packard Development Company, L.P.; IBM Corp.;
 10            // EMC Corporation; VERITAS Software Corporation; The Open Group.

 11 karl  1.21 // Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
 12            // EMC Corporation; Symantec Corporation; The Open Group.

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

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

 18 mike  1.9  // sell copies of the Software, and to permit persons to whom the Software is
 19            // furnished to do so, subject to the following conditions:
 20            // 

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

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

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

 27 mike  1.9  // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 28            // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 29            //
 30            //==============================================================================
 31            //
 32            // Author: Mike Brasher (mbrasher@bmc.com)
 33            //

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

 36 mike  1.9  //
 37            //%/////////////////////////////////////////////////////////////////////////////
 38            
 39            #ifndef Pegasus_InstanceIndexFile_h
 40            #define Pegasus_InstanceIndexFile_h
 41            

 42 kumpf 1.17 #include <fstream>

 43 mike  1.9  #include <Pegasus/Common/Config.h>
 44            #include <Pegasus/Common/String.h>

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

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

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

 48 mike  1.9  
 49            PEGASUS_NAMESPACE_BEGIN
 50            

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

 64 mike  1.10   

 65 mike  1.9      <pre>

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

 67 mike  1.9      </pre>
 68            

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

 74 mike  1.10     location of the instance record in the instance file, the size is the
 75                record size of the instance record, and instance name is a CIM style
 76                object name.
 77            

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

 79 mike  1.9  
 80                <pre>

 81 mike  1.11 	00000001
 82            	0 A6B275A9 0 1425 Employee.ssn=444332222 
 83            	1 A6BA08B1 1425 1430 Employee.ssn=555667777 

 84 mike  1.9      </pre>
 85            

 86 mike  1.11     To lookup an entry in the index file, first take the hash code of the
 87                target key. Then find the first non-free entry whose hash code and key
 88                are the same as the target hash code and key. Note that an entry may
 89                usually be ruled out by comparing the hash codes (except in the case of
 90                clashes).
 91                

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

 93 mike  1.10     removing, and modifying.

 94 mike  1.9  */
 95            class PEGASUS_REPOSITORY_LINKAGE InstanceIndexFile
 96            {
 97            public:
 98                

 99 mike  1.10     /** Searches the instance index file for the given instance name. Sets 
100                    the index parameter to the corresponding index, and sets the size
101                    parameter to the corresponding instance record size.  Returns true
102                    on success.
103            

104 mike  1.11         @param path the file path of the instance index file
105                    @param instanceName the name of the instance
106                    @param indexOut the index of the instance record found
107                    @param sizeOut the size of the instance record found
108                    @return true if the instance is found; false otherwise.

109 mike  1.9      */

110 mike  1.11     static Boolean lookupEntry(

111 mike  1.9  	const String& path, 

112 kumpf 1.13 	const CIMObjectPath& instanceName,

113 mike  1.11 	Uint32& indexOut,
114            	Uint32& sizeOut);

115 mike  1.9  

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

117 mike  1.10         size of the instance record passed in.  This method assumes that the
118            	keys in the instance name are in sorted order. This must be done
119                    prior to calling the method.  Returns true on success.
120            

121 mike  1.11         @param path the file path of the instance index file
122                    @param instanceName the name of the instance
123                    @param indexIn the index of the new instance record
124                    @param sizeIn the size of the new instance record 
125                    @return true if successful; false otherwise.

126 mike  1.9      */

127 mike  1.11     static Boolean createEntry(

128 mike  1.9  	const String& path, 

129 kumpf 1.13 	const CIMObjectPath& instanceName,

130 mike  1.11 	Uint32 indexIn,
131                    Uint32 sizeIn);

132 mike  1.10 

133 mike  1.11     /** Deletes the entry with the given instance name.
134                    @param path path of the instance index file
135                    @param instanceName name of the instance
136                    @return true on success

137 mike  1.9      */

138 mike  1.11     static Boolean deleteEntry(

139 mike  1.9  	const String& path, 

140 kumpf 1.13 	const CIMObjectPath& instanceName,

141 mike  1.11 	Uint32& freeCount);

142 mike  1.9  

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

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

145 mike  1.10 

146 mike  1.11         @param path the file path of the instance index file.
147                    @param instanceName the name of the instance.
148                    @param indexIn the index of the modified instance record.
149                    @param sizeIn the size of the modified instance record.
150                    @return true on success.

151 mike  1.10     */

152 mike  1.11     static Boolean modifyEntry(

153 mike  1.10 	const String& path, 

154 kumpf 1.13 	const CIMObjectPath& instanceName,

155 mike  1.11 	Uint32 indexIn,

156 mike  1.10         Uint32 sizeIn,

157 mike  1.11 	Uint32& freeCount);

158 mike  1.10 
159                /** Gets the information stored in the index file for all the instances
160                    of the given class.  Appends the instance names, indices and sizes 
161                    to the given arrays (does not clear the arrays first).  Returns
162                    true on success.
163            

164 mike  1.11         @param path path of the instance index file.
165                    @param instanceNames array to hold the instance names.
166                    @param indices array to hold the indices of the instance records.
167                    @param sizes an array to hold the sizes of the instance records.
168                    @return true on success.

169 mike  1.9      */

170 mike  1.11     static Boolean enumerateEntries(

171 mike  1.9  	const String& path,

172 mike  1.11 	Array<Uint32>& freeFlags,
173            	Array<Uint32>& indices,
174                    Array<Uint32>& sizes,

175 kumpf 1.13 	Array<CIMObjectPath>& instanceNames,

176 mike  1.11 	Boolean includeFreeEntries);
177            

178 kumpf 1.12 

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

205 mike  1.10 
206            private:

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

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

212 mike  1.11     */
213                static Boolean _openFile(
214            	const String& path, 

215 kumpf 1.12         PEGASUS_STD(fstream)& fs,
216                    Boolean create = false);

217 mike  1.10     

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

220 mike  1.10     */

221 mike  1.11     static Boolean _appendEntry(
222                    PEGASUS_STD(fstream)& fs,

223 kumpf 1.13         const CIMObjectPath& instanceName,

224 mike  1.11         Uint32 indexIn,
225                    Uint32 sizeIn);

226 mike  1.10     

227 mike  1.11     /** Increment the index file's free count; called by _markEntryFree().
228            	The resulting value is left in the freeCount parameter.
229                */
230                static Boolean _incrementFreeCount(
231            	PEGASUS_STD(fstream)& fs,
232            	Uint32& freeCount);

233 mike  1.10 

234 mike  1.11     /** Marks the entry matching the given instanceName as free; called by both
235            	deleteEntry() and modifyEntry().
236                */
237                static Boolean _markEntryFree(
238                    PEGASUS_STD(fstream)& fs,

239 kumpf 1.13         const CIMObjectPath& instanceName);

240 mike  1.11 
241                /** Helper method for lookupEntry() which takes a file stream rather than
242            	a path.
243                */
244                static Boolean _lookupEntry(
245            	PEGASUS_STD(fstream)& fs,

246 kumpf 1.13 	const CIMObjectPath& instanceName,

247 mike  1.11 	Uint32& indexOut,
248            	Uint32& sizeOut,
249            	Uint32& entryOffset);

250 mike  1.9  };
251            
252            PEGASUS_NAMESPACE_END
253            
254            #endif /* Pegasus_InstanceIndexFile_h */