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