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 karl  1.23 //

 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            //%/////////////////////////////////////////////////////////////////////////////
 33            
 34            #ifndef Pegasus_InstanceIndexFile_h
 35            #define Pegasus_InstanceIndexFile_h
 36            

 37 kumpf 1.17 #include <fstream>

 38 mike  1.9  #include <Pegasus/Common/Config.h>
 39            #include <Pegasus/Common/String.h>

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

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

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

 43 mike  1.9  
 44            PEGASUS_NAMESPACE_BEGIN
 45            

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

 47 kumpf 1.22     instance names to offsets of the instances contained in the "instance
 48                data file".

 49 mike  1.11 

 50 kumpf 1.22     The first line of this file is a free count, expressed as eight hex
 51                digits followed by a newline. The free count indicates how many instances
 52                are free (but not reclaimed). When instances are deleted or modified, the

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

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

 55 mike  1.11     some upper bound, reclamation is performed which involves removing free
 56                entries (from both the index file and the data file).
 57            
 58                All subsequent lines contain an entry with the following form:

 59 kumpf 1.22 

 60 mike  1.9      <pre>

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

 62 mike  1.9      </pre>
 63            

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

 69 mike  1.10     location of the instance record in the instance file, the size is the
 70                record size of the instance record, and instance name is a CIM style
 71                object name.
 72            

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

 74 mike  1.9  
 75                <pre>

 76 kumpf 1.22         00000001
 77                    0 A6B275A9 0 1425 Employee.ssn=444332222
 78                    1 A6BA08B1 1425 1430 Employee.ssn=555667777

 79 mike  1.9      </pre>
 80            

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

 86 kumpf 1.22 

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

 88 mike  1.10     removing, and modifying.

 89 mike  1.9  */
 90            class PEGASUS_REPOSITORY_LINKAGE InstanceIndexFile
 91            {
 92            public:

 93 kumpf 1.22 
 94                /** Searches the instance index file for the given instance name. Sets

 95 mike  1.10         the index parameter to the corresponding index, and sets the size
 96                    parameter to the corresponding instance record size.  Returns true
 97                    on success.
 98            

 99 mike  1.11         @param path the file path of the instance index file
100                    @param instanceName the name of the instance
101                    @param indexOut the index of the instance record found
102                    @param sizeOut the size of the instance record found
103                    @return true if the instance is found; false otherwise.

104 mike  1.9      */

105 mike  1.11     static Boolean lookupEntry(

106 kumpf 1.22         const String& path,
107                    const CIMObjectPath& instanceName,
108                    Uint32& indexOut,
109                    Uint32& sizeOut);

110 mike  1.9  

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

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

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

114 mike  1.10         prior to calling the method.  Returns true on success.
115            

116 mike  1.11         @param path the file path of the instance index file
117                    @param instanceName the name of the instance
118                    @param indexIn the index of the new instance record

119 kumpf 1.22         @param sizeIn the size of the new instance record

120 mike  1.11         @return true if successful; false otherwise.

121 mike  1.9      */

122 mike  1.11     static Boolean createEntry(

123 kumpf 1.22         const String& path,
124                    const CIMObjectPath& instanceName,
125                    Uint32 indexIn,

126 mike  1.11         Uint32 sizeIn);

127 mike  1.10 

128 mike  1.11     /** Deletes the entry with the given instance name.
129                    @param path path of the instance index file
130                    @param instanceName name of the instance
131                    @return true on success

132 mike  1.9      */

133 mike  1.11     static Boolean deleteEntry(

134 kumpf 1.22         const String& path,
135                    const CIMObjectPath& instanceName,
136                    Uint32& freeCount);

137 mike  1.9  

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

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

140 mike  1.10 

141 mike  1.11         @param path the file path of the instance index file.
142                    @param instanceName the name of the instance.
143                    @param indexIn the index of the modified instance record.
144                    @param sizeIn the size of the modified instance record.
145                    @return true on success.

146 mike  1.10     */

147 mike  1.11     static Boolean modifyEntry(

148 kumpf 1.22         const String& path,
149                    const CIMObjectPath& instanceName,
150                    Uint32 indexIn,

151 mike  1.10         Uint32 sizeIn,

152 kumpf 1.22         Uint32& freeCount);

153 mike  1.10 
154                /** Gets the information stored in the index file for all the instances

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

156 mike  1.10         to the given arrays (does not clear the arrays first).  Returns
157                    true on success.
158            

159 mike  1.11         @param path path of the instance index file.
160                    @param instanceNames array to hold the instance names.
161                    @param indices array to hold the indices of the instance records.
162                    @param sizes an array to hold the sizes of the instance records.
163                    @return true on success.

164 mike  1.9      */

165 mike  1.11     static Boolean enumerateEntries(

166 kumpf 1.22         const String& path,
167                    Array<Uint32>& freeFlags,
168                    Array<Uint32>& indices,

169 mike  1.11         Array<Uint32>& sizes,

170 kumpf 1.22         Array<CIMObjectPath>& instanceNames,
171                    Boolean includeFreeEntries);

172 mike  1.11 

173 kumpf 1.12 

174 mike  1.11     /** Returns true if this index file has any non-free entries:
175                */
176                static Boolean hasNonFreeEntries(const String& path);
177            
178                /** Begin a transaction to modify this file. The effect of subsequent

179 kumpf 1.22         modifications can be rolled back by calling rollbackTransaction().
180                    The current implementation simply copies the index file to a a file
181                    with the same name but with ".rollback" appended to it.

182 mike  1.11     */
183                static Boolean beginTransaction(const String& path);
184            

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

186 mike  1.11         beginTransaction() was called. The current implementation deletes

187 kumpf 1.22         the current file and renames the rollback file to the same name.

188 mike  1.11     */
189                static Boolean rollbackTransaction(const String& path);
190            
191                /** Commit changes made after beginTransaction() was called. The curent

192 kumpf 1.22         implementation simply removes the .rollback file.

193 mike  1.11     */
194                static Boolean commitTransaction(const String& path);
195            
196                /** Compact the file by removing entries which are marked as free.
197                */
198                static Boolean compact(
199                    const String& path);

200 mike  1.10 
201            private:

202 mike  1.11 
203                /** Open the index file and position the file pointer on the first

204 kumpf 1.22         entry (immediately after the free count). Create the file if it
205                    does not exist and if the create flag is true (writing a free

206 kumpf 1.12         count of zero).

207 mike  1.11     */
208                static Boolean _openFile(

209 kumpf 1.22         const String& path,

210 kumpf 1.12         PEGASUS_STD(fstream)& fs,
211                    Boolean create = false);

212 kumpf 1.22 

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

215 mike  1.10     */

216 mike  1.11     static Boolean _appendEntry(
217                    PEGASUS_STD(fstream)& fs,

218 kumpf 1.13         const CIMObjectPath& instanceName,

219 mike  1.11         Uint32 indexIn,
220                    Uint32 sizeIn);

221 kumpf 1.22 

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

223 kumpf 1.22         The resulting value is left in the freeCount parameter.

224 mike  1.11     */
225                static Boolean _incrementFreeCount(

226 kumpf 1.22         PEGASUS_STD(fstream)& fs,
227                    Uint32& freeCount);

228 mike  1.10 

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

230 kumpf 1.22         deleteEntry() and modifyEntry().

231 mike  1.11     */
232                static Boolean _markEntryFree(
233                    PEGASUS_STD(fstream)& fs,

234 kumpf 1.13         const CIMObjectPath& instanceName);

235 mike  1.11 
236                /** Helper method for lookupEntry() which takes a file stream rather than

237 kumpf 1.22         a path.

238 mike  1.11     */
239                static Boolean _lookupEntry(

240 kumpf 1.22         PEGASUS_STD(fstream)& fs,
241                    const CIMObjectPath& instanceName,
242                    Uint32& indexOut,
243                    Uint32& sizeOut,
244                    Uint32& entryOffset);

245 mike  1.9  };
246            
247            PEGASUS_NAMESPACE_END
248            
249            #endif /* Pegasus_InstanceIndexFile_h */