1 mike 1.15 //%/////////////////////////////////////////////////////////////////////////////
2 //
|
3 kumpf 1.17 // Copyright (c) 2000, 2001, 2002 BMC Software, Hewlett-Packard Company, IBM,
4 // The Open Group, Tivoli Systems
|
5 mike 1.15 //
6 // Permission is hereby granted, free of charge, to any person obtaining a copy
|
7 kumpf 1.17 // 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.15 // 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.17 // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
|
14 mike 1.15 // 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.17 // 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.15 // 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 kumpf 1.22 // Modified By: Carol Ann Krug Graves, Hewlett-Packard Company
27 // (carolann_graves@hp.com)
|
28 mike 1.15 //
29 //%/////////////////////////////////////////////////////////////////////////////
30
31 #ifndef Pegasus_InheritanceTree_h
32 #define Pegasus_InheritanceTree_h
33
34 #include <iostream>
35 #include <Pegasus/Common/Config.h>
|
36 kumpf 1.21 #include <Pegasus/Common/ArrayInternal.h>
|
37 kumpf 1.22 #include <Pegasus/Common/CIMName.h>
|
38 mike 1.15 #include <Pegasus/Common/String.h>
|
39 kumpf 1.20 #include <Pegasus/Common/InternalException.h>
|
40 kumpf 1.19 #include <Pegasus/Repository/Linkage.h>
|
41 mike 1.15
42 PEGASUS_NAMESPACE_BEGIN
43
44 struct InheritanceTreeRep;
45
46 /** The InheritanceTree class tracks inheritance relationships of CIM classes.
47
48 This class is a memory resident version of the repository's persistent
49 inheritance information (represented using file names). The InheritanceTree
50 provides O(1) access (via hashing) to any class in the inheritance tree.
51
52 The inheritance tree provides methods for interrogating certain kinds of
53 information about a class, including:
54
55 <ul>
56 <li>the superclass</li>
57 <li>the subclasses</li>
58 <li>the descendent classes</li>
59 </ul>
60
61 The insert() method is used to build up an InheritanceTree. The insert()
62 mike 1.15 method is called for each class-subclass relationship. For example, consider
63 the following list of class-subclass pairs:
64
65 <pre>
66 { "D", "B" }
67 { "E", "B" }
68 { "B", "A" }
69 { "C", "A" }
70 { "F", "C" }
71 </pre>
72
73 These pairs specify the following inheritance tree:
74
75 <pre>
76 A
77 / \
78 B C
79 / \ \
80 D E F
81 </pre>
82
83 mike 1.15 The pairs above may be used to build a class tree as follows:
84
85 <pre>
86 InheritanceTree it;
87 it.insert("D", "B");
88 it.insert("E", "B");
89 it.insert("B", "A");
90 it.insert("C", "A");
91 it.insert("F", "C");
92 it.insert("A", "");
93 it.check();
94 </pre>
95
96 The check() method determines whether insert() was called for every class
97 used as a superclass. In the following example, check() would fail (and
98 throw and exception) since the "B" class is passed as a superclass (second
99 argument) in two insert() calls but was never passed as the class itself
100 (first argument) in any insert() call:
101
102 <pre>
103 InheritanceTree it;
104 mike 1.15 it.insert("D", "B");
105 it.insert("E", "B");
106 it.insert("C", "A");
107 it.insert("F", "C");
108 it.insert("A", "");
109 it.check();
110 </pre>
111
112 In this case, check() throws an InvalidInheritanceTree exception.
113
114 The InheritanceTree may be printed by calling the print() method.
115
116 The insertFromPath() method is used to build up an InheritanceTree from
117 the file names in a certain directory as used by the CIMRepository. The
118 CIMRepository contains a disk file per class and the name has this form:
119
120 <pre>
121 <ClassName>.<SuperClassName>
122 </pre>
123
124 For example, a class called "ThisClass" with super class "ThatClass"
125 mike 1.15 has this name:
126
127 <pre>
128 ThisClass.ThisClass
129 </pre>
130
131 The file or course contains the XML encoding of the ThisClass class (which
132 is irrelevant for the InheritanceTree). A root class (with no superclass
133 has the following form):
134
135 <pre>
136 <ClassName>.#
137 </pre>
138
139 Suppose that ThatClass is a root class; then its file name is:
140
141 <pre>
142 ThatClass.#
143 </pre>
144
145 It must be obvious by now that the insertFromPath() method just scans
146 mike 1.15 the file names in a directory and calls insert() for each one (splitting
147 the class name from superclass name and translating '#' to an empty string).
148
149 The insertFromPath() method does NOT call check(), so it still must be
150 called to verify the InheritanceTree.
151 */
152 class PEGASUS_REPOSITORY_LINKAGE InheritanceTree
153 {
154 public:
155
156 /** Default constructor. */
157 InheritanceTree();
158
159 /** Destructor. */
160 ~InheritanceTree();
161
162 /** Inserts a class-subclass relationship into the inheritance three.
163 Note that a class CAN be inserted before its superclass, in which case
164 a provisional entry is made for the superclass and flagged as such;
165 when the superclass is later inserted, the provisional flag is cleared.
166 @param className - name of class being inserted.
167 mike 1.15 @param superClassName - name of super class of class.
168 */
169 void insert(const String& className, const String& superClassName);
170
171 /** Scan directory for file names of the form <ClassName>.<SuperClass> and
172 call insert on insert for each one. Note that root classes (classes with
173 no superclass) will use "#" for a SuperClass name.
174 @param path - directory that contains files describing inheritance
175 infoformation.
176 @exception throws CannotOpenDirectory is invalid path specifies an
177 invalid directory.
178 */
179 void insertFromPath(const String& path);
180
181 /** Checks that every superClassName passed to insert() was also passed
182 as a className argument to insert(). In other words, it checks that
183 there are no provisional entries as described in the insert() method.
184 @exception InvalidInheritanceTree
185 */
186 void check() const;
187
188 mike 1.15 /** Get subclass names of the given class.
189 @param className - class whose subclass names will be gotten. If
190 className is empty, all classnames are returned.
191 @param deepInheritance - if true all descendent classes of class
192 are returned. If className is empty, only root classes are returned.
193 @param subClassNames - output argument to hold subclass names.
194 @return true on success. False if no such class.
195 */
196 Boolean getSubClassNames(
|
197 kumpf 1.22 const CIMName& className,
|
198 mike 1.15 Boolean deepInheritance,
|
199 kumpf 1.22 Array<CIMName>& subClassNames) const;
|
200 mike 1.15
201 /** Returns true if class1 is a subclass of class2.
202 */
|
203 kumpf 1.22 Boolean isSubClass(const CIMName& class1, const CIMName& class2) const;
|
204 mike 1.15
205 /** Get the names of all superclasses of this class (direct and indirect).
206 */
207 Boolean getSuperClassNames(
|
208 kumpf 1.22 const CIMName& className,
209 Array<CIMName>& subClassNames) const;
|
210 mike 1.15
211 /** Get the superclass of the given class.
212 @param className name of class.
213 @param superClassName name of superclass upon return.
214 @return true if class was found; false otherwise.
215 */
216 Boolean getSuperClass(
|
217 kumpf 1.22 const CIMName& className,
218 CIMName& superClassName) const;
|
219 mike 1.15
220 /** Returns true if the given class has sub-classes. */
221 Boolean hasSubClasses(
|
222 kumpf 1.22 const CIMName& className,
|
223 mike 1.15 Boolean& hasSubClasses) const;
224
225 /** Returns true if this inhertance tree contains the given class. */
|
226 kumpf 1.22 Boolean containsClass(const CIMName& className) const;
|
227 mike 1.15
228 /** Removes the given class from the class graph.
229 @exception CIMException(CIM_ERR_CLASS_HAS_CHILDREN)
230 @exception CIMException(CIM_ERR_INVALID_CLASS)
231 */
|
232 kumpf 1.22 void remove(const CIMName& className);
|
233 mike 1.15
234 /** Prints the class */
235 void print(PEGASUS_STD(ostream)& os) const;
236
237 private:
238
239 InheritanceTree(const InheritanceTree&) { }
240
241 InheritanceTree& operator=(const InheritanceTree&) { return *this; }
242
243 InheritanceTreeRep* _rep;
244 };
245
246 /** The InvalidInheritanceTree exception is thrown when the
247 InheritanceTreeRep::check() method determines that an inheritance tree
248 was not fully specified (when any class was passed as a superClassName
249 argument to insert() but never as a className argument.
250 */
251 class InvalidInheritanceTree : public Exception
252 {
253 public:
254 mike 1.15
255 InvalidInheritanceTree(const String& className)
256 : Exception("Invalid inheritance tree: unknown class: " + className) { }
257 };
258
259 PEGASUS_NAMESPACE_END
260
261 #endif /* Pegasus_InheritanceTree_h */
|