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