1 martin 1.14 //%LICENSE////////////////////////////////////////////////////////////////

  2 martin 1.15 //

  3 martin 1.14 // Licensed to The Open Group (TOG) under one or more contributor license
  4             // agreements.  Refer to the OpenPegasusNOTICE.txt file distributed with
  5             // this work for additional information regarding copyright ownership.
  6             // Each contributor licenses this file to you under the OpenPegasus Open
  7             // Source License; you may not use this file except in compliance with the
  8             // License.

  9 martin 1.15 //

 10 martin 1.14 // Permission is hereby granted, free of charge, to any person obtaining a
 11             // copy of this software and associated documentation files (the "Software"),
 12             // to deal in the Software without restriction, including without limitation
 13             // the rights to use, copy, modify, merge, publish, distribute, sublicense,
 14             // and/or sell copies of the Software, and to permit persons to whom the
 15             // Software is furnished to do so, subject to the following conditions:

 16 martin 1.15 //

 17 martin 1.14 // The above copyright notice and this permission notice shall be included
 18             // in all copies or substantial portions of the Software.

 19 martin 1.15 //

 20 martin 1.14 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS

 21 martin 1.15 // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

 22 martin 1.14 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 23             // IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 24             // CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 25             // TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 26             // SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

 27 martin 1.15 //

 28 martin 1.14 //////////////////////////////////////////////////////////////////////////

 29 mike   1.1  //
 30             //%/////////////////////////////////////////////////////////////////////////////
 31             
 32             #ifndef Pegasus_InstanceDataFile_h
 33             #define Pegasus_InstanceDataFile_h
 34             
 35             #include <fstream>
 36             #include <Pegasus/Common/Config.h>
 37             #include <Pegasus/Common/String.h>

 38 kumpf  1.5  #include <Pegasus/Common/InternalException.h>

 39 kumpf  1.2  #include <Pegasus/Common/CIMObjectPath.h>

 40 kumpf  1.4  #include <Pegasus/Repository/Linkage.h>

 41 mike   1.10 #include <Pegasus/Common/Buffer.h>

 42 mike   1.1  
 43             PEGASUS_NAMESPACE_BEGIN
 44             
 45             /** This class manages access to an instance data file which contains all
 46                 instances of a particular class.
 47             
 48                 The instances are stored in ASCII XML format one after another. A separate
 49                 instance index file is maintained (see InstanceIndexFile) which contains
 50                 an index entry for each instance in the data file. This index ties the key
 51                 of the instance to an offset and size within the instance file.
 52             
 53                 The index file and data file are named according to the class whose
 54                 instances they contain information about. The index file and data file for
 55                 a class named "Zebra" would be:
 56             
 57                 <pre>
 58                     Zebra (index file).
 59                     Zebra.instances (instance-file).
 60                 </pre>

 61 kumpf  1.12 
 62                 When an instance is created, it is appended to the end of the instance

 63 mike   1.1      file. When one is deleted, it is marked as free in the index file. When
 64                 an instance is modified, the old one is marked as deleted and the new

 65 kumpf  1.12     modified instance is appended to the end of the data file. Note that

 66 mike   1.1      deletion and modification may leave unused gaps in the data file. These
 67                 gaps are reclaimed during compaction (performed when the data file has
 68                 N gaps where N is some arbitrarily chosen number for now). Performing
 69                 compaction during each modify and delete would be extremely inefficient.

 70 kumpf  1.12     By postponing it until N such operations have been performed, we

 71 mike   1.1      improve performance considerably.
 72             
 73                 Note the three operations which may be performed on an instance and there
 74                 associated effect on the data file.
 75             
 76                 <ul>
 77                 <li>Create - appends an instance to the end of the file.</li>
 78                 <li>Modify - appends an instance to the end of the file.</li>
 79                 <li>Delete - has no effect on the data file</li>
 80                 </ul>
 81             
 82                 To avoid corruption of the data file we provide a rollback scheme. A
 83                 rollback file is created (the name is formed by appending ".rollback" to
 84                 the name of the data file) which contains the original size of the data
 85                 file. After the modification of the data file is complete, the rollback
 86                 file is removed. If we discover a rollback file when we start an operation,
 87                 this means that the last operation did not succeed. We then rollback the
 88                 operation by truncating the file to its old size.
 89             */
 90             class PEGASUS_REPOSITORY_LINKAGE InstanceDataFile
 91             {
 92 mike   1.1  public:

 93 kumpf  1.12 

 94 mike   1.1      /** loads an instance from the data file into memory.
 95             
 96                     @param path the file path of the instance file
 97                     @param index the byte positon of the instance record

 98 kumpf  1.12         @param size the size of the instance record
 99                     @param data the buffer to hold the instance data

100 mike   1.1          @return true on success.
101                 */
102                 static Boolean loadInstance(

103 kumpf  1.12         const String& path,
104                     Uint32 index,
105                     Uint32 size,

106 mike   1.10         Buffer& data);

107 kumpf  1.12 
108                 /** loads all the instances from the data file into memory.

109 mike   1.1  
110                     @param path the file path of the instance file

111 kumpf  1.12         @param data the buffer to hold the data

112 mike   1.1          @return true on success.
113                 */
114                 static Boolean loadAllInstances(

115 kumpf  1.12         const String& path,

116 mike   1.10         Buffer& data);

117 kumpf  1.12 

118 mike   1.1      /** Appends a new instance to the end of the file.

119 kumpf  1.12 
120                     @param out the buffer containing the CIM/XML encoding of the

121 mike   1.1          @param path the file path of the instance file
122                     @param index the byte positon of the instance record
123                     @return true on success
124                 */
125                 static Boolean appendInstance(

126 kumpf  1.12         const String& path,

127 mike   1.10         const Buffer& data,

128 kumpf  1.12         Uint32& index);

129 mike   1.1  
130                 /** Begin a transaction to modify this file. The effect of subsequent

131 kumpf  1.12         modifications can be rolled back by calling rollbackTransaction().

132 mike   1.1      */
133                 static Boolean beginTransaction(const String& path);
134             

135 marek  1.16     /** In case of a failure in the beginTransaction(), undo the changes
136                     done in the begin transaction and restore the repository
137                     to the previous state
138                 */
139                 static void undoBeginTransaction(const String& path);
140             

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

142 mike   1.1          beginTransaction() was called.
143                 */
144                 static Boolean rollbackTransaction(const String& path);
145             
146                 /** Commit changes made after beginTransaction() was called.
147                 */
148                 static Boolean commitTransaction(const String& path);
149             
150                 /** Reorganizes the data file to reclaim free space. This is done by

151 kumpf  1.12         copying over all non-free instances to a temporary file and then
152                     deleting the original file and renaming the temporary file to the
153                     same name as the original.

154 mike   1.1      */
155                 static Boolean compact(

156 kumpf  1.12         const String& path,

157 mike   1.1          const Array<Uint32>& freeFlags,
158                     const Array<Uint32>& indices,
159                     const Array<Uint32>& sizes);
160             
161             private:
162             
163                 static Boolean _openFile(

164 kumpf  1.12         PEGASUS_STD(fstream)& fs,
165                     const String& path,
166                     int mode);

167 mike   1.1  };
168             
169             PEGASUS_NAMESPACE_END
170             
171             #endif /* Pegasus_InstanceDataFile_h */