Implementing a Provider Interface

Providers implement a provider interface that supports the type of service specific to their role. In order to implement the interface, a provider class must first declare the interface in an implements clause, and then it must provide an implementation (a body) for all of the abstract methods of the interface.

The CIM Object Manager communicates with providers using the initialize method. The initialize method takes an argument of type CIMOMhandle, which is a reference to the CIM Object Manager. The CIMOMhandle class contains methods that providers can use to transfer data to and from the CIM Object Manager.

The following table describes the provider interfaces in the com.sun.wbem.provider package. Use the InstanceProvider interface in the com.sun.wbem.provider20 package. You can include a method provider, instance provider, and property provider in a single Java class file, or store each provider in a separate file.

The Instance Provider Interface (InstanceProvider)

The following table describes the methods in the instance provider interface in the Provider package (com.sun.wbem.provider20).

These methods each take the op argument, the CIMObjectPath of the specified CIM class or CIM instance. The object path includes the namespace, class name, and keys (if the object is an instance). The namespace is a directory that can contain other namespaces, classes, instances, and qualifier types. A key is a property that uniquely identifies an instance of a class. Key properties have a KEY qualifier.

For example, the following object path has two parts:

\\myserver\root\cimv2\Solaris_ComputerSystem:Name=mycomputer:   CreationClassName=Solaris_ComputerSystem

• \\myserver\root\cimv2

  The default CIM namespace on host myserver.

• Solaris_ComputerSystem:Name=mycomputer: CreationClassName=Solaris_ComputerSystem

  A specific Solaris Computer System object in the default namespace on host myserver. This Solaris computer system is uniquely identified by two key property values in the format (property=value):

  • Name=mycomputer

  • CreationClassName=Solaris_ComputerSystem

Example — Implementing an Instance Provider

The following example shows the Java source code for an instance provider, SimpleInstanceProvider, that implements the enumInstances and getInstance interfaces for the Ex_SimpleInstanceProvider class. For brevity, this example implements the deleteInstance, createInstance, setInstance, and execQuery interfaces by throwing a CIMException. In practice, an instance provider must implement all InstanceProvider interfaces.

Example 5–1 SimpleInstanceProvider Instance Provider

/*
 * "@(#)SimpleInstanceProvider.java"
 */
import com.sun.wbem.cim.*;
import com.sun.wbem.client.*;
import com.sun.wbem.provider.CIMProvider;
import com.sun.wbem.provider20.InstanceProvider;
import com.sun.wbem.provider.MethodProvider;
import java.util.*;
import java.io.*;

public class SimpleInstanceProvider implements InstanceProvider{
     static int loop = 0;
     public void initialize(CIMOMHandle cimom) throws CIMException {
     }
     public void cleanup() throws CIMException {
     }
     public Vector enumInstances(CIMObjectPath op, boolean deep, CIMClass cc,
            boolean localOnly) throws CIMException {
                return null;
     }
     /*
      * enumInstances:
      * The entire instances and not just the names are returned.
      * Deep or shallow enumeration is possible, however
      * currently the CIMOM only asks for shallow enumeration.
      */
     public Vector enumInstances(CIMObjectPath op, boolean deep, CIMClass cc)
             throws CIMException {
         if (op.getObjectName().equalsIgnoreCase("Ex_SimpleInstanceProvider")) 
             {
             Vector instances = new Vector();
             CIMObjectPath cop = new CIMObjectPath(op.getObjectName(),
                     op.getNameSpace());
                 if (loop == 0){
                     cop.addKey("First", new CIMValue("red"));
                     cop.addKey("Last", new CIMValue("apple"));
                     // To delete this class, comment this following 
	                    // line and compile it.
                     instances.addElement(cop);
                     loop += 1;
                 } else {
                     cop.addKey("First", new CIMValue("red"));
                     cop.addKey("Last", new CIMValue("apple"));
                     // To delete this class, comment this following 
                     // line and compile it.
                     instances.addElement(cop);
                     cop = new CIMObjectPath(op.getObjectName(),
                             op.getNameSpace());
                     cop.addKey("First", new CIMValue("green"));
                     cop.addKey("Last", new CIMValue("apple"));
                     // To delete this class, comment this following 
                     // line and compile it.
                     instances.addElement(cop);
                 }
             return instances;
             }
         return new Vector();
     }

     public CIMInstance getInstance(CIMObjectPath op, 
             CIMClass cc, boolean localOnly) throws CIMException {
             if (op.getObjectName().equalsIgnoreCase("Ex_SimpleInstanceProvider"))
             {
                 CIMInstance ci = cc.newInstance();
                 ci.setProperty("First", new CIMValue("yellow"));
                 ci.setProperty("Last", new CIMValue("apple"));
                 return ci;
             }
            return new CIMInstance();
      }

     public Vector execQuery(CIMObjectPath op, String query, int ql, CIMClass cc)
             throws CIMException {
                 throw(new CIMException(CIMException.CIM_ERR_NOT_SUPPORTED));
    }

     public void setInstance(CIMObjectPath op, CIMInstance ci)
             throws CIMException {
                 throw(new CIMException(CIMException.CIM_ERR_NOT_SUPPORTED));
    }

     public CIMObjectPath createInstance(CIMObjectPath op, CIMInstance ci)
              throws CIMException {
                 throw(new CIMException(CIMException.CIM_ERR_NOT_SUPPORTED));
    }

     public void deleteInstance(CIMObjectPath cp) throws CIMException {
         throw(new CIMException(CIMException.CIM_ERR_NOT_SUPPORTED));
     }
 }

The Property Provider Interface (PropertyProvider)

The following table describes the methods in the property provider interface.

Example — Implementing a Property Provider

The code segment in Example 5–2 creates a property provider (fruit_prop_provider) class that is registered in Example 5–2. The fruit_prop_provider implements the PropertyProvider interface.

This sample property provider illustrates the getPropertyValue method, which returns a property value for the specified class, parent class, and property name. A CIM property is defined by its name and origin class. Two or more properties can have the same name, but the origin class uniquely identifies the property.

Example 5–2 Implementing a Property Provider

...

public class SimplePropertyProvider implements PropertyProvider{
    public void initialize(CIMOMHandle cimom) 
    throws CIMException {
    }

    public void cleanup() 
    throws CIMException {
    }
    
    public CIMValue getPropertyValue(CIMObjectpath op, string originclass, 
	           string PropertyName){
		    if (PropertyName.equals("A")
		        return new CIMValue("ValueA")
  		  else
			      return new CIMValue("ValueB");
    }
    ...
}
 

The Method Provider Interface (MethodProvider)

The following table describes the method in the Method Provider interface.

Example — Implementing a Method Provider

The code segment in Example 5–3 creates a Solaris provider class that routes requests to execute methods from the CIM Object Manager to one or more specialized providers. These specialized providers service requests for dynamic data for a particular type of Solaris object. For example, the Solaris_Package provider services requests to execute methods in the Solaris_Package class.

The method provider in this example implements a single method invokeMethod that calls the appropriate provider to perform one of following operations:

• Reboot a Solaris system

• Reboot or shut down a Solaris system

• Delete a Solaris serial port

Example 5–3 Implementing a Method Provider

...
public class Solaris implements MethodProvider {
    public void initialize(CIMONHandle, ch) throws CIMException {
    }
    public void cleanup() throws CIMException {
    }
    public CIMValue invokeMethod(CIMObjectPath op, String methodName, 
            Vector inParams, Vector outParams) throws CIMException {
        if (op.getObjectName().equalsIgnoreCase("solaris_computersystem")) {
            Solaris_ComputerSystem sp = new Solaris_ComputerSystem();
            if (methodName.equalsIgnoreCase("reboot")) {
                return new CIMValue (sp.Reboot());
            }
        }
        if (op.getObjectName().equalsIgnoreCase("solaris_operatingsystem")) {
            Solaris_OperatingSystem sos = new Solaris_OperatingSystem();
            if (methodName.equalsIgnoreCase("reboot")) {
                return new CIMValue (sos.Reboot());
            }
            if (methodName.equalsIgnoreCase("shutdown")) {
                return new CIMValue (sos.Shutdown());
            }
        }
        if (op.getObjectName().equalsIgnoreCase("solaris_serialport")) {
            Solaris_SerialPort ser = new Solaris_SerialPort();
            if (methodName.equalsIgnoreCase("disableportservice")) {
                return new CIMValue (ser.DeletePort(op));
            }
        }
        return null;
    }
}
...
 

The Associator Provider Interface (AssociatorProvider)

The following table describes the methods in the AssociatorProvider interface. For detailed information about the arguments these methods take, see The Association Methods.

Example — Implementing an Association Provider

A complete association provider must implement all AssociatorProvider methods. For brevity, the code segment in the following example implements only the associators method. The CIM Object Manager passes values for assocName, objectName, role, resultRole, includeQualifiers, includeClassOrigin, and propertyList to the association provider.

Example 5–4 prints the name of a CIM association class and the CIM class or instance whose associated objects are to be returned. This provider handles instances of example_teacher and example_student classes.

Example 5–4 Implementing an Association Provider

public Vector associators(CIMObjectPath assocName,
        CIMObjectPath objectName, String role,
				 String resultRole, boolean includeQualifiers,
				 boolean includeClassOrigin, String propertyList[]) throws CIMException {
    System.out.println("Associators "+assocName+" "+objectName);
	   if (objectName.getObjectName()equalsIgnoreCase("example_teacher")) {
		     Vector v = new Vector();
		     if ((role != null)  &&
		         (!role.equalsIgnoreCase("teaches"))) {
		          // Teachers only play the teaches role.
		          return v;
		     }
		 // Get the associators of a teacher
		 CIMProperty nameProp = (CIMProperty)objectName.getKeys().elementAt(0);
		 String name = (String)nameProp.getValue().getValue();
		 // Get the student class
		 CIMObjectPath tempOp = new CIMObjectPath("example_student");
		 tempOp.setNameSpace(assocName.getNameSpace());
		 CIMClass cc = cimom.getClass(tempOp, false);
    // Test the instance name passed by objectName
    // and return the associated instances of the student class.
  	 if(name.equals("teacher1")) {
		     // Get students for teacher1
		     CIMInstance ci = cc.newInstance();
		     ci.setProperty("name", new CIMValue("student1"));
		     v.addElement(ci.filterProperties(propertyList,
			           includeQualifiers, includeClassOrigin));
		     ci = cc.newInstance();
		     ci.setProperty("name", new CIMValue("student2"));
		     v.addElement(ci.filterProperties(propertyList,
			           includeQualifiers, includeClassOrigin));
		     return v;
		  }
}

Writing a Native Provider

Providers get and set information on managed devices. A native provider is a machine-specific program written to run on a managed device. For example, a provider that accesses data on a Solaris system will most likely include C functions to query the Solaris system. Two common reasons for writing a native provider are:

• Efficiency – You may want to implement a small portion of time-critical code in a lower-level programming language, such as assembly, and then have your Java application call these functions.

• Need to access platform-specific features – The standard Java class library may not support the platform-dependent features needed by your application.

• Legacy code - Often, you have legacy code written in some programming language other than Java and want to continue to use the code with a Java provider.

The Java Native Interface is the native programming interface for Java that is part of the JDK. By writing programs using the JNI, you ensure that your code is completely portable across all platforms. The JNI allows Java code that runs within a Java Virtual Machine (VM) to operate with applications and libraries written in other languages, such as C, C++, and assembly.

For more information on writing and integrating Java programs with native methods, visit the Java web site at http://www.javasoft.com/docs/books/tutorial/native1.1/index.html.