1 mike 1.1 //%/////////////////////////////////////////////////////////////////////////////
2 //
3 // Copyright (c) 2000 The Open Group, BMC Software, Tivoli Systems, IBM
4 //
5 // Permission is hereby granted, free of charge, to any person obtaining a
6 // copy of this software and associated documentation files (the "Software"),
7 // to deal in the Software without restriction, including without limitation
8 // the rights to use, copy, modify, merge, publish, distribute, sublicense,
9 // and/or sell copies of the Software, and to permit persons to whom the
10 // Software is furnished to do so, subject to the following conditions:
11 //
12 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
13 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
14 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
15 // THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
16 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
17 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
18 // DEALINGS IN THE SOFTWARE.
19 //
20 //==============================================================================
21 //
|
22 mike 1.2 // Author: Mike Brasher (mbrasher@bmc.com)
|
23 mike 1.1 //
24 // Modified By:
25 //
26 //%/////////////////////////////////////////////////////////////////////////////
27
28 #ifndef Pegasus_InheritanceTree_h
29 #define Pegasus_InheritanceTree_h
30
|
31 mike 1.2 #include <iostream>
|
32 mike 1.1 #include <Pegasus/Common/Config.h>
|
33 mike 1.2 #include <Pegasus/Common/String.h>
|
34 mike 1.4 #include <Pegasus/Common/Exception.h>
|
35 mike 1.1
36 PEGASUS_NAMESPACE_BEGIN
37
|
38 mike 1.3 struct InheritanceTreeRep;
39
|
40 mike 1.1 /** The InheritanceTree class tracks inheritance relationships of CIM classes.
41
42 This class is a memory resident version of the repository's persistent
43 inheritance information (represented using file names). The InheritanceTree
44 provides O(1) access (via hashing) to any class in the inheritance tree.
45
|
46 mike 1.4 The inheritance tree provides methods for interrogating certain kinds of
47 information about a class, including:
48
49 <ul>
50 <li>the superclass</li>
51 <li>the subclasses</li>
52 <li>the descendent classes</li>
53 </ul>
54
55 The insert() method is used to build up an InheritanceTree. The insert()
56 method is called for each class-subclass relationship. For example, consider
57 the following list of class-subclass pairs:
58
59 <pre>
60 { "D", "B" }
61 { "E", "B" }
62 { "B", "A" }
63 { "C", "A" }
64 { "F", "C" }
65 </pre>
66
67 mike 1.4 These pairs specify the following inheritance tree:
68
69 <pre>
70 A
71 / \
72 B C
73 / \ \
74 D E F
75 </pre>
76
77 The pairs above may be used to build a class tree as follows:
78
79 <pre>
80 InheritanceTree it;
81 it.insert("D", "B");
82 it.insert("E", "B");
83 it.insert("B", "A");
84 it.insert("C", "A");
85 it.insert("F", "C");
86 it.insert("A", "");
87 it.check();
88 mike 1.4 </pre>
89
90 The check() method determines whether insert() was called for every class
91 used as a superclass. In the following example, check() would fail (and
92 throw and exception) since the "B" class is passed as a superclass (second
93 argument) in two insert() calls but was never passed as the class itself
94 (first argument) in any insert() call:
95
96 <pre>
97 InheritanceTree it;
98 it.insert("D", "B");
99 it.insert("E", "B");
100 it.insert("C", "A");
101 it.insert("F", "C");
102 it.insert("A", "");
103 it.check();
104 </pre>
105
106 In this case, check() throws an InvalidInheritanceTree exception.
107
108 The InheritanceTree may be printed by calling the print() method.
109 mike 1.4
110 The insertFromPath() method is used to build up an InheritanceTree from
111 the file names in a certain directory as used by the CIMRepository. The
112 CIMRepository contains a disk file per class and the name has this form:
113
114 <pre>
115 <ClassName>.<SuperClassName>
116 </pre>
117
118 For example, a class called "ThisClass" with super class "ThatClass"
119 has this name:
120
121 <pre>
122 ThisClass.ThisClass
123 </pre>
124
125 The file or course contains the XML encoding of the ThisClass class (which
126 is irrelevant for the InheritanceTree). A root class (with no superclass
127 has the following form):
128
129 <pre>
130 mike 1.4 <ClassName>.#
131 </pre>
132
133 Suppose that ThatClass is a root class; then its file name is:
134
135 <pre>
136 ThatClass.#
137 </pre>
138
139 It must be obvious by now that the insertFromPath() method just scans
140 the file names in a directory and calls insert() for each one (splitting
141 the class name from superclass name and translating '#' to an empty string).
142
143 The insertFromPath() method does NOT call check(), so it still must be
144 called to verify the InheritanceTree.
|
145 mike 1.1 */
|
146 mike 1.2 class PEGASUS_REPOSITORY_LINKAGE InheritanceTree
147 {
148 public:
149
|
150 mike 1.4 /** Default constructor. */
|
151 mike 1.3 InheritanceTree();
|
152 mike 1.2
|
153 mike 1.4 /** Destructor. */
|
154 mike 1.3 ~InheritanceTree();
|
155 mike 1.2
|
156 mike 1.4 /** Inserts a class-subclass relationship into the inheritance three.
157 Note that a class CAN be inserted before its superclass, in which case
158 a provisional entry is made for the superclass and flagged as such;
159 when the superclass is later inserted, the provisional flag is cleared.
160 @param className - name of class being inserted.
161 @param superClassName - name of super class of class.
162 */
163 void insert(const String& className, const String& superClassName);
164
165 /** Scan directory for file names of the form <ClassName>.<SuperClass> and
166 call insert on insert for each one. Note that root classes (classes with
167 no superclass) will use "#" for a SuperClass name.
168 @param path - directory that contains files describing inheritance
169 infoformation.
170 @exception throws CannotOpenDirectory is invalid path specifies an
171 invalid directory.
172 */
173 void insertFromPath(const String& path);
174
175 /** Checks that every superClassName passed to insert() was also passed
176 as a className argument to insert(). In other words, it checks that
177 mike 1.4 there are no provisional entries as described in the insert() method.
178 @exception InvalidInheritanceTree
179 */
180 void check() const;
|
181 mike 1.2
|
182 mike 1.4 /** Get subclass names of the given class.
183 @param className - class whose subclass names will be gotten. If
184 className is empty, all classnames are returned.
185 @param deepInheritance - if true all descendent classes of class
186 are returned. If className is empty, only root classes are returned.
187 @param subClassNames - output argument to hold subclass names.
188 @return true on success. False if no such class.
189 */
190 Boolean getSubClassNames(
191 const String& className,
192 Boolean deepInheritance,
|
193 mike 1.5 Array<String>& subClassNames) const;
|
194 mike 1.4
|
195 mike 1.6 /** Returns true if the given class has sub-classes. */
196 Boolean hasSubClasses(
197 const String& className,
198 Boolean& hasSubClasses) const;
199
200 /** Prints the class */
201 void print(std::ostream& os) const;
202
|
203 mike 1.2 private:
|
204 mike 1.6
205 InheritanceTree(const InheritanceTree&) { }
206
207 InheritanceTree& operator=(const InheritanceTree&) { return *this; }
|
208 mike 1.2
|
209 mike 1.3 InheritanceTreeRep* _rep;
|
210 mike 1.4 };
211
212 /** The InvalidInheritanceTree exception is thrown when the
213 InheritanceTreeRep::check() method determines that an inheritance tree
214 was not fully specified (when any class was passed as a superClassName
215 argument to insert() but never as a className argument.
216 */
217 class InvalidInheritanceTree : public Exception
218 {
219 public:
220
221 InvalidInheritanceTree(const String& className)
222 : Exception("Invalid inheritance tree: unknown class: " + className) { }
|
223 mike 1.2 };
|
224 mike 1.1
225 PEGASUS_NAMESPACE_END
226
227 #endif /* Pegasus_InheritanceTree_h */
|