test

Sun WBEM SDK Developer's Guide

Working with Instances

This section describes how to create a CIM instance, delete a CIM instance, and update an instance (get and set the property values of one or more instances).

Creating an Instance

Use the newInstance method to create an instance of an existing class. If the existing class has a key property, an application must set it to a value that is guaranteed to be unique. As an option, an instance can define additional qualifiers that are not defined for the class. These qualifiers can be defined for the instance or for a particular property of the instance and do not need to appear in the class declaration.

Applications can use the getQualifiers method to get the set of qualifiers defined for a class.

Example — Creating an Instance

The code segment in Example 4–6 uses the newInstance method to create a Java class representing a CIM instance (for example, a Solaris package) from the Solaris_Package class.

Example 4–6 Creating an Instance (newInstance())

...
{ 
/*Connect to the CIM Object Manager in the root\cimv2 
namespace on the local host. Specify the username and password of an 
account that has write permission to the objects in the 
root\cimv2namespace. */
 
CIMClient cc = new CIMClient(cns, "root", "root_password");
 
// Get the Solaris_Package class
cimclass = cc.getClass(new CIMObjectPath("Solaris_Package"), true, true, true, null);
 
/* Create a new instance of the Solaris_Package 
 class populated with the default values for properties. If the provider
 for the class does not specify default values, the values of the 
 properties will be null and must be explicitly set. */
 
 ci = cimclass.newInstance();
}
...

Deleting an Instance

Use the deleteInstance method to delete an instance.

Example — Deleting an Instance

The example in Example 4–7 connects the client application to the CIM Object Manager and uses the following interfaces to delete all instances of a class:

Example 4–7 Deleting Instances (deleteInstance)

 
import java.rmi.*;
import com.sun.wbem.client.CIMClient;
import com.sun.wbem.cim.CIMInstance;
import com.sun.wbem.cim.CIMValue;
import com.sun.wbem.cim.CIMProperty;
import com.sun.wbem.cim.CIMNameSpace;
import com.sun.wbem.cim.CIMObjectPath;
import com.sun.wbem.cim.CIMClass;
import com.sun.wbem.cim.CIMException;
import java.util.Enumeration;
 
/**
 * This example program takes four required command-line arguments and 
 * deletes all instances of the specified class and its subclasses. The 
 * running this program must specify the username and password of an
 * account that has write permission to the specified namespace.
 * /
public class DeleteInstances {
    public static void main(String args[]) throws CIMException {
    
		// Initialize an instance of the CIM Client class
		CIMClient cc = null;
	
		// Requires 4 command-line arguments. If not all entered, prints command string.
	
		if(args.length != 4) {
	      System.out.println("Usage: DeleteClass host className username password"); 
	      System.exit(1);
		 }
		 try {
	
				 /**
				  * Creates a name space object (cns), which stores the host name
				  * (args[0]) from the command line.
				  */ 
				 CIMNameSpace cns = new CIMNameSpace(args[0]);
 
				 /** 
				  * Connects to the CIM Object Manager, and passes it the
				  * namespace object (cns) and the username (args[2]) and 
				  * password (args[3]) from the command line. 
				  */
 
				 cc = new CIMClient(cns, args[2], args[3]);
 
				 /**
				  * Construct an object containing the CIM object path
				  * of the class to delete (args[1]) from the command line.
				  */
 
				 CIMObjectPath cop = new CIMObjectPath(args[1]);
	    
				 /**
				  * Get an enumeration of the instance object paths of the 
				  * class and all subclasses of the class. An instance object 
				  * path is a reference used by the CIM Object Manager to locate
          * the instance.
			    */
	     
				 Enumeration e = cc.enumerateInstanceNames(cop);
	    
				 /**
				  * Iterate through the instance object paths in the enumeration.
				  * Construct an object to store the object path of each
				  * enumerated instance, print the instance, and then 
				  * delete it.
				  */
	 
				 while(e.hasMoreElements()) {
				     CIMObjectPath op = (CIMObjectPath)e.nextElement();
					   System.out.println(op);
					   cc.deleteInstance(op);
	    		 }
			} catch (Exception e) {
	    	    System.out.println("Exception: "+e);
			}
			if(cc != null) {
	   	    cc.close();
			}
   }
}

Getting and Setting Instances

An application frequently uses the getInstance method to retrieve CIM instances from the CIM Object Manager. When an instance of a class is created, it inherits the properties of the class it is derived from and all parent classes in its class hierarchy. The getInstance method takes the Boolean argument localOnly. If localOnly is true, getInstance returns only the non-inherited properties in the specified instance. The non-inherited properties are those defined in the instance itself. If localOnly is false, all properties in the class are returned – those defined in the instance and all properties inherited from all parent classes in its class hierarchy.

To create a new instance, use the CIMInstance method in the CIMClass class to create the instance on the local system. Then use the CIMClient.setInstance method to update an existing instance in a namespace or use the CIMClient.createInstance method to add a new instance to a namespace.

Example — Getting Instances

The code segment in Example 4–8 lists all processes on a given system. This example uses the enumerateInstanceNames method to get the names of instances of the CIM_Process class. Running this code on a Microsoft Windows 32 system returns Windows 32 processes. Running this same code on a Solaris system returns Solaris processes.

Example 4–8 Getting Instances of a Class (getInstance)

...
{
//Create namespace cns
CIMnameSpace cns = new CIMNameSpace(); 
 
//Connect to the cns namespace on the CIM Object Manager
cc = new CIMClient(cns, "root", "root_password"); 
 
/* Pass the CIM Object Path of the CIM_Process class 
to the CIM Object Manager. We want to get instances of 
this class. */ 
 
CIMObjectPath cop = new CIMObjectPath("CIM_Process"); 
 
/* The CIM Object Manager returns an enumeration of 
object paths, the names of instances of 
the CIM_Process class. */
Enumeration e = cc.enumerateInstanceNames(cop); 
 
/* Iterate through the enumeration of instance object paths.
Use the CIM Client getInstance class to get 
the instances referred to by each object name. */

while(e.hasMoreElements()) {
    CIMObjectPath op = (CIMObjectPath)e.nextElement();
    // Get the instance. Returns only the properties
		// that are local to the instance (localOnly is true).
		CIMInstance ci = cc.getInstance(op, true);
		}
...

Example — Getting a Property

Example 4–9 prints the value of the lockspeed property for all Solaris processes. This code segment uses the following methods:

Example 4–9 Printing Processor Information (getProperty)

...
{
/* Create an object (CIMObjectPath) to store the name of the
Solaris_Processor class. */ 
 
CIMObjectPath cop = new CIMObjectPath("Solaris_Processor"); 
 
/* The CIM Object Manager returns an enumeration containing the names 
of instances of the Solaris_Processor class and
all its subclasses (cc.DEEP). */
 
Enumeration e = cc.enumInstances(cop, cc.DEEP); 
 
/* Iterate through the enumeration of instance object paths.
Use the getProperty method to get the lockspeed
value for each Solaris processor. */
 
while(e.hasMoreElements()) {
			CIMValue cv = cc.getProperty(e.nextElement(), "lockspeed");
    	System.out.println(cv);
}
...
}

Example — Setting a Property

The code segment in Example — Setting a Property sets a hypothetical lockspeed value for all Solaris processors. This code segment uses the following methods:

Example 4–10 Setting Processor Information (setProperty)

...
{
    /* Create an object (CIMObjectPath) to store the name of the
    Solaris_Processor class. */ 
 
    CIMObjectPath cop = new CIMObjectPath("Solaris_Processor"); 
 
    /* The CIM Object Manager returns an enumeration containing the names 
    of instances of the Solaris_Processor class and
    all its subclasses. */
 
    Enumeration e = cc.enumerateInstanceNames(cop); 
 
    /* Iterate through the enumeration of instance object paths.
    Use the setProperty method to set the lockspeed
    value to 500 for each Solaris processor. */
 
    for (; e.hasMoreElements(); cc.setProperty(e.nextElement(), "lockspeed", 
        new CIMValue(new Integer(500))));
 
...
}

Example — Setting Instances

The code segment in Example 4–11 gets a CIM instance, updates one of its property values, and passes the updated instances to the CIM Object Manager.

A CIM property is a value used to describe a characteristic of a CIM class. Properties can be thought of as a pair of functions, one to set the property value and one to get the property value.

Example 4–11 Setting Instances (setInstance)

...
{
    // Create an object path, an object that contains the
    // CIM name for "myclass"
    CIMObjectPath cop = new CIMObjectPath("myclass"); 
    /* Get instances for each instance object path in an enumeration, 
    update the property value of b to 10 in each instance, 
    and pass the updated instance to the CIM Object Manager. */
    
    while(e.hasMoreElements()) {
		    CIMInstance ci = cc.getInstance(CIMObjectPath)(e.nextElement(), 
                true, true, true, null);
        ci.setProperty("b", new CIMValue(new Integer(10)));
				cc.setInstance(new CIMObjectPath(),ci);
		}
}
...