Sun WBEM SDK Developer's Guide

Associations

This section explains the CIM concept of associations and the CIMClient methods you can use to get information about associations.

About Associations

An association describes a relationship between two or more managed resources, for example a computer and the system disk it contains. This relationship is described in an association class, a special type of class that contains an association qualifier.

An association class also contains two or more references to the CIM instances representing its managed resources. A reference is a special property type that is declared with the REF keyword, indicating that it is a pointer to other instances. A reference defines the role each managed resource plays in an association.

The following figure shows two classes, Teacher and Student. Both classes are linked by the association, TeacherStudent. The TeacherStudent association has two references: Teaches, a property that refers to instances of the Teacher class and TaughtBy, a property that refers to instances of the Student class.

Figure 4–1 An Association Between Teacher and Student

You must delete an association before deleting one of its references. You can add or change the association between two or more objects without affecting the objects.

The Association Methods

The following methods in the CIMClient class return information about associations (relationships) between classes and instances:

Table 4–7 The CIMClient Association Methods


Method	Description
`associators`	Gets the CIM classes or instances that are associated with the specified CIM class or instance.
`associatorNames`	Gets the names of the CIM classes or instances that are associated with the specified CIM class or instance.
`references`	Gets the associations that refer to the specified CIM class or instance.
`referenceNames`	Gets the names of the associations that refer to the specified CIM class or instance.

Specifying the Source Class or Instance

The association methods each take one required argument, CIMObjectPath, which is the name of a source CIM class or CIM instance whose associations or associated classes or instances you want to return. If the CIM Object Manager finds no associations or associated classes or instances, it returns nothing.

If the CIMObjectpath is a class, the association methods return the associated classes and the subclasses of each associated class. If the CIMObjectpath is an instance, the methods return the associated instances and the class from which each instance is derived.

Using the Model Path to Specify an Instance

To specify the name of an instance or class, you must specify its model path. The model path for a class includes the namespace and class name. The model path for an instance uniquely identifies a particular managed resource. The model path for an instance includes the namespace, class name, and keys. A key is a property or set of properties used to uniquely identify managed resource. Key properties are marked with the KEY qualifier.

The model path \\myserver\\Root\cimv2\Solaris_ComputerSystem.Name=mycomputer: CreationClassName=Solaris_ComputerSystem has three parts:

\\myserver\Root\cimv2 – The default CIM namespace on host myserver.
Solaris_ComputerSystem – The name of the class from which the instances is derived.
Name=mycomputer, CreationClassName=Solaris_ComputerSystem – Two key properties in the form key property = value.

Using the APIs to Specify an Instance

In practice, you will usually use the enumInstances method to return all instances of a given class. Then, use a loop structure to iterate through the instances In the loop, you can pass each instance to an association method. The code segment in the following example does the following:

Enumerates the instances in the current class (op) and the subclasses of the current class.
Uses a While loop to cast each instance to a CIMObjectPath (op),
Passes each instance as the first argument to the associators method.

This code example passes null or false values for all other parameters.

Example 4–16 Passing Instances to the associators Method

 {
    ...
    Enumeration e = cc.enumInstances(op, true);
    while (e.hasMoreElements()) {
        op = (CIMObjectPath)e.nextElement();
        Enumeration e1 = cc.associators(op, null, null, 
                null, null, false, false, null);
    ...
    }

Using Optional Arguments to Filter Returned Classes and Instances

The association methods also take the following optional arguments, which filter the classes and instances that are returned. Each optional parameter value passes its results to the next parameter for filtering until all arguments have been processed.

You can pass values for any one or a combination of the optional arguments. You must enter a value for each parameter. The assocClass, resultClass, role, and resultRole arguments filter the classes and instances that are returned. Only the classes and instances that match the values specified for these parameters are returned. The includeQualifiers, includeClassOrigin, and propertyList arguments filter the information that is included in the classes and instances that are returned.

The following table lists the optional arguments to the association methods:

Table 4–8 Optional Arguments to the Association Methods


Argument	Type	Description	Value
`assocClass`	String	Returns target objects that participate in this type of association with the source CIM class or instance. If Null, does not filter returned objects by association.	Valid CIM association class name or Null.
`resultClass`	String	Returns target objects that are instances of the `resultClass` or one of its subclasses, or objects that match the `resultClass` or one of its subclasses.	Valid name of a CIM class or Null.
role	String	Specifies the role played by the source CIM class or instance in the association. Returns the target objects of associations in which the source object plays this role.	Valid property name or Null.
resultRole	String	Returns target objects that play the specified role in the association.	Valid property name or Null.
`includeQualifiers`	Boolean	If true, returns all qualifiers for each target object (qualifiers on the object and any returned properties). If false, returns no qualifiers.	True or False.
includeClassOrigin	Boolean	If true, includes the CLASSORIGIN attribute in all appropriate elements in each returned object. If false, excludes CLASSORIGIN attributes.	True or False.
propertyList	String array	Returns objects that include only elements for properties on this list. If an empty array, no properties are included in each returned object. If NULL, all properties are included in each returned object. Invalid property names are ignored. If you specify a property list, you must specify a non-Null value for `resultClass`.	An array of valid property names. an empty array, or Null.

Examples — `associators` and `associatorNames` Methods

The examples in this section show how to use the associators and associatorNames methods to get information about the classes associated with the Teacher and Student classes shown in the following figure. Notice that the associatorNames method does not take the arguments includeQualifiers, includeClassOrigin, and propertyList because these arguments are irrelevant to a method that returns only the names of instances or classes, not their entire contents.

Figure 4–2 Teacher-Student Association Example

Table 4–9 associators and associatorNames Methods


Example	Output	Description
`associators(Teacher`, `null`, `null`, `null`, `null`, `false`, `false`, `null`)	`Student` class	Returns associated classes and their subclasses.`Student` is linked to `Teacher` by the `TeacherStudent` association.
`associators`(`Student`, `null`, `null`, `null`, `null,false`, `false`, `null`)	`Teacher`, `MathTeacher`, and `ArtTeacher` classes	Returns associated classes and their subclasses. `Teacher` is linked to `Student` by the `TeacherStudent` association. `MathTeacher` and `ArtTeacher` inherit the `TeacherStudent` association from `Teacher`.
`associatorNames`(`Teacher`, `null`, `null`, `null`, `null`)	Name of the `Student` class	Returns the names of the associated classes and their subclasses`Student` is linked to `Teacher` by the `TeacherStudent` association.
`associatorNames`(`Student`, `null`, `null`, `null`, `null`)	`Teacher`, `MatchTeacher`, and `ArtTeacher` class names.	Returns the names of the associated classes and their subclasses. `Teacher` is linked to `Student` by the `TeacherStudent` association. `MatchTeacher` and `ArtTeacher` inherit the `TeacherStudent` association from `Teacher`.

Examples — `references` and `referenceNames` Methods

The examples in this section show how to use the references and referenceNames methods to get information about the associations between the Teacher and Student classes in Figure 4–2. Notice that the referenceNames method does not take the arguments includeQualifiers, includeClassOrigin, and propertyList because these arguments are irrelevant to a method that returns only the names of instances or classes, not their entire contents.

Table 4–10 references and referenceNames Methods


Example	Output	Comments
`references(Student`, `null`, `null`. `false`, `false`, `null`)	`TeacherStudent`	Returns the associations in which `Student` participates.
`references(Teacher`, `null`, `null`. `false`, `false`, `null`)	`TeacherStudent`	Returns the associations in which `Teacher` participates.
`referenceNames(Teacher`, `null`, `null`)	The name of the `TeacherStudent` class.	Returns the names of the associations in which `Teacher` participates.