Chapter 6 Writing Client Applications

This chapter explains how to use the Client Application Programming Interfaces (APIs) to write client applications.

• Overview

• Opening and Closing a Client Connection

• Working with Instances

• Enumerating Objects

• Calling Methods

• Retrieving Class Definitions

• Handling Exceptions

• Advanced Programming Topics

• Sample Programs

For detailed information on the CIM and Client APIs, see the Javadoc reference pages.

Overview

A Web-Based Enterprise Management (WBEM) application is a standard Java program that uses Sun WBEM SDK APIs to manipulate CIM objects. A client application typically uses the CIM API to construct an object (for example, a namespace, class, or instance) and then initialize that object. The application then uses the Client APIs to pass the object to the CIM Object Manager and request a WBEM operation, such as creating a CIM namespace, class, or instance.

Sequence of a Client Application

Sun WBEM SDK applications typically follow this sequence:

1. Connect to the CIM Object Manager - (CIMClient).

   A client application contacts a CIM Object Manager to establish a connection each time it needs to perform a WBEM operation, such as creating a CIM Class or updating a CIM instance.

2. Use one or more APIs to perform some programming tasks.

   Once a program connects to the CIM Object Manager, it uses the APIs to request operations.

3. Close the client connection to the CIM Object Manager - (close).

   Applications should close the current client session when finished. Use the CIMClient interface to close the current client session and free any resources used by the client session.

Example -- Typical Sun WBEM SDK Application

Example 6-1 is a simple application that connects to the CIM Object Manager, using all default values. The program gets a class and then enumerates and prints the instances in that class.

Example 6-1 Typical Sun WBEM SDK Application

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;
 
/**
 * Gets the class specified in the command line (args[1]). Gets the 
 * instances of the class in the namespace specified in the command 
 * line (args[0]).
 */
1	public class WBEMsample {
2    public static void main(String args[]) throws CIMException {
3        CIMClient cc = null;
4        try {
5           /* args[0] contains the namespace. We create
6						  a namespace object (cns) to store the namespace. */
7						  CIMNameSpace cns = new CIMNameSpace(args[0]);
8						  /* Connect to the CIM Object manager and pass it 
9							the namespace object containing the namespace. */
10						cc = new CIMClient(cns);
11						/* args[1] contains the class name. We create a
12						CIM Object Path that references the specified
13					  class in the current namespace. */
14						CIMObjectPath cop = new CIMObjectPath(args[1]);
15						/* Get the class object referenced by the CIM Object
16						Path. */
17						cc.getClass(cop);
18						//Deep enumeration of the class and all its subclasses
19						Enumeration e = cc.enumInstances(cop, true);
20						while(e.hasMoreElements()) {
21								CIMObjectPath op = (CIMObjectPath)e.nextElement();
22								System.out.println(op);
23						}
24        catch (Exception e) {
25            			System.out.println("Exception: "+e);
26       }
27        if(cc != null) {
28           		 cc.close();
29       }
30    }
31 }

Typical Programming Tasks

Once a client application connects to the CIM Object Manager, it uses the API to request operations. The program's feature set determines which operations it needs to request. The typical tasks that most programs perform are:

• Working with instances - creating, deleting, and updating

• Enumerating objects

• Calling methods

• Retrieving class definitions

• Handling errors

In addition, applications may occasionally perform the following tasks:

• Creating namespaces

• Deleting namespaces

• Creating a class

• Deleting a class

• Working with qualifiers

Opening and Closing a Client Connection

The first task an application performs is to open a client session to a CIM Object Manager. WBEM Client applications request object management services from a CIM Object Manager. The client and CIM Object Manager can run on the same hosts or on different hosts. Multiple clients can establish connections to the same CIM Object Manager.

This section describes some basic concepts about namespaces and explains how to use:

• The CIMClient class to connect to the CIM Object Manager

• The close method to close the client connection

Using Namespaces

Before writing an application, you need to understand the CIM concept of a namespace. A namespace is a directory-like structure that can contain other namespaces, classes, instances, and qualifier types. The names of objects within a namespace must be unique. All operations are performed within a namespace. The installation of Solaris WBEM Services creates two namespaces:

• root\cimv2 - Contains the default CIM classes that represent objects on the system on which Solaris WBEM Services is installed. This is the default namespace.

• root\security - Contains the security classes

When an application connects to the CIM Object Manager, it must either connect to the default namespace (root\cimv2) or specify another namespace, for example, root\security or a namespace you created.

Once connected to the CIM Object Manager in a particular namespace, all subsequent operations occur within that namespace. An application can connect to a namespace within a namespace. This is similar to changing to a subdirectory within a directory. Once the application connects to the new namespace, all subsequent operations occur within that namespace.

Connecting to the CIM Object Manager

A client application contacts a CIM Object Manager to establish a connection each time it needs to perform a WBEM operation, such as creating a CIM class or updating a CIM instance. The application uses the CIMClient class to create an instance of the client on the CIM Object Manager. The CIMClient class takes three optional arguments:

• namespace

  The host name and namespace to use for this client connection. The default is root\cimv2 on the local host.

• user name

  The name of a valid Solaris user account. The CIM Object Manager checks the access privileges for this user to determine what type of access to CIM objects is allowed. The default user account is guest.

• password

  The password for this user account. The password must be a valid password for the user's Solaris account. The default password is guest.

Once connected to the CIM Object Manager, all subsequent CIMClient operations occur within the specified namespace.

Examples -- Connecting to the CIM Object Manager

The following examples show two ways of using the CIMClient interface to connect to the CIM Object Manager.

In Example 6-2, the application takes all the default values. That is, it connects to the CIM Object Manager running on the local host (the same host the client application is running on), in the default namespace (root\cimv2), using the default user account and password, guest.

Example 6-2 Connecting to the Default Namespace

/* Connect to root\cimv2 namespace on the local 
host as user guest with password guest
 
cc = new CIMClient();

In Example 6-3, the application connects to namespace A on host happy. The application first creates an instance of a namespace to contain the string name of the namespace (A). Next the application uses the CIMClient class to connect to the CIM Object Manager, passing it the namespace object, user name, and host name.

Example 6-3 Connecting to a Non-Default Namespace

/* Create a namespace object initialized with A 
(name of namespace) on host happy.
CIMNameSpace cns = new CIMNameSpace("happy", A);
 
// Connect to the namespace as user Mary.
cc = new CIMClient(cns, "Mary", "");

Closing a Client Connection

Applications should close the current client session when finished. Use the close method to close the current client session and free any resources used by the client session.

The following sample code closes the client connection. The instance variable cc represents this client connection.

cc.close();

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 6-4 uses the newInstance method to create a Java class representing a CIM instance (for example, a Solaris package) from the Solaris_Package class.

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

 
/*Connect to the CIM Object Manager in the root\cimv2 namespace 
on the local host. */
CIMClient cc = new CIMClient();
 
// Get the Solaris_Package class
cimclass = cc.getClass(newCIMObjectPath("Solaris_Package");
 
/* 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 6-5 connects the client application to the CIM Object Manager and uses the following interfaces to delete all instances of a class:

• CIMObjectPath to construct an object containing the CIM object path of the object to be deleted

• enumInstance to get the instances and all instances of its subclasses

• deleteInstance to delete each instance

Example 6-5 Deleting an Instance (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 java.util.Enumeration;
 
public class DeleteInstances {
		public static void main(String args[]) throws CIMException {
			CIMClient cc = null;
			try {
					/* Construct a namespace object containing the 
					   command line arguments. */
					CIMNameSpace cns = new CIMNameSpace(args[0]);
 
					/* Pass the namespace object to the CIM Object Manager.*/
 				  CIMClient cc = new CIMClient(cns);
 
					/* Construct an object containing the CIM object 
					   path of the object we want to delete. */
 				  CIMObjectPath cop = new CIMObjectPath(args[1]);
 
					/* Do a deep enumeration (deep is set to 
            CIMClient.DEEP) of the instances of the object. A deep 
            enumeration of the instances of a class returns the 
            class instances and all instances of its subclasses. */
					Enumeration e = cc.enumInstances(cop, CIMClient.DEEP);
	    
					// Print the name of each object and delete the instance.
					while(e.hasMoreElements()) {
						CIMObjectPath op = (CIMObjectPath)e.nextElement();
						System.out.println(op);
						cc.deleteInstance(op);
	   		 	}
				}
			catch (Exception e) {
	    			System.out.println("Exception: "+e);
			}
 
  		// If the client connection is open, close it.
			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.

Example -- Getting Instances

The code segment in Example 6-6 lists all processes on a given system. This example uses the enumInstances 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 6-6 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); 
 
/* Pass the CIM Object Path of the CIM_Process class 
to the CIM Object Manager. We want to get instances of this class. */ 
 
CIMObjectPath op = new CIMObjectPath("CIM_Process"); 
 
/* The CIM Object Manager returns a vector of object paths, the names 
of instances of the CIM_Process class. */
Vector v = cc.enumInstances(op, true); 
 
/* Iterate through the vector of instance object paths.
Use the CIM Client getInstance interface to get 
the instances referred to by each object name. */
 
for (int i=0; i < v.size(); i++) {
 
		// Get the instance
		CIMInstance ci = cc.getInstance(v.elementAt(i));
 
		/* Get the process ID string for each instance of 
		CIM_Process. */
		CIMProperty cp = ci.getProperty("Handle");
}

Example -- Getting a Property

Example 6-7 prints the value of the lockspeed property for all Solaris processes. This code segment uses the following methods:

• enumInstances - to get the names of all instances of Solaris processor

• getInstance - to get the instance data for each instance name

• getProperty - to get the value of the lockspeed for each instance

• println - to print the lockspeed value

Example 6-7 Printing Processor Information (getProperty)

/* Connect to the CIM Object Manager as user mary with password 
contrary in the /root namespace on myhost */
{
CIMNameSpace cns = new CIMNamesSpace ("myhost" "/root");
cc = new CIMClient (cns, "/root", "mary", "contrary");
 
// Get names of all instances of Solaris_Processor
Vector op cc.enumInstances("Solaris_Processor")
 
// For each Solaris processor, get its instance data
while (vector has more elements) {
        cn.getNextElement();
        cc.getInstance (cn);
 
// Print the lockspeed of each processor
p = ci.getProperty("lockspeed")
        System.out.println(p.getValue().getValue());
}

Example -- Setting Instances

The code segment in Example 6-8 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 6-8 Setting Instances (setInstance)

{
/* Get instances for each element in a vector, update the 
property value of b to 10 in each instance, 
and pass the updated instance to the CIM Object Manager. */
 
For (int i=0; i(v.size(); i++) {
		CIMInstance ci = cc.getInstance(v.elementAt(i));
		ci.setProperty("b",new CIMValue(10)); 
		cc.setInstance(new CIMObjectPath(),ci); 
 
}

Enumerating Objects

Enumerating objects means getting a list of the names of the objects. 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 Sun WBEM SDK provides APIs for enumerating namespaces, classes, and instances.

The enumeration APIs take two Boolean arguments, deep and shallow. The behavior of these parameters depends upon the particular method being used. A deep enumeration of instances of a class returns the class instances and all instances of its subclasses. A deep enumeration of a class returns all subclasses of the class, but does not return the class itself. A shallow enumeration of the instances of a class returns the instances of that class. A shallow enumeration of a class returns the direct subclasses of that class.

The following examples show how to use the enumeration APIs to enumerate a namespace and a class.

Example -- Enumerating Namespaces

The sample program in Example 6-9 uses the enumNameSpace method in the CIM Client class to print the names of the namespace and all the namespaces contained within the namespace.

Example 6-9 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 CIM Client interface to get a list of the 
  * namespaces within the namespace specified by the CIMObjectPath.
  * 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 and print any exception returned
		catch (Exception e) {
				System.out.println("Exception: "+e);
			}
 
// If the client connection is open, close it.
		if(cc != null) {
            cc.close();
    	}
 
		}
}
 

Example -- Enumerating Classes

A Java GUI application might use the code segment in Example 6-10 to display a list of classes and subclasses to a user. Once the user selects a particular class, the code enumerates the class.

Example 6-10 Enumerating Classes (enumClass)

/* Creates an object containing the path of a CIM object. */
CIMObjectPath (op = new(CIMObjectPath()); 
 
/* Specifies the object path name as A. */
cop.setName("A");	
 
/* Vector returns the object path of the object, classes, and 
all subclasses within those classes. The object path includes the 
namespace, class name, and keys (if the object is an instance). */
 
/* This vector contains the CIM Object Paths to the enumerated
classes. */
Vector v = cc.enumClass(cop, true);  
				 

Calling Methods

Use the invokeMethod method to call a method in a class supported by a provider. To retrieve the signature of a method, an application must first get the definition of the class to which the method belongs. The invokeMethod interface takes four arguments:

The invokeMethod method returns a CIMValue. The return value is null when the method you invoke does not define a return value.

Example -- Calling a Method

The code segment in Example 6-11 gets the instances of the CIM_Service class (services that manage device or software features) and uses the invokeMethod method to stop each service.

Example 6-11 Calling a Method (invokeMethod)

{
 
 
/* Pass the CIM Object Path of the CIM_Service class 
to the CIM Object Manager. We want to get instances of this class. */ 
 
CIMObjectPath op = new CIMObjectPath("CIM_Service"); 
 
/* The CIM Object Manager returns a vector of object paths, the names 
of instances of the CIM_Service class. */
 
Vector v = cc.enumInstances(op, true); 
 
/* Iterate through the vector of instance object paths.
Use the CIM Client getInstance interface to get 
the instances referred to by each object name. */
 
for (int i=0; i < v.size(); i++) {
		
			// Get the instance
		
			CIMInstance ci = cc.getInstance(v.elementAt(i));
 
 		//Invoke the Stop Service method to stop the CIM services.
 
		c.invokeMethod(v.element(i), "StopService", null, null);
	
}
 
}
 

Retrieving Class Definitions

Use the getClass method to get a CIM class.

Example -- Retrieving a Class Definition

The code shown in Example 6-12, uses the following methods to retrieve a class definition:

• CIMNameSpace - to create a new namespace

• CIMClient - to create a new client connection to the CIM Object Manager

• CIMObjectPath - to create an object path, an object to contain the name of the class to retrieve

• getClass - to retrieve the class from the CIM Object Manager

Example 6-12 Retrieving a Class Definition (getClass)

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;
 
/**
 * Gets the class specified in the command line. Works in the default
 * namespace /root/cimv2.
 */
public class GetClass {
    public static void main(String args[]) throws CIMException {
        CIMClient cc = null;
        try {
            CIMNameSpace cns = new CIMNameSpace(args[0]);
 
            cc = new CIMClient(cns);
 
            CIMObjectPath cop = new CIMObjectPath(args[1]);
            cc.getClass(cop);
        }
        catch (Exception e) {
            System.out.println("Exception: "+e);
        }
        if(cc != null) {
            cc.close();
        }
    }
}

Handling Exceptions

Each interface has a throws clause that defines a CIM Exception. An exception is an error condition. The CIM Object Manager uses Java exception handling and creates a hierarchy of WBEM-specific exceptions. The CIMException class is the base class for CIM exceptions. All other CIM exception classes extend from the CIMException class.

Each class of CIM exceptions defines a particular type of error condition that API code handles. See Table 5-2 for a description of the CIM exception APIs.

Using the Try/Catch Clauses

The Client API uses standard Java try/catch clauses to handle exceptions. Generally, an application catches exceptions and either takes some corrective action or passes some information about the error to the user.

The CIM rules are not explicitly identified in the CIM specification. In many cases, they are implied by example. In many cases, the error code refers to a general problem, for example, a data type mismatch, but the programmer must figure out what the correct data type is for the data.

Syntactic and Semantic Error Checking

The MOF Compiler (mofc) compiles .mof text files into Java classes (bytecode). The MOF Compiler does syntactical checking of the MOF files. The CIM Object Manager does semantic and syntactical checking because it can be accessed by many different applications.

The MOF file in Example 6-13 defines two classes, A and B. If you compiled this example file, the CIM Object Manager would return a semantic error because only a key can override another key.

Example 6-13 Semantic Error Checking

Class A         \\Define Class A
 
{     [Key]
int a;  
}  
 
Class B:A       \\Class B extends A 
 
{  [overrides ("c", key (false) ]
int b;   
}
 

Advanced Programming Topics

This section describes advanced programming operations and operations that you would use less frequently.

Creating a Namespace

The installation compiles the standard CIM MOF files into the default namespaces, /root/cimv2 and /root/security. If you create a new namespace, you must compile the appropriate CIM MOF files into the new namespace before creating objects in it. For example, if you plan to create classes that use the standard CIM elements, compile the CIM Core Schema into the namespace. If you plan to create classes that extend the CIM Application Schema, compile the CIM Application into the namespace.

Example -- Creating a Namespace

The code segment in Example 6-14 uses a two-step process to create a namespace within an existing namespace.

• First, it uses the CIMNameSpace method to construct a namespace object. This namespace object contains the parameters to be passed to the CIM Object Manager when the namespace is actually created.

• Second, the example uses the CIMClient class to connect to the CIM Object Manager and pass it the namespace object. The CIM Object Manager creates the namespace, using the parameters contained in the namespace object.

Example 6-14 Creating a Namespace (CIMNameSpace)

{
/*Creates a namespace object on the client, which stores the 
parameters passed to it. args[0] contains the host name (for example,
myhost); args[1] contains the namespace (for example,
the toplevel directory.) */
CIMNameSpace cns = new CIMNameSpace (args[0], args[1]); 
/* Connects to the CIM Object Manager and passes it the 
namespace object (cns) containing the namespace parameters. */
CIMClient cc = new CIMClient (cns);	
/* Passes to the CIM Object Manager another namespace object that 
contains a null string (host name) and args[2], the name of a name 
space (for example, secondlevel). */
CIMNameSpace cop = new CIMNameSpace("", args[2]);
/* Creates a new namespace called secondlevel under the
toplevel namespace on myhost./*
cc.createNameSpace(cop);
}
 

Deleting a Namespace

Use the deleteNameSpace method to delete a namespace.

Example -- Deleting a Namespace

The code segment in Example 6-15 first creates a namespace and then uses the deleteNameSpace method to delete it.

Example 6-15 Deleting a Namespace (deleteNameSpace)

{
/* Creates a namespace object on the client to contain the 
namespace parameters, args[0] (host name) and args[1] 
(namespace name). */ 
 
CIMNameSpace cns = new CIMNameSpace (args[0], args[1]);
 
/* Connects to the CIM Object Manager and passes it 
the namespace object. */
 
CIMClient cc = new CIMClient (cns); 
 
/* Passes the CIM Object Manager a namespace object containing a null
host argument (we are not changing the CIM Object Manager host) and
the name of the namespace to be deleted. */
 
CIMNameSpace cop = new CIMNameSpace("", args[2]); 
 
/* Delete namespace cop. */
 
cc.deleteNameSpace(cop); 									

Creating a Base Class

Applications can create classes using either the MOF language or the client APIs. If you are familiar with MOF syntax, use a text editor to create a MOF file and then use the MOF Compiler to compile it into Java classes. This section describes how to use the client APIs to create a base class.

Use the CIMClass class to create a Java class representing a CIM class. To declare the most basic class, you need only specify the class name. Most classes include properties that describe the data of the class. To declare a property, include the property's data type, name, and an optional default value. The property data type must be an instance of CIMDataType (one of the predefined CIM data types).

A property can have a key qualifier, which identifies it as a key property. A key property uniquely defines the instances of the class. Only keyed classes can have instances. Therefore, if you do not define a key property in a class, the class can only be used as an abstract class.

If you define a key property in a class in a new namespace, you must first compile the core MOF files into the namespace. The core MOF files contain the declarations of the standard CIM qualifiers, such as the key qualifier. For more information on MOF files, see Chapter 3, MOF Compiler.

Class definitions can be more complicated, including such MOF features as aliases, qualifiers, and qualifier flavors.

Example -- Creating a CIM Class

The example in Example 6-16 creates a new CIM class in the default namespace (/root/cimv2) on the local host. This class has two properties, one of which is the key property for the class. The example then uses the newInstance method to create an instance of the new class.

Example 6-16 Creating a CIM Class (CIMClass)

{
/* Connect to the /root/cimv2 namespace 
on the local host and create a new class called myclass */
// Connect to the default namespace on local host.
CIMClient cc = new CIMClient(); 
// Construct a new CIMClass object 
CIMClass cimclass = new CIMClass();
// Set CIM class name to myclass. 
cimclass.setName("myclass"); 
// Construct a new CIM property object
CIMProperty cp = new CIMProperty(); 
// Set property name
cp.setName("keyprop"); 
// Set property type
cp.setType(CIMDatatype.getpredefined(CIMDataType.STRING); 
// Construct a new CIM Qualifier object
CIMQualifier cq = new CIMQualifier(); 
// Set the qualifier name
cq.setName("key"); 
// Add the new key qualifier to the property
cp.addQualfiier(cq); 
/* Create an integer property initialized to 10 */
// Construct a new CIM property object
CIMProperty mp = new CIMProperty(); 
// Set property name to myprop
mp.setName("myprop"); 
// Set property type
mp.setType(CIMDatatype.getpredefined(CIMDataType.INTEGER); 
// Initialize myprop to 10 
mp.setValue(CIMValue.setValue(10));
 
/* Add the new properties to myclass and call the CIM Object Manager 
to create the class. */
// Add the key property to class object
cimclass.addProperty(cp); 
// Add the integer property to class object
cimclass.addProperty(mp); 
 
/* Connect to the CIM Object Manager and pass the new class */
cc.setClass(new CIMObjectPath(),cimclass); 
// Pass the new class to the CIM Object Manager
ci = cc.newInstance(); 
// Create a new CIM instance of myclass
// If the client connection is open, close it.
		if(cc != null) {
            cc.close();
}

Deleting a Class

Use the CIMClient deleteClass method to delete a class. Deleting a class removes the class, its subclasses, and all instances of the class; it does not delete any associations that refer to the deleted class.

Example -- Deleting a Class

The example in Example 6-17 uses the deleteClass interface to delete a class.

Example 6-17 Deleting a Class (deleteClass)

 
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;
 
/**
 * Deletes the class specified in the command line. Works in the default
 * namespace root\cimv2.
 */
public class DeleteClass {
    public static void main(String args[]) throws CIMException {
        CIMClient cc = null;
        try {
            CIMNameSpace cns = new CIMNameSpace(args[0]);
 
            cc = new CIMClient(cns);
 
            CIMObjectPath cop = new CIMObjectPath(args[1]);
            cc.deleteClass(cop);
        }
        catch (Exception e) {
            System.out.println("Exception: "+e);
        }
        if(cc != null) {
            cc.close();
        }
    }
}

Working with Qualifier Types and Qualifiers

A CIM qualifier is an element that characterizes a CIM class, instance, property, method, or parameter. Qualifiers have the following attributes:

• Type

• Value

• Name

In Managed Object Format syntax, each CIM qualifier must have a CIM qualifier type declared in the same MOF file. Qualifiers do not have a scope attribute. Scope indicates which CIM elements can use the qualifier. Scope can only be defined in the qualifier type declaration; it cannot be changed in a qualifier.

The following sample code shows the MOF syntax for a CIM qualifier type declaration. This statement defines a qualifier type named key, with a Boolean data type (default value false), which can describe only a property and a reference to an object. The DisableOverride flavor means that key qualifiers cannot change their value.

Qualifier Key : boolean = false, Scope(property, reference), 
								Flavor(DisableOverride);

The following sample code shows the MOF syntax for a CIM qualifier. In this sample MOF file, key and description are qualifiers for the property test. The property data type is an integer with the value a.

{
[key, Description("test")]
int a
}

Example -- Getting CIM Qualifiers

The code segment in Example 6-18 uses the CIMQualifier class to identify the CIM qualifiers in a vector of CIM elements. The example returns the property name, value, and type for each CIM Qualifier.

A qualifier flavor is a flag that governs the use of a qualifier. Flavors describe rules that specify whether a qualifier can be propagated to derived classes and instances and whether or not a derived class or instance can override the qualifier's original value.

Example 6-18 Getting CIM Qualifiers (CIMQualifier)

	
...
 
    } else if (tableType == QUALIFIER_TABLE) {
		CIMQualifier prop = (CIMQualifier)cimElements.elementAt(row);
		if (prop != null) {
		    if (col == nameColumn) {
			return prop.getName();
		    } else if (col == typeColumn) {
			CIMValue cv = prop.getValue();
			if (cv != null) {
			    return cv.getType().toString();
			} else {
			    return "NULL";			      }
		  } 
 
...
 
 

Example -- Setting CIM Qualifiers

Example 6-19 is a code segment that sets a list of CIM qualifiers for a new class to the qualifiers in its superclass.

Example 6-19 Set Qualifiers (setQualifiers)

   ...
	try 	{
	    	cimSuperClass = cimClient.getClass(new CIMObjectPath(scName));
	    	Vector v = new Vector();
	    	for (Enumeration e = cimSuperClass.getQualifiers().elements();
					e.hasMoreElements();) { 
					CIMQualifier qual = (CIMQualifier)((CIMQualifier)e.nextElement()).clone();
					v.addElement(qual);
	    	}
	    	cimClass.setQualifiers(v);
		} catch (CIMException exc) {
	    	return;
		}
}

Sample Programs

The examples directory contains sample programs that use the client API to perform a function. You can use these examples to start writing your own applications more quickly. The sample programs are described in Chapter 8, Using Sun WBEM SDK Examples.

To run a sample program, type the command:

java program_name

For example, java createNameSpace.