Sun WBEM SDK Developer's Guide

Enumerating Namespaces, Classes, and Instances

An enumeration is a collection of objects that can be retrieved one at a time. The Sun WBEM SDK provides APIs for enumerating namespaces, classes, and instances.

The following examples show how to use the enumeration methods to enumerate namespaces, a classes, and instances.

Deep and Shallow Enumeration

The enumeration methods take a Boolean argument that can have the value deep or shallow. The behavior of deep and shallow depends upon the particular method being used, as shown in Table 4–1.

Table 4–1 Deep and Shallow Enumeration


Method	`deep`	`shallow`
`enumNameSpace`	Returns the entire hierarchy of namespaces under the enumerated namespace.	Returns the first-level children of the enumerated namespace.
`enumClass`	Returns all subclasses of the enumerated class, but does not return the class itself.	Returns the direct subclasses of that class.
`enumInstances`	Returns the class instances and all instances of its subclasses.	Returns the instances of that class

Getting Class and Instance Data

The following enumeration methods return the class and instance data:

enumInstances(CIMObjectPath path, boolean deep, boolean localOnly) – Returns the instances for the class specified in Path. If deep is true, this method returns the instances of the specified class and all classes derived from the class. If shallow is true, this method returns the instances of the specified class.

When an instance of a class is created, it inherits the properties of the class it is derived from and all parent classes in the class hierarchy. If localOnly is true, enumInstances returns only non-inherited properties. If localOnly is false, all properties in the class are returned.
enumClass(CIMObjectPath path, boolean deep, boolean localOnly) – Returns the classes (the entire class not just the name of the class) for the class specified in Path. If deep is true, this method returns all classes derived from the enumerated class. If shallow is true, this method returns only the first-level children of the enumerated class.

When a class is created, it inherits the methods and properties of the class it is derived from and all parent classes in the class hierarchy. If localOnly is true, this method returns only non-inherited properties and methods. If localOnly is false, all properties in the class are returned.

Getting Class and Instance Names

CIM WorkShop is an example of an application that uses enumeration methods to return the names of classes and instances. Once you get a list of object names, you can get the instances of that object, its properties, or other information about the object.

The following enumeration methods return the names of the enumerated class or instance:

enumerateInstanceNames(CIMObjectPath path) — Returns the names of the instances for the specified class.
enumerateClassNames(CIMObjectPath path, boolean deep) — Returns the names of the classes for the class specified in Path. If deep is true, this method returns the names of all classes derived from the enumerated class. If shallow is true, this method returns only the names of the first-level children of the enumerated class.

Example — Enumerating Namespaces

The sample program in Example 4–12 uses the enumNameSpace method in the CIMClient class to print the names of the namespace and all the namespaces contained within the namespace.

Example 4–12 Enumerating Namespaces (`enumNameSpace`)

 
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 java.util.Enumeration;
 
/ **
  * This program takes a namespace argument and calls the 
  * enumNameSpace CIMClient interface to get a list of the 
  * namespaces within the namespace specified by the CIMObjectPath,
  * (cop) and all the namespaces contained in the namespace
  * (CIMClient.DEEP).  The program then prints the name of the specified 
  * namespace (CIMClient.SHALLOW).
 /**
 
public class EnumNameSpace {
 
    // EnumNameSpace takes a string of arguments
    public static void main (String args[ ]) {
		    CIMClient cc = null;
 
			  try {    
			      // Create a namespace object for the namespace passed as an argument
			      CIMNameSpace cns = new CIMNameSpace(args[0], "");
 
			      // Connect to the CIM Object Manager in the namespace passed as an argument
			      CIMClient cc = new CIMClient(cns);
 
			      // Create an object path to store the namespace name on the current host
			      CIMObjectPath cop = new CIMObjectPath("",args[1]);
 
			      // Enumerate the namespace and all namespaces it contains 
            // (deep is set to CIMClient.DEEP)
			      Enumeration e = cc.enumNameSpace(cop, CIMClient.DEEP);
 
			      // Iterate through the list of namespaces and print each name.
			      for (; e.hasMoreElements();
						    System.out.println(e.nextElement()));
						    System.out.println("++++++");
			      // Iterate through the list of namespaces (CIMClient.SHALLOW) and 
            // print each name.
			      e = cc.enumNamesSpace(cop, CIMClient.SHALLOW);
			      for (; e.hasMoreElements();
					      System.out.println(e.nextElement()));
	       } catch (Exception e) {
				    System.out.println("Exception: "+e);
			   }
         // If the client connection is open, close it.
		     if(cc != null) {
            cc.close();
         }
     }
}

Example — Enumerating Class Names

A Java GUI application might use the code segment in Example 4–13 to display a list of classes and subclasses to a user.

Example 4–13 Enumerating Class Names (`enumClass`)

...
{
    /* Creates a CIMObjectPath object and initializes it 
    with the name of the CIM class to be enumerated (myclass). */
    CIMObjectPath cop = new CIMObjectPath(myclass); 
    
    /* This enumeration contains the names of the classes and subclasses
    in the enumerated class. */
    Enumeration e = cc.enumClass(cop, cc.DEEP);
}
...

An application might use the code segment in Example 4–14 to display the contents of a class and its subclasses.

Example 4–14 Enumerating Class Data (`enumClass`)

...
{
    /* Creates a CIMObjectPath object and initializes it 
    with the name of the CIM class to be enumerated (myclass). */
     
    CIMObjectPath cop = new CIMObjectPath(myclass); 
     
    /* This enumeration contains the classes and subclasses
    in the enumerated class (cc.DEEP). This enumeration
    returns only the non-inherited methods and properties 
    for each class and subclass (localOnly is true).*/
 
    Enumeration e = cc.enumClass(cop, cc.DEEP, true);  
}
...

The sample program in Example 4–15 does a deep and shallow enumeration of classes and instances. This example also shows the use of the localOnly flag to return class and instance data, instead of returning the names of the classes and instances.

Example 4–15 Enumerating Classes and Instances

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 enumerates classes and instances. It does 
 * a deep and shallow enumeration of a class that is passed 
 * from the command line. It uses the localOnly flag to return 
 * class and instance details. 
 */
 public class ClientEnum {
     public static void main(String args[]) throws CIMException {
		     CIMClient cc = null;
			   CIMObjectPath cop = null;
			   if(args.length != 2) {
				     System.out.println("Usage: ClientEnum host className"); 
				     System.exit(1);
	    		 }
			   try {
				    // Create a CIMNameSpace object that contains the 
				    // hostname (args[0] from the command line).
	    		    CIMNameSpace cns = new CIMNameSpace(args[0]);
 
				    // Creates a client connection to the CIM Object Manager
				    // on the specified host (args[0]).
	    		    cc = new CIMClient(cns);
 
	    		    // Get the class name from the command line
	    		    cop = new CIMObjectPath(args[1]);
 
	    		    // Do a deep enumeration of the class, which
				    // returns the class names.
	    		    Enumeration e = cc.enumClass(cop, cc.DEEP);
 
	    		    // Print the names of all subclasses of the enumerated class.
	    		    for (; e.hasMoreElements(); System.out.println(e.nextElement()));
	    		        System.out.println("+++++");
 
	    		    // Do a shallow enumeration of the class, which
				    // returns the class names.
	    		    e = cc.enumClass(cop, cc.SHALLOW);
 
	    		    // Prints the names of the first-level subclasses.
	    		    for (; e.hasMoreElements(); System.out.println(e.nextElement()));
	    		        System.out.println("+++++");
 
	    		    // Do a shallow enumeration of the class, which
				    // returns the class data, not just the class
				    // name (localOnly is true).
	    		    e = cc.enumClass(cop, cc.SHALLOW, true);
 
	    		    // Prints the details of the first-level subclasses.
	    		    for (; e.hasMoreElements(); System.out.println(e.nextElement()));
	    		        System.out.println("+++++");
 
				    // Do a deep enumeration of the instances of the class, which
				    // returns the names of the instances.
	    		    e = cc.enumInstances(cop, cc.DEEP);
 
	    		    // Prints the names of all instances of the class and its subclasses.
	    		    for (; e.hasMoreElements(); System.out.println(e.nextElement()));
	    		        System.out.println("+++++");
 
				    // Do a deep enumeration of the instances of the class, which
				    // returns the actual instance data, not just the instance
				    // name. (localOnly is true).
	    		    e = cc.enumInstances(cop, cc.DEEP);
 
	    		    // Prints the details of the instances of the class and its subclasses.
	    		    for (; e.hasMoreElements(); System.out.println(e.nextElement()));
	    		        System.out.println("+++++");
 
				    // Do a shallow enumeration of the instances of the class,
				    // which returns the names of the instances.
	    		    e = cc.enumInstances(cop, cc.SHALLOW);
 
				    // Prints the names of the instances of the class.
	    		    for (; e.hasMoreElements(); System.out.println(e.nextElement()));
	    			      System.out.println("+++++");
			      } catch (Exception e) {
	    		        System.out.println("Exception: "+e);
			     }
			    // close session.
			    if(cc != null) {
	    		    cc.close();
			    }
    }
}