The CIMReference class represents the value of a reference. A reference
is one of property types which an association may contain. Consider the
following MOF for example:
[Association]
class MyAssociations
{
MyClass ref from;
MyClass ref to;
};
The value of the from and to properties are internally represented using
the CIMReference class.
CIM references are used to uniquely identify a CIM class or CIM instance
objects. CIMReference objects contain the following parts:
- Host - name of host whose repository contains the object
- NameSpace - the namespace which contains the object
- ClassName - name of objects class
- KeyBindings key/value pairs which uniquely identify an instance
CIM references may also be expressed as simple strings (as opposed to
being represented by the CIMReference class). This string is known as
the "Object Name". An object name has the following form:
<namespace-path>:<model-path>
The namespace-path is implementation dependent and has the following form
in Pegasus:
//<hostname>>/<namespace>>
For example, suppose there is a host named "atp" with a CIM Server
listening on port 9999 which has a CIM repository with a namespace
called "root/cimv25". Then the namespace-path is given as:
//atp:9999/root/cimv25
As for the model-path mentioned above, its form is defined by the CIM
Standard (more is defined by the "XML Mapping Specification v2.0.0"
specification) as follows:
<Qualifyingclass>.<key-1>=<value-1>[,<key-n>=
<value-n>]*
For example:
TennisPlayer.first="Patrick",last="Rafter"
This of course presupposes the existence of a class called "TennisPlayer"
that has key properties named "first" and "last". For example, here is what
the MOF might look like:
class TennisPlayer : Person
{
[key] string first;
[key] string last;
};
All keys must be present in the model path.
Now the namespace-type and model-path are combined in the following
string object name.
//atp:9999/root/cimv25:TennisPlayer.first="Patrick",last="Rafter"
Now suppose we wish to create a CIMReference from this above string. There
are two constructors provided: one which takes the above string and the
other that takes the constituent elements. Here are the signature of the
two constructors:
CIMReference(const String& objectName);
CIMReference(
const String& host,
const String& nameSpace,
const String& className,
const KeyBindingArray& keyBindings);
Following our example, the above object name may be used to initialize
a CIMReference like this:
CIMReference ref =
"//atp:9999/root/cimv25:TennisPlayer.first="Patrick",last="Rafter";
A CIMReference may also be initialized using the constituent elements
of the object name (sometimes the object name is not available as a string:
this is the case with CIM XML encodings). The arguments shown in that
constructor above correspond elements of the object name in the following
way:
- host = "atp:9999"
- nameSpace = "root/cimv25"
- className = "TennisPlayer"
- keyBindings = "first=\"Patrick\",last=\"Rafter\""
Note that the host and nameSpace argument may be empty since object names
need not necessarily include a namespace path according to the standard.
The key bindings must be built up by appending KeyBinding objects
to a KeyBindingArray like this:
KeyBindingArray keyBindings;
keyBindings.append(KeyBinding("first", "Patrick", KeyBinding::STRING));
keyBindings.append(KeyBinding("last", "Rafter", KeyBinding::STRING));
The only key values that are supported are:
- KeyBinding::BOOLEAN
- KeyBinding::STRING
- KeyBinding::NUMERIC
This limitation is imposed by the "XML Mapping Specification v2.0.0"
specification. The CIM types are encoded as one of these three in the
following way:
boolean - BOOLEAN (the value must be "true" or "false")
uint8 - NUMERIC
sint8 - NUMERIC
uint16 - NUMERIC
sint16 - NUMERIC
uint32 - NUMERIC
sint32 - NUMERIC
uint64 - NUMERIC
sint64 - NUMERIC
char16 - NUMERIC
string - STRING
datetime - STRING
Notice that real32 and real64 are missing. Properties of these types
cannot be used as keys.
Notice that the keys in the object name may appear in any order.
That is the following object names refer to the same object:
TennisPlayer.first="Patrick",last="Rafter"
TennisPlayer.last="Rafter",first="Patrick"
And since CIM is not case sensitive, the following refer to the same
object:
TennisPlayer.first="Patrick",last="Rafter"
tennisplayer.FIRST="Patrick",Last="Rafter"
Therefore, the CIMReferences::operator==() would return true for the last
two examples.
The CIM standard leaves it an open question whether model paths may have
spaces around delimiters (like '.', '=', and ','). We assume they cannot.
So the following is an invalid model path:
TennisPlayer . first = "Patrick", last="Rafter"
We require that the '.', '=', and ',' have no spaces around them.
For reasons of efficiency, the key bindings are internally sorted
during initialization. This allows the key bindings to be compared
more easily. This means that when the string is converted back to
string (by calling toString()) that the keys may have been rearranged.
There are two forms an object name can take:
<namespace-path>:<model-path>
<model-path>
In other words, the namespace-path is optional. Here is an example of
each:
//atp:9999/root/cimv25:TennisPlayer.first="Patrick",last="Rafter"
TennisPlayer.first="Patrick",last="Rafter"
If it begins with "//" then we assume the namespace-path is present and
process it that way.
It should also be noted that an object name may refer to an instance or
a class. Here is an example of each:
TennisPlayer.first="Patrick",last="Rafter"
TennisPlayer
In the second case--when it refers to a class--the key bindings are
omitted.
![[more]](icon1.gif)
CIMReference()