1 kumpf 1.1.2.1 //%/////////////////////////////////////////////////////////////////////////////
2 //
3 // Copyright (c) 2000, 2001 BMC Software, Hewlett-Packard Company, IBM,
4 // The Open Group, Tivoli Systems
5 //
6 // Permission is hereby granted, free of charge, to any person obtaining a copy
7 // 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 // 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 // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
14 // 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 // 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 // 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 kumpf 1.1.2.1 //==============================================================================
23 //
24 // Author: Jenny Yu, Hewlett-Packard Company (jenny_yu@hp.com)
25 //
26 // Modified By:
27 //
28 //%/////////////////////////////////////////////////////////////////////////////
29
30 #ifndef Pegasus_InstanceFile_h
31 #define Pegasus_InstanceFile_h
32
33 PEGASUS_NAMESPACE_BEGIN
34
35 /** This class manages access to an 'instance file' which stores all the
36 instances of a CIM class.
37
38 For each instance, The CIM/XML representation is stored in the file.
39 The byte location and size of a particular instance record in the file
40 is stored in the 'instance index file'. The name of an instance file
41 has the following form:
42
43 kumpf 1.1.2.1 <pre>
44 className.instances
45 </pre>
46
47 Here's an example:
48
49 <pre>
50 Employee.instances
51 </pre>
52
53 When an instance is added, it is appended to the end of the
54 instance file. After an instance is deleted, the instance file is
55 reorganized to reuse the disk space. When an instance is modified,
56 the old instance is deleted, and the modified instance is
57 appended to the end of the file.
58
59 It is very important to keep both the instance and index file in
60 a consistent state. In order to minimize the window in which the
61 instance and index file can be left in an inconsistent state (after
62 an unexpected system termination or failure), all updates to the
63 instance and index files are done first to temporary files. After
64 kumpf 1.1.2.1 an update operation is successful on BOTH the instance and index files,
65 the temporary files are renamed back to the original files.
66
67 */
68
69 class PEGASUS_REPOSITORY_LINKAGE InstanceFile
70 {
71 public:
72
73 /** loads an instance record in the instance file to memory. The caller
74 passes the byte position and the size of the instance record to be
75 read. Returns true on success.
76
77 @param path the file path of the instance file
78 @param index the byte positon of the instance record
79 @param size the size of the instance record
80 @param data the buffer to hold the instance data
81
82 @return true if successful
83 false if an error occurs in accessing the instance file
84 */
85 kumpf 1.1.2.1 static Boolean loadInstance(
86 const String& path,
87 Uint32 index,
88 Uint32 size,
89 Array<Sint8>& data);
90
91 /** loads all the instance records in the instance file to memory.
92 Returns true on success.
93
94 @param path the file path of the instance file
95 @param data the buffer to hold the data
96
97 @return true if successful
98 false if an error occurs in accessing the instance file
99 */
100 static Boolean loadAllInstances(
101 const String& path,
102 Array<Sint8>& data);
103
104 /** Inserts a new instance record into the instance file. The byte
105 position and the size of the newly inserted instance record are
106 kumpf 1.1.2.1 returned. Returns true on success.
107
108 @param out the buffer containing the CIM/XML encoding of the
109 instance
110 @param path the file path of the instance file
111 @param index the byte positon of the instance record
112 @param size the size of the instance record
113
114 @return true if successful
115 false if an error occurs in accessing the instance file
116 or adding a new record to the instance file
117 */
118 static Boolean insertInstance(
119 Array<Sint8> out,
120 const String& path,
121 Uint32& index,
122 Uint32& size);
123
124 /** Removes an instance record in the instance file at the given byte
125 position for the given size. Returns true on success.
126
127 kumpf 1.1.2.1 @param path the file path of the instance file
128 @param size the size of the instance record
129 @param index the byte positon of the instance record
130
131 @return true if successful
132 false if an error occurs in accessing the instance file
133 or removing a record from the instance file
134 */
135 static Boolean removeInstance(
136 const String& path,
137 Uint32 size,
138 Uint32 index);
139
140 /** Modifies an instance record in the instance file by first removing
141 the old instance record in the instance file at the given byte
142 position, then inserts a new instance record into the instance file.
143 The byte position and the size of the newly added instance record
144 are returned. Returns true on success.
145
146 @param out the buffer containing the CIM/XML encoding of the
147 modified instance
148 kumpf 1.1.2.1 @param path the file path of the instance file
149 @param oldIndex the byte positon of the old instance record
150 @param oldSize the size of the old instance record
151 @param newIndex the byte positon of the new instance record
152 @param newSize the size of the new instance record
153
154 @return true if successful
155 false if an error occurs in accessing or modifying the
156 instance file
157 */
158 static Boolean modifyInstance(
159 Array<Sint8> out,
160 const String& path,
161 Uint32 oldIndex,
162 Uint32 oldSize,
163 Uint32& newIndex,
164 Uint32& newSize);
165
166 private:
167
168 /** Loads data from the instance file.
169 kumpf 1.1.2.1
170 This method is called to load data from the instance file. It loads
171 the given number of bytes starting at the given byte position of the
172 file. Returns true on success.
173
174 @param path the file path of the instance file
175 @param index the starting byte positon
176 @param size the number of bytes to load
177 @param data the buffer to hold the data
178
179 @return true if successful
180 false if an error occurs in accessing the instance file
181 */
182 static Boolean _loadData(
183 const String& path,
184 Uint32 index,
185 Uint32 size,
186 Array<Sint8>& data);
187
188 /** Removes data in the temporary instance file at the given byte position
189 for the given size. Returns true on success.
190 kumpf 1.1.2.1
191 @param path the file path of the instance file
192 @parm os the ofstream of the temporary instance file
193 @param size the size of the instance record
194 @param index the byte positon of the instance record
195
196 @return true if successful
197 false if an error occurs in accessing the instance file
198 or removing a record from the instance file
199 */
200 static Boolean _removeData(
201 const String& path,
202 PEGASUS_STD(ofstream)& os,
203 Uint32 size,
204 Uint32 index);
205
206 /** Appends data to the end of the temporary instance file. Returns true
207 on success.
208
209 @param out the buffer containing the CIM/XML encoding of the
210 instance
211 kumpf 1.1.2.1 @parm os the ofstream of the temporary instance file
212 @param index the byte positon of the instance record
213 @param size the size of the instance record
214
215 @return true if successful
216 false if an error occurs in accessing the instance file
217 or removing a record from the instance file
218 */
219 static Boolean _insertData(
220 Array<Sint8> out,
221 PEGASUS_STD(ofstream)& os,
222 Uint32& index,
223 Uint32& size);
224 };
225
226 PEGASUS_NAMESPACE_END
227
228 #endif /* Pegasus_InstanceFile_h */
|