1 kumpf 1.6 //%/////////////////////////////////////////////////////////////////////////////
|
2 chip 1.1 //
|
3 kumpf 1.6 // Copyright (c) 2000, 2001, 2002 BMC Software, Hewlett-Packard Company, IBM,
4 // The Open Group, Tivoli Systems
|
5 chip 1.1 //
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 kumpf 1.6 //
|
13 chip 1.1 // 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 //==============================================================================
23 //
|
24 kumpf 1.2 // Author: Mike Brasher (mbrasher@bmc.com)
|
25 chip 1.1 //
|
26 kumpf 1.2 // Modified By: Roger Kumpf, Hewlett-Packard Company (roger_kumpf@hp.com)
|
27 kumpf 1.11 // Carol Ann Krug Graves, Hewlett-Packard Company
28 // (carolann_graves@hp.com)
|
29 chip 1.1 //
30 //%/////////////////////////////////////////////////////////////////////////////
31
|
32 kumpf 1.2 #ifndef Pegasus_ObjectPath_h
33 #define Pegasus_ObjectPath_h
|
34 chip 1.1
35 #include <Pegasus/Common/Config.h>
|
36 kumpf 1.9 #include <Pegasus/Common/Linkage.h>
|
37 kumpf 1.2 #include <Pegasus/Common/String.h>
|
38 kumpf 1.9 #include <Pegasus/Common/CIMName.h>
|
39 kumpf 1.2 #include <Pegasus/Common/Array.h>
40 #include <Pegasus/Common/Exception.h>
41
42 #include <iostream>
|
43 chip 1.1
44 PEGASUS_NAMESPACE_BEGIN
45
|
46 kumpf 1.2 class CIMObjectPath;
47 class KeyBindingRep;
48 class CIMObjectPathRep;
49
50 /** The KeyBinding class associates a key name, value, and type.
51 It is used by the reference class to represent key bindings.
52 See the CIMObjectPath class to see how they are used.
53 */
54 class PEGASUS_COMMON_LINKAGE KeyBinding
55 {
56 public:
57
58 enum Type { BOOLEAN, STRING, NUMERIC, REFERENCE };
59
60 /** Default constructor */
61 KeyBinding();
62
63 /** Copy constructor */
64 KeyBinding(const KeyBinding& x);
65
66 /** Construct a KeyBinding with a name, value, and type
|
67 kumpf 1.9 @param name CIMName name for the key for this binding object.
|
68 kumpf 1.2 @param value String value for this key.
69 @param type
70 <pre>
71 </pre>
72 */
|
73 kumpf 1.9 KeyBinding(const CIMName& name, const String& value, Type type);
|
74 kumpf 1.2
75 /** Destructor */
76 ~KeyBinding();
77
78 /** Assignment operator */
79 KeyBinding& operator=(const KeyBinding& x);
80
81 /** Accessor
82 */
|
83 kumpf 1.9 const CIMName& getName() const;
|
84 kumpf 1.2
85 /** Modifier */
|
86 kumpf 1.9 void setName(const CIMName& name);
|
87 kumpf 1.2
88 /** Accessor */
89 const String& getValue() const;
90
91 /** Modifier */
92 void setValue(const String& value);
93
94 /** Accessor */
95 Type getType() const;
96
97 /** Modifier */
98 void setType(Type type);
99
100 private:
101
102 KeyBindingRep* _rep;
103
104 friend class CIMObjectPath;
105 };
106
107 PEGASUS_COMMON_LINKAGE Boolean operator==(
108 kumpf 1.2 const KeyBinding& x,
109 const KeyBinding& y);
110
111 #define PEGASUS_ARRAY_T KeyBinding
|
112 kumpf 1.4 # include <Pegasus/Common/ArrayInter.h>
|
113 kumpf 1.2 #undef PEGASUS_ARRAY_T
114
115 typedef Array<KeyBinding> KeyBindingArray;
116
117 class XmlWriter;
118
119 /** The CIMObjectPath class represents the value of a reference. A reference
120 is one of property types which an association may contain. Consider the
121 following MOF for example:
122
123 <pre>
124 [Association]
125 class MyAssociations
126 {
127 MyClass ref from;
128 MyClass ref to;
129 };
130 </pre>
131
132 The value of the from and to properties are internally represented using
133 the CIMObjectPath class.
134 kumpf 1.2
135 CIM references are used to uniquely identify a CIM class or CIM instance
136 objects. CIMObjectPath objects contain the following parts:
137
138 <ul>
139 <li>Host - name of host whose repository contains the object</li>
140 <li>NameSpace - the namespace which contains the object</li>
141 <li>ClassName - name of objects class</li>
142 <li>KeyBindings key/value pairs which uniquely identify an instance</li>
143 </ul>
144
145 CIM references may also be expressed as simple strings (as opposed to
146 being represented by the CIMObjectPath class). This string is known as
147 the "Object Name". An object name has the following form:
148
149 <pre>
150 <namespace-path>:<model-path>
151 </pre>
152
153 The namespace-path is implementation dependent and has the following form
154 in Pegasus:
155 kumpf 1.2
156 <pre>
157 //<hostname>>/<namespace>>
158 </pre>
159
160 For example, suppose there is a host named "atp" with a CIM Server
161 listening on port 9999 which has a CIM repository with a namespace
162 called "root/cimv25". Then the namespace-path is given as:
163
164 <pre>
165 //atp:9999/root/cimv25
166 </pre>
167
168 As for the model-path mentioned above, its form is defined by the CIM
169 Standard (more is defined by the "XML Mapping Specification v2.0.0"
170 specification) as follows:
171
172 <pre>
173
174 <Qualifyingclass>.<key-1>=<value-1>[,<key-n>=
175 <value-n>]*
176 kumpf 1.2 </pre>
177
178 For example:
179
180 <pre>
181 TennisPlayer.first="Patrick",last="Rafter"
182 </pre>
183
184 This of course presupposes the existence of a class called "TennisPlayer"
185 that has key properties named "first" and "last". For example, here is what
186 the MOF might look like:
187
188 <pre>
189 class TennisPlayer : Person
190 {
191 [key] string first;
192 [key] string last;
193 };
194 </pre>
195
196 All keys must be present in the model path.
197 kumpf 1.2
198 Now the namespace-type and model-path are combined in the following
199 string object name.
200
201 //atp:9999/root/cimv25:TennisPlayer.first="Patrick",last="Rafter"
202
203 Now suppose we wish to create a CIMObjectPath from this above string. There
204 are two constructors provided: one which takes the above string and the
205 other that takes the constituent elements. Here are the signature of the
206 two constructors:
207
208 <pre>
209 CIMObjectPath(const String& objectName);
210
211 CIMObjectPath(
212 const String& host,
|
213 kumpf 1.9 const CIMNamespaceName& nameSpace,
214 const CIMName& className,
|
215 kumpf 1.2 const KeyBindingArray& keyBindings);
216 </pre>
217
218 Following our example, the above object name may be used to initialize
219 a CIMObjectPath like this:
220
221 <pre>
222 CIMObjectPath ref =
223 "//atp:9999/root/cimv25:TennisPlayer.first="Patrick",last="Rafter";
224 </pre>
225
226 A CIMObjectPath may also be initialized using the constituent elements
227 of the object name (sometimes the object name is not available as a string:
228 this is the case with CIM XML encodings). The arguments shown in that
229 constructor above correspond elements of the object name in the following
230 way:
231
232 <ul>
233 <li>host = "atp:9999"</li>
234 <li>nameSpace = "root/cimv25"</li>
235 <li>className = "TennisPlayer"</li>
236 kumpf 1.2 <li>keyBindings = "first=\"Patrick\",last=\"Rafter\""</li>
237 </ul>
238
239 Note that the host and nameSpace argument may be empty since object names
240 need not necessarily include a namespace path according to the standard.
241
242 The key bindings must be built up by appending KeyBinding objects
243 to a KeyBindingArray like this:
244
245 <pre>
246 KeyBindingArray keyBindings;
247 keyBindings.append(KeyBinding("first", "Patrick", KeyBinding::STRING));
248 keyBindings.append(KeyBinding("last", "Rafter", KeyBinding::STRING));
249 </pre>
250
251 The only key values that are supported are:
252
253 <ul>
254 <li>KeyBinding::BOOLEAN</li>
255 <li>KeyBinding::STRING</li>
256 <li>KeyBinding::NUMERIC</li>
257 kumpf 1.2 </ul>
258
259 This limitation is imposed by the "XML Mapping Specification v2.0.0"
260 specification. The CIM types are encoded as one of these three in the
261 following way:
262
263 <pre>
264 boolean - BOOLEAN (the value must be "true" or "false")
265 uint8 - NUMERIC
266 sint8 - NUMERIC
267 uint16 - NUMERIC
268 sint16 - NUMERIC
269 uint32 - NUMERIC
270 sint32 - NUMERIC
271 uint64 - NUMERIC
272 sint64 - NUMERIC
273 char16 - NUMERIC
274 string - STRING
275 datetime - STRING
276 </pre>
277
278 kumpf 1.2 Notice that real32 and real64 are missing. Properties of these types
279 cannot be used as keys.
280
281 Notice that the keys in the object name may appear in any order.
282 That is the following object names refer to the same object:
283
284 <pre>
285 TennisPlayer.first="Patrick",last="Rafter"
286 TennisPlayer.last="Rafter",first="Patrick"
287 </pre>
288
289 And since CIM is not case sensitive, the following refer to the same
290 object:
291
292 <pre>
293 TennisPlayer.first="Patrick",last="Rafter"
294 tennisplayer.FIRST="Patrick",Last="Rafter"
295 </pre>
296
297 Therefore, the CIMObjectPaths::operator==() would return true for the last
298 two examples.
299 kumpf 1.2
300 The CIM standard leaves it an open question whether model paths may have
301 spaces around delimiters (like '.', '=', and ','). We assume they cannot.
302 So the following is an invalid model path:
303
304 <pre>
305 TennisPlayer . first = "Patrick", last="Rafter"
306 </pre>
307
308 We require that the '.', '=', and ',' have no spaces around them.
309
310 For reasons of efficiency, the key bindings are internally sorted
311 during initialization. This allows the key bindings to be compared
312 more easily. This means that when the string is converted back to
313 string (by calling toString()) that the keys may have been rearranged.
314
315 There are two forms an object name can take:
316
317 <pre>
318 <namespace-path>:<model-path>
319 <model-path>
320 kumpf 1.2 </pre>
321
322 In other words, the namespace-path is optional. Here is an example of
323 each:
324
325 <pre>
326 //atp:9999/root/cimv25:TennisPlayer.first="Patrick",last="Rafter"
327 TennisPlayer.first="Patrick",last="Rafter"
328 </pre>
329
330 If it begins with "//" then we assume the namespace-path is present and
331 process it that way.
332
333 It should also be noted that an object name may refer to an instance or
334 a class. Here is an example of each:
335
336 <pre>
337 TennisPlayer.first="Patrick",last="Rafter"
338 TennisPlayer
339 </pre>
340
341 kumpf 1.2 In the second case--when it refers to a class--the key bindings are
342 omitted.
343 */
344 class PEGASUS_COMMON_LINKAGE CIMObjectPath
345 {
346 public:
347
348 /** Default constructor. */
349 CIMObjectPath();
350
351 /** Copy constructor. */
352 CIMObjectPath(const CIMObjectPath& x);
353
354 /** Initializes a CIMObjectPath object from a CIM object name.
355 @param objectName String representing the object name.
356 @return Returns the initialized CIMObjectPath
|
357 kumpf 1.11 @exception IllformedObjectName if the name is not parsable.
|
358 kumpf 1.2 <PRE>
359 CIMObjectPath r1 = "MyClass.z=true,y=1234,x=\"Hello World\"";
360 </PRE>
361 */
362 CIMObjectPath(const String& objectName);
363
364 /** Constructs a CIMObjectPath from constituent elements.
365 @param host Name of host (e.g., "nemesis-5988").
366 @param nameSpace Namespace (e.g., "root/cimv2").
367 @param className Name of a class (e.g., "MyClass").
368 @param keyBindings An array of KeyBinding objects.
369 @return Returns the constructed CIMObjectPath
370 */
371 CIMObjectPath(
372 const String& host,
|
373 kumpf 1.9 const CIMNamespaceName& nameSpace,
374 const CIMName& className,
|
375 kumpf 1.11 //
376 // NOTE: Due to a bug in MSVC 5, the following will not work on MSVC 5
377 //
378 const KeyBindingArray& keyBindings = KeyBindingArray ());
|
379 kumpf 1.2
380 /** Destructor */
381 ~CIMObjectPath();
382
383 /** Assignment operator */
384 CIMObjectPath& operator=(const CIMObjectPath& x);
385
386 /** Clears out the internal fields of this object making it an empty
387 (or unitialized reference). The effect is the same as if the object
388 was initialized with the default constructor.
389 */
390 void clear();
391
392 /** Sets this reference from constituent elements. The effect is same
393 as if the object was initialized using the constructor above that
394 has the same arguments.
|
395 kumpf 1.11 @exception IllformedObjectName if host name is illformed.
|
396 kumpf 1.2 */
397 void set(
398 const String& host,
|
399 kumpf 1.9 const CIMNamespaceName& nameSpace,
400 const CIMName& className,
|
401 kumpf 1.11 //
402 // NOTE: Due to a bug in MSVC 5, the following will not work on MSVC 5
403 //
404 const KeyBindingArray& keyBindings = KeyBindingArray ());
|
405 kumpf 1.2
406 /** Set the reference from an object name . */
|
407 kumpf 1.11 void set(const String& objectName);
|
408 kumpf 1.2
409 /** Same as set() above except that it is an assignment operator */
410 CIMObjectPath& operator=(const String& objectName);
411
412 /** getHost - returns the hostname component of the
413 CIMObjectPath
414 @return String containing hostname.
415 <pre>
416
417 </pre>
418 */
419 const String& getHost() const;
420
421 /** setHost Sets the hostname component of the CIMObjectPath
422 object to the input parameter
423 @param host String parameter with the hostname
424 <PRE>
425 CIMObjectPath r1;
426 r1.setHost("fred:5988");
427 </PRE>
428 Note that Pegasus does no checking on valid host names.
429 kumpf 1.2 */
430 void setHost(const String& host);
431
432 /** getNameSpace - returns the namespace component of the
|
433 kumpf 1.10 CIMObjectPath as a CIMNamespaceName.
|
434 kumpf 1.2 */
|
435 kumpf 1.9 const CIMNamespaceName& getNameSpace() const;
|
436 kumpf 1.2
437 /** Sets the namespace component.
|
438 kumpf 1.10 @param CIMNamespaceName representing the namespace.
|
439 kumpf 1.2 */
|
440 kumpf 1.9 void setNameSpace(const CIMNamespaceName& nameSpace);
|
441 kumpf 1.2
442 /** Accessor for className attribute.
|
443 kumpf 1.9 @return CIMName containing the classname.
|
444 kumpf 1.2 */
|
445 kumpf 1.9 const CIMName& getClassName() const;
|
446 kumpf 1.2
447 /** Sets the classname component of the CIMObjectPath object to the input
448 parameter.
|
449 kumpf 1.9 @param className CIMName containing the className.
|
450 kumpf 1.2 */
|
451 kumpf 1.9 void setClassName(const CIMName& className);
|
452 kumpf 1.2
453 /** getKeyBindings - Returns an Array of keybindings from the
454 CIMObjectPath representing all of the key/value pairs defined in the
455 ObjectPath.
456 @return Array of KeyBinding objects from the CIMObjectPath.
457 */
458 const Array<KeyBinding>& getKeyBindings() const;
459
460 /** setKeyBindings - Sets the key/value pairs in the CIMObjectPath
461 from an array of keybindings defined by the input parameter
462 @param keyBindings Array of keybindings to set into the CIMObjectPath
463 object.
464 */
465 void setKeyBindings(const Array<KeyBinding>& keyBindings);
466
|
467 kumpf 1.7 // ATTN: The form of the below string definition needs cleaning.
468
|
469 kumpf 1.2 /** Returns the object name represented by this reference. The returned
470 string is formed from the hostname, namespace, classname
471 and keybindings defined for this CIMObjectPath object.
472 the form of the name is:
473
474 <pre>
475 "//" + hostname + "/" + namespace + ":" + classname +"." +
476 (keyname) + "=" (keyvalue) +"," ...
477 </pre>
478
479 The building includes the escaping of special characters.
480 */
481 String toString(Boolean includeHost=true) const;
482
483 /** Stringizes object into canonical form (in which all keys are sorted
484 into ascending order and classnames and keynames are shifted to
485 lower case.
486 */
487 String toStringCanonical(Boolean includeHost=true) const;
488
489 /** Returns true if this reference is identical to the one given
490 kumpf 1.2 by the x argument. Since CIMObjectPaths are normalized when they
491 are created, any differences in the ordering of keybindings is accounted
492 for as are the case insensitivity characteristics defined by
493 the specification
494 @param CIMObjectPath for comparison
495 @return True if the objects are have identical components
496 <PRE>
497 </PRE>
498 */
499 Boolean identical(const CIMObjectPath& x) const;
500
501 /** Generates hash code for the given reference. Two identical references
502 generate the same hash code (despite any subtle differences such as
503 the case of the classname and key names as well as the order of the
504 keys).
505 */
506 Uint32 makeHashCode() const;
507
508
509 private:
510
511 kumpf 1.2 Boolean _parseHostElement(
512 const String& objectName,
513 char*& p,
|
514 kumpf 1.11 String& host);
|
515 kumpf 1.2
516 Boolean _parseNamespaceElement(
517 const String& objectName,
518 char*& p,
|
519 kumpf 1.9 CIMNamespaceName& nameSpace);
|
520 kumpf 1.2
521 void _parseKeyBindingPairs(
522 const String& objectName,
523 char*& p,
|
524 kumpf 1.11 Array<KeyBinding>& keyBindings);
|
525 kumpf 1.2
526 CIMObjectPathRep* _rep;
527 };
528
529 PEGASUS_COMMON_LINKAGE Boolean operator==(
530 const CIMObjectPath& x,
531 const CIMObjectPath& y);
532
533 PEGASUS_COMMON_LINKAGE Boolean operator!=(
534 const CIMObjectPath& x,
535 const CIMObjectPath& y);
536
537 PEGASUS_COMMON_LINKAGE PEGASUS_STD(ostream)& operator<<(
538 PEGASUS_STD(ostream)& os,
539 const CIMObjectPath& x);
540
541 #define PEGASUS_ARRAY_T CIMObjectPath
|
542 kumpf 1.5 # include <Pegasus/Common/ArrayInter.h>
|
543 kumpf 1.2 #undef PEGASUS_ARRAY_T
|
544 chip 1.1
545 PEGASUS_NAMESPACE_END
546
|
547 kumpf 1.2 #endif /* Pegasus_ObjectPath_h */
548
549
|
Return to
CIMObjectPath.h
CVS log
Up to [Pegasus] / pegasus / src / Pegasus / Common