Sun WBEM SDK Developer's Guide

Chapter 3 Application Programming Interfaces

The Sun WBEM SDK applications request information or services from the Common Information Model (CIM) Object Manager through the application programming interfaces (APIs). This chapter describes the following topics.

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

About the APIs

The APIs represent and manipulate CIM objects. These APIs represent CIM objects as Java classes. An object is a computer representation or model of a managed resource, such as a printer, disk drive, or CPU. Because the CIM Object Manager enforces the Common Information Model (CIM) 2.2 Specification, the objects you model using the APIs conform to standard CIM objects.

Programmers can use these interfaces to describe managed objects and retrieve information about managed objects in a particular system environment. The advantage of modeling managed resources using CIM is that those objects can be shared across any system that is CIM compliant.

The API Packages

The API can be grouped into three categories:

CIM API – Common classes and methods that applications use to represent all basic CIM elements. The CIM APIs create objects on the local system.
Client API – Methods that applications use to transfer data to and from the CIM Object Manager. The Client APIs transfer objects that have been created on the local system to the CIM Object Manager.
Provider API – Interfaces that the CIM Object Manager and object provider use to communicate with each other

CIM API Package (`com.sun.wbem.cim`)

The following table describes the interfaces in the CIM API package.

Table 3–1 CIM Classes


Class	Description
`CIMClass`	A CIM class, an object representing a collection of CIM instances, all of which support a common type (for example, a set of properties and methods). This interface creates a template that fills in the required CIM values for the group of objects you are creating.
`CIMDataType`	The CIM data types (as defined by the CIM specification).
`CIMDateTime`	The CIM date and time representation.
`CIMElement`	A CIM element. This is the base class for managed system elements.
`CIMFlavor`	A CIM qualifier flavor, a characteristic of a qualifier that describes 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.
`CIMInstance`	A unit of CIM data. Use this interface to describe a managed object that belongs to a particular class. Instances contain actual data.
`CIMMethod`	A declaration containing the method name, return type, and parameters.
`CIMNameSpace`	A CIM namespace, a directory-like structure, that can contain other namespaces, classes, instances, qualifier types, and qualifiers.
`CIMObjectPath`	A path name of a CIM object. The object names have two parts: namespace and a model path. The model path uniquely identifies an object in the namespace.
`CIMParameter`	A CIM parameter, a value passed to a CIM method from a calling method.
`CIMProperty`	A value that characterizes an instance of a CIM class. Properties can be thought of as a pair of functions, one to set the property value, and one to return the property value. A property has a name and one domain, the class that owns the property.
`CIMQualifier`	A modifier that describes a class, instance, method, or property. Use this class to modify an attribute of a managed object, for example, add read-only access to a disk. There are two categories of qualifiers: those defined by the Common Information Model (CIM) and those defined by developers.
`CIMQualifierType`	A CIM qualifier type, a template for creating CIM qualifiers.
`CIMScope`	A CIM scope, a qualifier attribute that indicates the CIM objects with which the qualifier can be used. For example, the qualifier ABSTRACT has Scope(Class Association Indication), meaning that it can only be used with classes, associations, and indications.
`CIMValue`	A CIM value, a value that can be assigned to properties, references, and qualifiers. CIM values have a data type (`CIMDataType`) and the actual value(s).
`UnsignedInt8`	An unsigned 8-bit integer.
`UnsignedInt16`	An unsigned 16-bit integer.
`UnsignedInt32`	An unsigned 32-bit integer.
`UnsignedInt64`	An unsigned 64-bit integer.

Exception Classes

The Exception classes represent the error conditions that can occur in Sun WBEM SDK classes. The CIMException class is the base class for CIM exceptions. All other CIM exception classes extend from the CIMException class.

The following table describes the CIM exception classes.

Table 3–2 Exception Classes


Class	Description
`CIMClassException`	A semantic exception that occurs in a CIM class. The MOF Compiler (`mofc`) uses this class to handle semantic errors found during compilation.
`CIMException`	Exceptional CIM conditions. This is the base class for CIM exceptions.
`CIMInstanceException`	Semantic exceptions that occur in a CIM instance.
`CIMMethodException`	Semantic exceptions that occur in a CIM method.
`CIMNameSpaceException`	Semantic exceptions that occur in a CIM namespace.
`CIMPropertyException`	Semantic exceptions that occur in a CIM property.
`CIMProviderException`	Exceptional conditions that can occur in the CIM Object Manager's providers.
`CIMQualifierTypeException`	Exceptional conditions that can occur in a CIM qualifier type.
`CIMRepositoryException`	Exceptional conditions that can occur in the CIM repository.
`CIMSemanticException`	Semantic exceptions that can occur in a CIM element. These exceptions are generally thrown when the CIM Object Manager tries to add, modify, or delete a CIM element and encounters situations that are illegal according to the CIM Specification.
`CIMTransportException`	Exceptional conditions that occur in the CIM transport interfaces (RMI and XML).

Client API Package (`com.sun.wbem.client`)

The Client API package contains classes and methods that transfer data between applications and the CIM Object Manager. Applications use the CIMClient class to connect to the CIM Object Manager, and they use the methods in the CIMClient class that are listed in the following table to transfer data to and from the CIM Object Manager.

Table 3–3 Client 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.
`close`	Close the client connection to the CIM Object Manager. This interface frees resources used for the client session.
`createClass`	Adds the CIM class to the specified namespace.
`createInstance`	Creates the specified instance if it does not exist. If the CIM instance already exists, throws `CIMInstanceException` with ID `CIM_ERR_ALREADY_EXISTS`.
`createNameSpace`	Creates a CIM namespace, a directory containing classes and instances. When a client application connects to the CIM Object Manager, it specifies a namespace. All subsequent operations occur within that namespace on the CIM Object Manager host
`createQualifierType`	Adds the specified CIM qualifier type to the specified namespace.
`deleteNameSpace`	Deletes the specified namespace on the specified host.
`deleteClass`	Deletes the specified class.
`deleteInstance`	Deletes the specified instance.

`enumClass(CIMObjectPath path,` `boolean deep)`	Enumerates the class specified by `Path`. This method returns the name of each class, not the class contents, as an enumeration of `CIMObjectPath` objects. If set to `deep`, the enumeration contains the names of all classes derived from the enumerated class. If set to `shallow`, the enumeration contains only the names of the first-level childeren of the enumerated class.
`enumClass(CIMObjectPath path,` `boolean deep, boolean localonly`)	Enumerates the class specified by `Path`. This method returns the entire class contents, not just the class name, as an enumeration of `CIMClass` objects. If set to `deep`, returns the classes derived from the enumerated class. If set to `shallow`, returns only the first-level children of the enumerated class. If `localOnly` is true, only the non-inherited properties and methods are returned. Otherwise, all proeprties and methods are returned.
`enumInstances(CIMObjectPath path`, `boolean deep`)	Enumerates the instances in the class specified by `path`. Returns the names of the instances for the class specified by `path` as an enumeration of `CIMObjectPath` objects. If `deep` is true, returns the names of all instances of the specified class and all classes derived from the class. Otherwise, returns only the names of instances belonging to the specified class.
`enumInstances(CIMObjectPath path,` `boolean deep, boolean localOnly)`	Enumerates the instances in the class specified by `path`. Returns the instances (the entire instance not just the name of the instance) for the specified class as an enumeration of `CIMInstance` objects.
`enumNameSpace`	Gets a list of namespaces.
`enumQualifierTypes`	Gets a set of qualifier types for the specified class or classes.
`execQuery(CIMObjectPath relNS`, `java.lang.String query, int ql)`	Returns an enumeration of instances containing properties that match the property value specified in the query, using the query language specified by ql. Currently, only WBEM Query Language (WQL) is supported. The query language maps the CIM object model to SQL tables.
`getClass`	Gets the CIM class for the specified CIM object path.
`getInstance`	Gets the CIM instance for the specified CIM object path.
`getProperty`	Returns the value of the specified property.
`getQualifierType`	Gets the qualifier type for the specified CIM object path.
`invokeMethod`	Executes the specified method on the specified object. A method is a declaration containing the method name, return type, and parameters in the method.
`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.
`setClass`	Updates the specified CIM class if it exists. Returns an error if the CIM class does not exist.
`setInstance`	Updates the specified CIM instance if it exists. Returns an error if the CIM instance does not exist.
`setProperty`	Sets the specified property to the specified value.

The following table describes the interfaces provided in the com.sun.wbem.client package.

Table 3–4 Interfaces in the com.sun.wbem.client Package


Interface	Description
`CIMOMHandle`	Provides to clients a reference to the CIM Object Manager. This interface contains methods that clients can use to transfer data to and from the CIM Object Manager.
`ProviderCIMOMHandle`	Provides to providers a reference to the CIM Object Manager. This interface contains methods that providers can use to transfer data to and from the CIM Object Manager.

The following table describes the methods in the ProviderCIMOMHandle Interface.

Table 3–5 Methods in the ProviderCIMOMHandle Interface


Method	Description
`decryptData`	Decrypts the specified string value using the authentication sessionkey, if the value is encrypted.
`getCurrentAuditId`	Returns a usually unique identifier for the session to be used in auditing records to identify the remote client connection
`getCurrentRole`	Returns the current role assumed by the current authenticated user.
`getCurrentUser`	Returns the current user on whose behalf the provider has been invoked.
`getInternalProvider`	Returns a reference to an internal instance provider, which can be used to store static instance information for the provider.

Provider API Package

The Provider API packages (com.sun.wbem.provider) and (com.sun.wbem.provider20) contain the provider interfaces that the CIM Object Manager and object providers use to communicate with each other. Providers can use these interfaces to provide the CIM Object Manager dynamic data.

When an application requests dynamic data from the CIM Object Manager, the CIM Object Manager uses these interfaces to pass the request to the provider. Providers are classes that perform the following functions in response to a request from the CIM Object Manager:

Map information from a managed device to CIM Java classes
- Get information from a device
- Pass the information to the CIM Object Manager in the form of CIM Java classes

Map the information from CIM Java classes to managed device format
- Get the required information from the CIM Java class
- Pass the information to the device in native device format

The following table describes the interfaces in the Provider package.

Table 3–6 com.sun.wbem.provider Interfaces


Interface	Description
`CIMProvider`	Base interface implemented by all providers.
`InstanceProvider`	Interface implemented by instance providers. Instance providers serve dynamic instances of classes. This is a deprecated interface. Use the `InstanceProvider` interface in `com.sun.wbem.provider20` instead.
`MethodProvider`	Interface implemented by method providers, which provide implementation for all methods of CIM classes.
`PropertyProvider`	Interface implemented by property providers, which are used to retrieve and update dynamic properties. Dynamic data is not stored in the CIM Object Manager Repository.

The following table describes the interfaces in the com.sun.wbem.provider20 package.

Table 3–7 com.sun.wbem.provider20 Interfaces


Interface	Description
`AssociatorProvider`	Interface implemented by providers of dynamic associations.
`Authorizable`	Maker interface implemented by providers that handle authorization checking instead of relying on the CIM Object Manager to check user authorizations.
`InstanceProvider`	Interface implemented by instance providers. Instance providers serve dynamic instances of classes.