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