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