Part II Sun WBEM SDK

The Sun WBEM SDK is a software developer's tool kit that includes components needed to write Java management applications that can communicate with any WBEM-enabled management device. Developers can also use this tool kit to write providers, programs that communicate with managed objects to access data.

Chapter 2 Installing the Sun WBEM SDK

This section describes the Sun WBEM SDK and explains how to install and remove it from your system. Topics covered include the following:

• About the Sun WBEM SDK

• Installation Prerequisites

• Installing the Sun WBEM SDK

• Getting Started with the Sun WBEM SDK

• Removing the Sun WBEM SDK

About the Sun WBEM SDK

Sun WBEM SDK is a software developer's tool kit you can use to develop applications that can run in WBEM environments. You can also develop providers, programs that communicate between WBEM components and the CIM Object Manager, to run on the Java platform in any WBEM-enabled environment.

Providers must be started on a computer running the CIM Object Manager. For Sun WBEM SDK version 1.0, the CIM Object Manager is not supported in the Windows environment. Consequently, the Sun WBEM SDK is not recommended for the development of providers for the Microsoft Windows 32-bit operating system.

Sun WBEM SDK includes the following components:

• CIM WorkShop

• Client API

• Provider API

• MOF Compiler

• Sample client programs

• Sample provider programs

• User documentation

  • This guide

  • Javadoc for Client and Provider API

CIM WorkShop

CIM WorkShop is a software application in which you can view CIM classes and instances, create new CIM subclasses and instances, and add or delete new properties, methods, and qualifiers of subclasses. For information about how to use CIM WorkShop, see Chapter 4, CIM WorkShop.

Client API

The Client Application Programming Interface (API) is a public API that Java applications use to request operations from the CIM Object Manager. For a complete list and description of the Client API, see Chapter 5, Application Programming Interfaces.

Provider API

Provider APIs are 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 a particular kind of 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 that registered to be the provider. For a description of the Provider API, see Chapter 5, Application Programming Interfaces.

MOF Compiler

The Managed Object Format (MOF) is a standard text format for representing CIM data. Products developed according to the CIM specification must be able to exchange information in MOF format.

The Sun WBEM SDK software uses a MOF Compiler (mofc) to convert a MOF text file to Java classes. Internally, Sun WBEM SDK uses Java classes to represent CIM data.

The MOF language defines a syntax for defining CIM classes and instances. MOF provides developers and administrators with a simple and fast technique for modifying the CIM Object Manager Repository.

Sample Client Programs

The Sun WBEM SDK provides sample Java programs that use the Client APIs. These programs are installed in /opt/SUNWconn/wbem/demo. You can run the sample client programs and use them to build your own applications. For information about the sample client programs, see "Using Client Examples" in the chapter, "Using Sun WBEM SDK Examples."

Sample Provider Programs

Sample provider programs use the Provider APIs. You can use these programs to develop providers that extend CIM capabilities into your specific technology. For example, you can develop a provider that enables your technology to communicate with the CIM Object Manager. For information about the sample provider programs, see "Using the Provider Examples" in the chapter, "Using Sun WBEM SDK Examples."

Documentation

This guide and the Javadoc reference pages are provided as part of Sun WBEM SDK.

Installation Prerequisites

Prior to installing the Sun WBEM SDK kits, the Java Development Kit (JDK) version 1.1.7_05 or a compatible version must be installed on the server designated to run the CIM Object Manager.

Shared Packages

You can install Sun WBEM SDK as a product that runs on its own, or you can install both Sun WBEM SDK and Solaris WBEM Services to be used interactively. Installing either product involves installing the product packages. The packages are compilations of the files, interfaces, and components of each product.

Sun WBEM SDK and Solaris WBEM Services share some of the same packages. For example, both applications require the package named SUNWwbapi, that contains the Client APIs.

For information about Sun WBEM SDK packages and installation instructions, see the following section, "Installing the Sun WBEM SDK". For information about Solaris WBEM Services packages and installation instructions, see the following section, "Installing Solaris WBEM Services" in Chapter 10, Installing Solaris WBEM Services.

Installing the Sun WBEM SDK

The following table describes the packages you need to install Sun WBEM SDK.

How to Install Sun WBEM SDK

1. Become root on your system by typing the following command:

   % su

2. Type the root password when you are prompted.

3. Change directories to the location of the packages in your work environment.

4. At the system prompt, type the following command to obtain a list of packages:

   # pkgadd -d .

   The list of packages is displayed. You are prompted to select one or all packages.

5. Type the number of the package you want to install.

   • Type 1 to install the SUNWwbapi package. It is important to install this package first because the other packages rely on the Sun WBEM APIs.

   • Type 5 to install the SUNWwbdev package, which installs the Sun WBEM SDK.

   • (Optional): Type 3 to install the SUNWwbdoc package, which installs this guide.

   As each package installs, its contents are listed for you to view. When the installation is complete, you are notified with the message: Installation of package_name was successful.

6. When you have finished installing the packages, type q to exit the package installation routine.

7. Type exit at the system prompt to exit root.

Getting Started with Sun WBEM SDK

After you finish installing the Sun WBEM SDK, you can use the product components. Getting started entails completing tasks that you will use on a daily basis, including the following:

• "Starting CIM WorkShop"

• "Compiling a MOF File"

• "Restarting the CIM Object Manager"

Uninstalling the Sun WBEM SDK

When you want to uninstall the Sun WBEM SDK from your computer, you remove the packages. When you remove the Sun WBEM SDK packages, not all files that make up your total installation are removed. If Solaris WBEM Services is installed, none of its associated packages are removed. For information about removing Solaris WBEM Services, see Chapter 10, Installing Solaris WBEM Services.

After you remove both the Sun WBEM SDK and Solaris WBEM Services, the LDAP schema and data files remain installed. You can remove these files, and the subdirectories that contain them, from the path /opt/SUNWconn/ldap. However, if you remove the LDAP data, you may encounter errors in other applications that require the data. Also, if you remove the LDAP data, you will need to re-install it if you decide to re-install the Sun WBEM SDK or Solaris WBEM Services at a later date.

How to Uninstall the Sun WBEM SDK

1. Become root on your system by typing the following command:

   % su

2. Type the root password at the Password prompt.

3. Type the following command at the system prompt to remove a package:

   # pkgrm package_name

   where package_name is replaced by the name of the package that you want to remove.

4. Type y when you are prompted with the question: "Do you want to remove this package?"

   You can remove the following packages in any order:

   • SUNWwbdev

   • SUNWwbdoc

   Be sure to remove the SUNWwbapi package last because all other packages rely on it.

   When a package has been removed successfully, the following message is displayed.

   Removal of package_name was successful

5. Type the pkgrm command at the system prompt for each package you want to remove.

6. Type exit to exit root and return to your system prompt when you have finished removing packages.

Chapter 3 MOF Compiler

This chapter describes the MOF Compiler and explains how to use it. The following topics are covered.

• About the MOF Compiler

• Compiling a MOF File

About the MOF Compiler

The MOF Compiler parses files created in Managed Object Format, converts files to Java classes, and stores the extracted classes and instances in the CIM Repository.

MOF Compiler Location

During installation, the MOF Compiler is provided in the SUNWwbmof package. After installation, the MOF Compiler is located in the following path: /opt/SUNWconn/wbem/bin/.

MOF Compiler Parameters

The mofcomp command uses the following command-line parameters.

Syntax of the MOF Compiler

The MOF Compiler uses the following command syntax:

% mofcomp filename.mof

where mofcomp is the command to run the MOF Compiler and filename.mof is the name of a MOF file to be compiled.

Security Advisory for Using Passwords

If you run a command with the -p or the -up parameters, and you include a password, another user can run the ps command or the history command to find out your password.

If you run a command that requires you to provide your password, immediately change your password after running the command.

Example 3-1 Example of Unsafe Syntax

The following examples show use of the mofcomp command with the -p parameter:

mofcomp -p Log8Rif

mofcomp -up molly Log8Rif

Change your password immediately after running the mofcomp command with the option to specify a password.

Compiling a MOF File

Using the MOF Compiler, you can compile all MOF files with or without a .mof extension. You can start the compiler in any directory where you want to compile a file. All MOF files that make up the CIM and Solaris Schemas are located in the path: /opt/SUNWconn/wbem/schema.

How to Compile a MOF File

1. Change directories to the location of the MOF Compiler.

   % cd /opt/SUNWconn/wbem/bin/

2. To run the MOF Compiler without parameters, type the following command:

   % mofcomp <filename>

   At the prompt, type the path and name of the MOF file that you want to compile.

   For example, type: /opt/SUNWconn/wbem/schema/Solaris_Schema1.0.mof

   The MOF file is compiled.

Example of MOF Output

The following example shows MOF output after compiling the file:

Example 3-2 Sample MOF Output

Initializing CIMValue
Parsing input file
Parsing input file
Parsed input file
MofcBackend:
NamespaceTable:
{}End of NamespaceTable
QualifierTypesTable:
{}End of QualifierTypesTable
Syntax Errors: 0
Semantic Errors: 0
Warnings: 0
End of MofcBackend

Chapter 4 CIM WorkShop

This chapter explains how to use CIM WorkShop to add new properties, methods, and qualifiers to the classes and instances that you create, and to set the scope and flavor of new qualifiers for new classes and instances. The following topics are covered:

• About CIM WorkShop

• Starting CIM WorkShop

• Navigating in CIM WorkShop

• Viewing Class Characteristics

• Working in Namespaces

• Working with Classes

• Adding a Class

• Deleting Classes and Their Attributes

• Working with Instances

• Reference: CIM WorkShop Windows and Dialog Boxes

About CIM WorkShop

CIM WorkShop provides a graphical user interface in which you can view and create classes and instances. In CIM WorkShop, you can complete any of the following tasks:

• View and select namespaces

• Add namespaces

• View and create classes

• Add properties, qualifiers, and methods to new classes

• View and create instances

• View and modify instance values

CIM guidelines prevent you from modifying or editing the properties, methods, or qualifiers of CIM Schema or Solaris Schema classes. However, you can create new classes and instances of classes. When you create a new class or instance, you can add or delete properties, methods, and qualifiers. You can also change the values, including the scope and flavor, of new qualifiers that you create for a new class, instance, property, or method. You cannot change the values of inherited properties, methods, or qualifiers.

Starting CIM WorkShop

CIM WorkShop is available as part of the Sun WBEM SDK.

The CIM Object Manager must be installed to run CIM WorkShop. During an installation of Solaris WBEM Services and Sun WBEM SDK in the Solaris operating environment, the CIM Object Manager runs on the local host. If you install only the Sun WBEM SDK, you must point to a host on which the CIM Object Manager already has started. You can enter this information in the Host field of the Login dialog box that is displayed when you start CIM WorkShop. For information about the CIM WorkShop dialog boxes and fields, see "Reference: CIM WorkShop Window and Dialogs".

How to Start CIM WorkShop

1. Start the CIM WorkShop:

   • If you have installed Solaris WBEM Services and Sun WBEM SDK in the Solaris operating environment, type the following command at the system prompt:

     % /opt/SUNWconn/wbem/bin/cimworkshop &

   • If you have installed the Sun WBEM SDK in the Microsoft Windows environment, click Start->Programs->WBEM SDK->CIM Workshop.

   The CIM WorkShop window is displayed, followed by the Login dialog box. The Login dialog box shows the name of the host computer on which CIM Workshop is installed and the path of the default namespace, root\cimv2. Context Help, information about how to complete the dialog box, is displayed in the right side of the Login dialog box. When you click a field, the help content changes to reflect how to enter information into the field and the significance of the field.

2. In the CIM WorkShop login dialog box, do the following:

   • In the Host Name field, type the name of a host running the CIM Object Manager.

     ---

     Note -

     By default, CIM WorkShop connects to the CIM Object Manager on the local host, in the default namespace, root\cimv2. If you start CIM WorkShop as part of the WBEM SDK in the Solaris operating environment or in the Microsoft Windows environment, you need to provide the name of a host that is already running a CIM Object Manager.

     ---

   • In the Namespace field, click in the field and type the name of the namespace that you want to use, or retain the name of the default namespace.

   • In the User Name field, type the user name you generally use for system and networking privileges.

   • In the Password field, type the password you generally use for system and networking privileges.

     ---

     Note -

     If you do not specify a user name and password, you can log in using the default user account, guest. Guest privileges are read-only. Your CIM Object Manager administrator can set up write privileges associated with your user name and password.

     ---

3. Click OK.

   A message is displayed to show that the classes in the class inheritance tree are being enumerated. In the left side of the CIM WorkShop window, CIM classes are displayed.

Navigating in CIM WorkShop

When you first start CIM WorkShop, the classes of the CIM Schema display hierarchically in the left side of the CIM WorkShop window. This arrangement of classes is referred to as the class inheritance tree. When you select a class, its associated properties are listed in the right side of the window. In the following illustration, the properties of the class solaris_computersystem are listed in the right side of the CIM WorkShop window.

Figure 4-1 Class Inheritance Tree in CIM WorkShop Window

For information about the toolbar, menus, and layout of the CIM WorkShop window, see "Reference: CIM WorkShop Window and Dialogs".

Browsing the Class Inheritance Tree

Each class that has classes is denoted by two icons: a folder icon and an enabler icon. The enabler icon looks like a small key to the left of the folder icon.

The folder icon indicates that the class serves as a container for the classes it contains. The enabler icon serves as a navigation aid.

When an enabler icon is displayed horizontally, the class folder is closed and classes are contained. When you click the enabler icon, the class folder opens and classes are revealed. When the enabler icon is displayed vertically, it indicates that the class folder is open.

How To Display the Contents of a Class

Click the enabler icon of the desired class to view its contents.

How to Display the Properties and Methods of a Class

Click the class folder icon of the class.

The properties and methods of the class are displayed in the right frame of the CIM WorkShop window.

Finding a Class

CIM WorkShop enables you to quickly find a specific class.

How to Find a Class

1. In the toolbar, click the Find Class icon.

2. In the Find Class dialog box, type the name of the class you want to find and click OK.

   When the specified class is found, its details are displayed in the right frame of the CIM WorkShop window.

Viewing Class Characteristics

When you select a class from the class inheritance tree--by clicking its folder icon--two tabs, indicating the properties and methods of the class, are displayed in the right side of the CIM WorkShop window.

Selecting a Class

In the class inheritance tree, classes that contain classes are indicated by folder icons. Classes that do not contain classes are indicated by purple rectangles. Select a class by clicking the folder or page icon of the class in the class inheritance tree.

Viewing Class Properties

By default, when the CIM WorkShop window is displayed, the Properties tab appears in the right side of the CIM WorkShop window. In the left side of the CIM WorkShop window, you can select a class from the class inheritance tree; you can view all properties of the class in the Properties tab. Inherited properties are indicated by an icon that consists of a purple rectangle with a black arrow pointing to a white rectangle. Properties that have an assigned key qualifier are indicated by a gold key icon. For information about the presentation of properties in the Properties tab, see "The Properties Tab".

Viewing Class Methods

After you select a class in the class inheritance tree, you can click the Methods tab to display the methods associated with the class. For information about how the methods are displayed in the methods tab, see "The Methods Tab".

Viewing Qualifiers

In CIM, qualifiers are attributes of classes, instances, properties, and methods. In CIM Workshop, you can view the qualifiers by right-clicking a class, property, or method and clicking Qualifiers in the pop-up menu. Clicking Qualifiers causes the Qualifiers dialog box to be displayed. For information about the presentation of qualifier information in the Qualifiers dialog box, see "Qualifiers Dialog Box".

Viewing the Scope of a Qualifier

When you click the Scope button in the Qualifiers dialog box, the Scope dialog box is displayed. In the Scope dialog box, you can view the scope of a qualifier. When you create qualifiers for a new class, you can also set the scope of new qualifiers in the Scope dialog box. For information about the Scope dialog box, see "Scope Dialog Box".

Viewing the Flavor of a Qualifier

When you click the Flavor button in the Qualifiers dialog box, the Flavors dialog box is displayed. In the Flavors dialog box, you can view the flavor of a qualifier. When you create qualifiers for a new class, you can also set the flavor of new qualifiers in the Flavors dialog box. For information about the Flavors dialog box, see "Flavors Dialog Box".

Working in Namespaces

A namespace is a logical entity, an abstraction of a managed object into which classes and instances can be stored. A namespace can be implemented in various forms including a directory structure, a database, or a folder. By default, CIM WorkShop connects to the CIM Object Manager on the local host, in the default namespace root\cimv2. All classes contained in the default namespace are displayed in the left side of the CIM WorkShop window. The name of the current namespace is listed in the toolbar of the CIM WorkShop window. In CIM WorkShop, you can browse the classes of namespaces on different hosts and you can change location to new namespaces.

When you want to set user privileges for a particular namespace, use the Sun WBEM User Manager. For information about the Sun WBEM User Manager tool, see "Using the Sun WBEM User Manager to Set Access Control" in Chapter 12, Administering Security.

This section describes how to:

• Change to a namespace

• Change to a host

• Refresh the class inheritance tree of the namespace

Changing Namespaces

In the Sun WBEM SDK, the default namespace is root\cimv2. You can change to any other namespace.

How to Change Namespaces

1. In the CIM WorkShop window, click Workshop->Change Namespace.

2. In the Change Namespace dialog box, click the icon of the namespace you want to use. Click OK.

   The namespace you have selected becomes the current namespace.

Changing Hosts

You can change to another host to view namespaces or processes.

How to Change Hosts

1. Click Workshop->Change Host or click the Change Hosts icon in the CIM WorkShop toolbar.

2. In the Hosts field, type the name of the host on which the namespace you want to view is located.

3. Type your user name and password in the User Name and Password fields, respectively.

4. Click OK.

Refreshing Classes and Namespaces

You can refresh the display of the class inheritance tree in the namespace to reflect current changes made by other users who work in the namespace.

How to Refresh a Class Inheritance Tree

1. In the class inheritance tree, click the folder of the class you want to refresh.

2. Click Action->Refresh or click the Refresh Selected Class icon in the CIM WorkShop toolbar.

Working with Classes

Classes are the building blocks of applications. When you start CIM WorkShop, it becomes populated with the classes that make up the CIM and Solaris Schemas. These classes adhere to the Distributed Management Task Force standards. Their unique properties, methods, and qualifier values cannot be changed.

To set new values for an existing class, you can create a new instance or class. The CIM and Solaris Schema classes serve as templates. When you create a new instance or class, you produce a copy of the selected class in which you can add new properties, methods, and qualifier values. In this way, you build your own extensions into the CIM or Solaris Schemas.

You cannot modify the values of inherited properties, methods, or qualifiers.

For information about how to create an instance, see "Working with Instances". For information about how to create a class, see the following section.

Adding a Class

Adding a class to an existing class entails the following tasks:

• Selecting the class

• Creating a new class

• Adding new qualifiers to the class

• Adding new properties to the class

• Adding new qualifiers to the properties

• Adding new methods to the class

• Adding new qualifiers to the methods

• Setting qualifier values: scope and flavor

Creating a Class

The first step in creating a class is to specify a name for the class. In CIM WorkShop, class names are displayed using standard CIM syntax: SchemaIndicator_ClassName. If you create a class of a CIM Schema class, the acronym CIM is used before the class name. If you create a class of a Solaris Schema class, the name Solaris is used before the class name. The underscore character (_) is required in the name of all classes that inherit a Key qualifier.

How to Add a class

1. In the class inheritance tree of the CIM WorkShop window, select the class from which to create a class.

2. Choose one of the following procedures for creating a class:

   • Click Action->Add Class.

     or

   • Click the New Class icon in the toolbar of the CIM WorkShop window.

     or

   • Right-click the selected class and click Add Class.

     The New Class dialog box is displayed.

3. In the Class Name field, type the name of the new class.

   For example, you can create a class of the class solaris_computersystem titled ultra1_computersystem.

4. To retain inherited properties and methods of the class, click OK. To add new properties, click Add Property.

   If you click OK, a class is created that uses inherited properties, methods, qualifiers, and their values. If you click Add Property, the Add Properties dialog box is displayed, in which you can specify properties to add to the class. For information about how to add properties to a class, see "Adding New Properties to a Class".

Adding Qualifiers

You can add qualifiers to a new class. You cannot change or reset the values of inherited qualifiers that modify the class. Also, you cannot delete inherited qualifiers.

How to Add Qualifiers

1. In the New Class dialog box, after you provide a name for the new class, click Class Qualifiers.

2. In the Qualifiers dialog box, right-click the Qualifier for which you want to set new values and click Add Qualifier.

3. In the Add Qualifier dialog box, select the name of a qualifier in the list and click OK.

4. To set the scope of the qualifier:

   1. Click Scope.

   2. In the Scope dialog box, select the scope of the qualifier and click OK.

5. To set the flavor of the qualifier:

   1. Click Flavors.

   2. In the Flavors dialog box, select the flavor of the qualifier and click OK.

6. Click OK in the Qualifiers dialog box to close it.

Adding New Properties to a Class

You can add new properties to a class and modify their values. You cannot change the values of inherited properties, and you cannot delete inherited properties.

How to Add a New Property to a Class

1. After specifying a name for the new class, click Add Property in the New Class dialog box.

   The Add Properties dialog box is displayed.

2. In the Name field, type the name of the new property.

3. Select a property type from the Type field and click OK.

   The new property is displayed in the Properties tab of the New Class dialog box. If the list of properties is long, click the scroll bar to view the newly added property.

4. Click OK in the New Class dialog box.

   For information about how to add new qualifiers or set qualifier values for a new property or class, see the following sections.

Adding Qualifiers to a New Property

You can set the values of qualifiers for new properties of the class. You cannot change or reset the values of qualifiers that modify inherited properties or methods. You cannot delete inherited qualifiers.

How to Add Qualifiers to a New Property

1. In the New Class dialog box, click the new property you created and click Property Qualifiers.

   The Qualifiers dialog box is displayed for the property that you created.

2. Click Add Qualifier.

3. In the Name field of the Add Qualifier dialog box, select a qualifier and click OK.

4. Click OK in the Qualifiers dialog box and in the New Class dialog box.

   The qualifier and qualifier type are set for the selected property.

Deleting Classes and Their Attributes

CIM WorkShop provides a way to delete classes, properties, methods, and qualifiers that you no longer need or use.

When you delete a class, you delete all subclasses it contains. You also delete all associated properties, methods, and qualifiers of the class and its subclasses.

Deleting a Class

Use the following procedure to delete a class from the class inheritance tree.

How to Delete a Class

1. Select the class that you want to delete.

2. Click Classes->Delete Class and click OK in the dialog box that asks you to confirm your decision to delete a class.

   The class is deleted.

Deleting a Property of a Class

You can delete a property only when you create a new class. Otherwise, you can view but not modify or delete properties of classes. However, when you create a new class, you can delete properties inherited from the parent class if you do not need them or want to use them. For information about how to create a class, see "Adding a Class".

How to Delete a Property of a Class

1. In the Properties tab of the New Class dialog box, right-click a property.

2. Click Delete Property in the pop-up menu.

   The property is deleted from the Properties tab.

Deleting Qualifiers

When you create a new class, you can delete qualifiers of properties or methods inherited from the parent class. For information about how to create a class, see "Adding a Class".

How to Delete a Qualifier of a Property

1. In the Properties tab of the New Class dialog box, right-click the property that you want to delete.

2. Click Qualifiers in the pop-up menu.

3. In the Qualifiers dialog box, click Delete Qualifier, then click OK.

   The selected qualifier is deleted. The New Class dialog box is displayed.

How to Delete a Qualifier of a Method

1. In the Methods tab of the New Class dialog box, right-click the method that you want to delete.

2. Click Qualifiers in the pop-up menu.

3. In the Qualifiers dialog box, click Delete Qualifier, then click OK.

   The selected qualifier is deleted. The New Class dialog box is displayed.

Working with Instances

In CIM WorkShop, you can create instances of classes. Instances inherit the characteristics of the class. You can then change the attributes of a new instance to create a unique instance of a class.

Displaying Instances

Before you create a new instance of a class, it is useful to view the instances of the class to see what properties and methods they contain.

How to Display Instances of an Existing Class

1. In the class inheritance tree of the CIM WorkShop window, select the class for which you want to view instances.

2. To display the Instances window:

   • Click Action->Instances.

     or

   • Click the Show Instances icon on the CIM WorkShop toolbar.

The Instances window is displayed. If the selected class has instances, the instances are displayed in the left frame of the Instances window. If the selected class does not have instances, the left frame of the Instances window is empty.

Adding Instances

Add instances to a class when you want to modify the inherited qualities of objects.

How to Add an Instance to a Class

1. In the CIM WorkShop window:

   • Click Action->Instances.

     or

   • Right-click a class that has instances from which you can create a new instance. Click Instances in the pop-up menu.

     The Instances window is displayed. All instances of the class are displayed in the left side of the window.

2. Right-click an instance listed in the Instances window.

   The Add Instances dialog box is displayed.

3. To modify the inherited properties of an instance:

   1. Right-click a property listed in the Add Instances dialog box.

      A dialog box is displayed in which you can provide a value for the property. The dialog box displayed varies depending on the type of the selected property. For example, if you select a property that has a type STRING, the String dialog box will display. The Value field of this dialog box accepts only character strings.

   2. In the Values field of the dialog box, type the required value.

4. Click OK to close the Add Instances window.

Deleting Instances

You can delete an instance that you no longer use.

How to Delete an Instance

1. In the left frame of the CIM WorkShop window, right-click the class from which you want to delete an instance.

2. In the pop-up menu, click Instance.

3. In the Instance window, right-click the instance you want to delete and click Delete Instance in the pop-up menu.

   The instance is deleted.

Reference: CIM WorkShop Window and Dialogs

The following section provides descriptions of the frames, toolbar icons, and fields that comprise the CIM WorkShop window. It also describes CIM WorkShop dialogs.

The CIM WorkShop Window

The CIM WorkShop window is divided into two main frames. In the left frame, you can view the class inheritance tree of the current host. In the right frame, you can view the properties and methods of a selected class.

Figure 4-2 The CIM WorkShop Window

CIM WorkShop Toolbar Icons

The icons provided in the CIM WorkShop toolbar enable you to display and change namespaces and search for classes and instances.

Figure 4-3 The CIM WorkShop Toolbar

The Properties Tab

The Properties tab shows information about a selected property. An icon resembling a folder with an arrow indicates that the property is inherited from a superclass. An icon resembling a gold key indicates that the property is a Key. Key properties provide unique identifiers for an instance of the domain class. The unique instance is indicated by a key qualifier.

In the Properties tab, the Name and Type of the property are displayed. You can change the value of a property when you create a new class of the domain class.

The Methods Tab

By selecting the Methods tab, you can view all methods of the class. Methods are listed consecutively. Reading horizontally from left to right, the following attributes are displayed for each method:

CIM WorkShop Menus

The following table describes the CIM WorkShop menus and menu items.

Login Dialog Box

The login dialog box is displayed when you first encounter CIM WorkShop. In the login dialog box, you specify the following:

• Host on which the CIM Object Manager is running and which contains the namespace you want to use

• Namespace in which you want to work

• Your user name

• Your password

If you do not specify a user name and password, you log in to CIM WorkShop as a guest. Guest privileges are read-only.

New Class Dialog Box

In the New Class dialog box, you can create a new class.

Figure 4-4 The New Class Dialog Box

Add Properties Dialog Box

In the Add Properties dialog box, you can add new properties to a class as you create it. In the Name field, you specify the name of the property. In the type field, select a type and click OK.

Qualifiers Dialog Box

In the Qualifiers dialog box, you can view qualifiers for a selected class, property, or method. When you create a new class, you can add qualifiers to the class or modify qualifiers of the class, its properties, or its methods in the Qualifiers dialog box. The title bar of the Qualifiers dialog box indicates the name of the class for which you view qualifiers or the class for which you add or modify qualifiers.

The following table describes the fields of the Qualifiers dialog box.

The following table describes the buttons of the Qualifiers dialog box.

Scope Dialog Box

In the Scope dialog box, you can view the scope of a qualifier that modifies an existing class, property, or method. You can also change the scope of a qualifier that you create for a new class or for a property or method added to a new class. The Scope field lists all possible scopes you can select.

Flavors Dialog Box

In the Flavors dialog box, you can view the flavor of a qualifier. You can also change the flavor of a qualifier that you create for a new class or for a property or method added to a new class. The Flavors field lists all possible flavors you can select.

Value Type Dialog Boxes

When you create new properties for a class, you can use any of the dialog boxes that CIM WorkShop provides for specifying properties of a particular type. These dialog boxes are configured to accept only a value of the appropriate type. The dialog boxes include the following:

• Real Integer dialog box

• Signed Integer dialog box

• Unsigned Integer dialog box

• String dialog box

• Array dialog box

• Boolean dialog box

Real Integer Dialog Box

The Values field of this dialog box accepts only a real integer. A real integer can be a negative or positive number including a decimal point. When you create a property that is of the type Real Integer, type a real integer in the Values field of this dialog box.

Signed Integer Dialog Box

The Values field of this dialog box accepts only a signed integer of a specified size. A signed integer can be a negative or positive whole number. CIM properties that have values which are signed integers can be 8 bits, 16 bits, 32 bits, or 64 bits in size. Depending on the size of the signed integer that makes up the value of the property, type the following in the Values field of this dialog box:

• For a property that is an 8-bit signed integer, type a positive or negative numeric value equivalent to 8 bits.

• For a property that is a 16-bit signed integer, type a positive or negative numeric value equivalent to 16 bits.

• For a property that is a 32-bit signed integer, type a positive or negative numeric value equivalent to 32 bits.

• For a property that is a 64-bit signed integer, type a positive or negative numeric value equivalent to 64 bits.

Unsigned Integer Dialog Box

The Values field of this dialog box accepts only an unsigned integer of a specified size. An unsigned integer can be only a positive whole number. CIM properties that have values which are unsigned integers can be 8 bits, 16 bits, 32 bits, or 64 bits in size. Depending on the size of the unsigned integer that makes up the value of the property, type the following in the Values field of this dialog box:

• For a property that is an 8-bit unsigned integer, type a positive numeric value equivalent to 8 bits.

• For a property that is a 16-bit unsigned integer, type a positive numeric value equivalent to 16 bits.

• For a property that is a 32-bit unsigned integer, type a positive numeric value equivalent to 32 bits.

• For a property that is a 64-bit unsigned integer, type a positive numeric value equivalent to 64 bits.

String Dialog Box

The Values field of this dialog box accepts only alphabetic and numeric characters. When you specify the value of a property that is a character string, you must enter a character string, such as Processor_Type, in the Values field of this dialog box. Character strings may not contain integers.

Array Dialog Boxes

In the Array dialog boxes, you can specify an array as a value for a property. The following array dialog boxes are available to return arrays:

• 8-Bit Unsigned Integer Array Dialog Box - returns a collection of positive integers equivalent to 8 bits in size

• 16-Bit Unsigned Integer Array Dialog Box - returns a collection of positive integers equivalent to 16 bits in size

• 32-Bit Unsigned Integer Array Dialog Box - returns a collection of positive integers equivalent to 32 bits in size

• 64-Bit Unisgned Integer Array Dialog Box - returns a collection of positive integers equivalent to 64 bits in size

• 8-Bit Signed Integer Array Dialog Box - returns a collection of positive or negative integers equivalent to 8 bits in size

• 16-Bit Signed Integer Array Dialog Box - returns a collection of positive or negative integers equivalent to 16 bits in size

• 32-Bit Signed Integer Array Dialog Box - returns a collection of positive or negative integers equivalent to 32 bits in size

• 64-Bit Signed Integer Array Dialog Box - returns a collection of positive or negative integers equivalent to 64 bits in size

• String Array Dialog Box - returns a collection of alphabetic and numeric character strings

• Boolean Array Dialog Box - returns a collection of Boolean expressions, True or False

• 32-Bit Real Array Dialog Box - returns a collection of positive or negative real numbers, with or without a decimal point, equivalent to 32 bits in size

• 64-Bit Real Array Dialog Box - returns a collection of positive or negative real numbers, with or without a decimal point, equivalent to 64 bits in size

• 16-Bit Character Array Dialog Box - returns a collection of alphabetic and numeric character strings equivalent to 16 bits in size

• Date/Time Array Dialog Box - returns a collection of dates in the format mm-dd-yy and times in the format hh:mm:ss

Boolean Dialog Box

In the Boolean dialog box, you can specify True or False as the value of a selected property.

Instance Window

The Instance window lists all instances for a selected class. You can also view the properties, methods, and qualifiers associated with each instance.

You display the Instance window by:

• Selecting a class in the CIM WorkShop window and clicking Action->Instances

• Right-clicking a class in the CIM WorkShop window and clicking Instances in the pop-up menu

Frames of the Instances Window

If the selected class has instances, the instances are listed in the left frame of the Instances window. Each instance is displayed with its Name, CreationClassName, and TargetOperatingSystem. If the selected class does not have instances, the left frame is empty.

Like the CIM WorkShop window, the right frame of the Instances window contains two tabs: Properties tab and Methods tab. All properties of the selected instance are displayed in the table of the Properties tab. The Inherited Properties icon--which appears in the left column of the Properties table as a purple rectangle with an arrow pointing to a white rectangle--indicates that the property is inherited from the class used to create the instance. The Key Qualifiers icon--which appears as a gold key--indicates that a property has an inherited Key qualifier.

Instances Window Toolbar Icons

The Instances window contains the following icons in the toolbar:

Menus of the Instances Window

The instances window contains the following menus and menu items:

Add Instances Dialog Box

In the Add Instances dialog box, you can right-click a property to change its value for a new instance. You cannot change the values of inherited properties.

Chapter 5 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.

• About the APIs

• The API Packages

For detailed information on the CIM and Client 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.1 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

• Client API - Methods that applications use to transfer data to and from 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.

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.

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 listed in the following table in the CIMClient class to transfer data to and from the CIM Object Manager.

Provider API Package (com.sun.wbem.provider)

Provider APIs are interfaces 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.

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.

Chapter 7 Writing a Provider Program

This chapter describes how to write a provider, including the following topics:

• About Providers

• Implementing a Provider Interface

• Installing a Provider

• Registering a Provider

• Modifying a Provider

• Provider Examples

For detailed information on the provider APIs, see the Javadoc reference pages.

About Providers

Providers are classes that communicate with managed objects to access data. Providers forward this information to the CIM Object Manager for integration and interpretation. When the CIM Object Manager receives a request from a management application for data that is not available from the CIM Object Manager Repository, it forwards the request to a provider.

Object providers must be installed on the same machine as the CIM Object Manager. The CIM Object Manager uses object provider application programming interfaces (APIs) to communicate with locally installed providers.

When an application requests dynamic data from the CIM Object Manager, the CIM Object Manager uses the provider interfaces to pass the request to the provider.

Providers perform the following functions in response to a request from the CIM Object Manager:

• Map the native information format 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 native device format

  • Get the required information from the CIM Java class

  • Pass the information to the device in native device format

Types of Providers

Providers are categorized according to the types of requests they service. The Sun WBEM SDK supports three types of providers:

• Instance - Supply dynamic instances of a given class, for example, Solaris packages. Instance providers support one or more of the following operations:

  • Instance retrieval

  • Enumeration

  • Modification

  • Deletion

• Property - Supply dynamic property values, for example, disk space.

• Method - Supply methods of one or more classes. A method is a function that describes the behavior of a class. Methods must be implemented by a provider.

A single provider can support both methods and instances, which can be convenient.

Most providers are pull providers, which means they maintain their own data, generating it dynamically when necessary. Pull providers have minimal interaction with the CIM Object Manager and the CIM Repository. The data managed by a pull provider typically changes frequently, requiring the provider to either generate the data dynamically or retrieve it from a local cache whenever an application issues a request. A provider can also contact the CIM Object Manager.

A single provider can act simultaneously as a class, instance, and method provider by proper registration and implementation of all relevant methods.

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 following table describes the provider interfaces. 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.

Providers can communicate with the CIM Object Manager 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 Instance Provider Interface (InstanceProvider)

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

These methods each take the op argument, the CIM object path 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 code segment in Example 7-1, creates a Solaris instance provider class that routes requests for instance data 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 for instances of the Solaris_Package class.

An instance provider must implement all methods in the InstanceProvider interface. The code segment in Example 7-1 shows only two methods:

• enumInstances - Calls the appropriate provider to enumerate Solaris packages and patches. This method does a deep enumeration, which returns the class instances and all instances of its subclasses.

• getInstances - Calls the appropriate provider to get instances of Solaris packages and patches.

Example 7-1 Implementing an Instance Provider

public class Solaris implements InstanceProvider
{
   /**
    * Top-level provider class routes requests from the CIM
    * Object Manager to the appropriate provider.
    */
 
    public void initialize(CIMONHandle, ch) 
    throws CIMException {
    }
 
    public void cleanup() 
    throws CIMException {
    }
 
    /* This class returns a vector of enumerated instances of the 
    specified object in the specified class. If the object is a 
    Solaris package, it calls the Solaris_Package provider to return 
    a list of the Solaris packages on the system. If the object is a 
    Solaris patch, it calls the Solaris_Patch provider to return a 
    list of the Solaris patches on the system. */
 
    public Vector enumInstances(CIMObjectPath op, CIMClient.DEEP, CIMClass cc)
    throws CIMException {
        if (op.getObjectName().equalsIgnoreCase("solaris_package")) {
            Solaris_Package sp = new Solaris_Package();
            return sp.enumerateInstances(op);
        }
        if (op.getObjectName().equalsIgnoreCase("solaris_patch")) {
            Solaris_Patch sp = new Solaris_Patch();
            return sp.enumerateInstances(op);
        }
       return new Vector();
    }
 
 
    /* This class returns an instance of the specified object in the 
    specified class. If the object is a Solaris package, it
    calls the Solaris_Package provider to return the data for the
    specified Solaris package. If the object is a Solaris patch, it 
    calls the Solaris_Patch provider to return the data for the 
    specified Solaris patch. */
 
    public CIMInstance getInstance(CIMObjectPath op, CIMClass cc) 
    throws CIMException {
        if (op.getObjectName().equalsIgnoreCase("solaris_package")) {
            Solaris_Package sp = new Solaris_Package();     
            return sp.getInstance(op,cc);
        }
        if (op.getObjectName().equalsIgnoreCase("solaris_patch")) {
            Solaris_Patch sp = new Solaris_Patch();         
            return sp.getInstance(op,cc);
        } 
}
 

The specialized Solaris instance providers use the API to get and set instances of objects. These providers also declare native methods that call C functions to get Solaris-specific values, such as host name, serial number, release, machine, architecture, and manufacturer.

The code segment in Example 7-2 shows the solaris_package class, which is called in Example 7-1. This code segment implements the getInstance method. This method creates a new instance of the specified class and then fills it with properties returned from native C functions, such as GetPkgArchitecture().

Example 7-2 Solaris Package Provider

public class Solaris_Package 
{
    public CIMInstance getInstance(CIMObjectPath op, CIMClass cc) {
        String pkgName = "";
 
        for (Enumeration e = op.getKeys().elements(); e.hasMoreElements();) {
            CIMProperty cp = (CIMProperty)e.nextElement();
            if (cp.getName().equalsIgnoreCase("name")) {
                pkgName = (String) ((CIMValue)(cp.getValue())).getValue();
            }
        }
 
 
        CIMInstance ci = cc.newInstance();
        ci.setProperty("Name", new CIMValue(pkgName));
        ci.setProperty("TargetOperatingSystem", 
                          new CIMValue(new UnsignedInt16(29)));
 
        ci.setProperty("Status", 
                     new CIMValue(GetPkgStatus(pkgName)));
  			 ci.setProperty("Architecture", 
                          new CIMValue(GetPkgArchitecture(pkgName)));
        ci.setProperty("Description", new CIMValue(GetPkgDescription(pkgName)));
        ci.setProperty("Caption", new CIMValue(GetPkgDescription(pkgName)));
        ci.setProperty("Manufacturer", new CIMValue(GetPkgVendor(pkgName)));
        ci.setProperty("Category", new CIMValue(GetPkgCategory(pkgName)));
        ci.setProperty("Basedir", new CIMValue(GetPkgBasedir(pkgName)));
       return ci;
    }
 
    native String GetPkgDescription(String pkgName);
    native String GetPkgArchitecture(String pkgName);
    native String GetPkgVersion(String pkgName);
    native String GetPkgVendor(String pkgName);
    native String GetPkgBasedir(String pkgName);
    native String GetPkgCategory(String pkgName);
    native String GetPkgStatus(String pkgName);
 
 
   static {
       System.loadLibrary("NativeUnix");
   
    }
 
}
 

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 7-3 creates a property provider (fruit_prop_provider) class that is registered in Example 7-5. 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 7-3 Implementing a Property Provider

fruit_prop_provider implements PropertyProvider 
{
public CIMValue getPropertyValue(CIMObjectpath op, string originclass, 
	string PropertyName){
 
		if (PropertyName.euqals("a")
			return new CIMValue("fooa")
 
		else
			return new CIMValue("foob");
}
...
}
 

The Method Provider Interface (MethodProvider)

The MethodProvider method takes the following arguments:

• op - Object path to the instance whose method must be invoked.

• originClass - Name of the class in which this method was originally defined in the class hierarchy. CIM properties are attributes of a CIM class that are inherited from a parent class. A CIM property is uniquely identified within a namespace by its name and origin class. For example, two properties named speed can be distinguished by their respective origin classes DiskDrive and CPU.

• inParams - Vector of CIMValues that are the input parameters for the method.

• CIMValue - Return value of the method. If the method has no return value, it must return null. A CIM value stores the CIM data type and value of a CIM property. CIM data types (defined in the CIM Specification) are limited to intrinsic data types. The following table provides the WBEM data type name for each CIM data type.

  Table 7-4 Sun WBEM SDK and CIM Data Type Names

  CIM Data Type	WBEM Data Type	Description
  uint8	UnsignedInt8	Unsigned 8-bit integer
  sint8	Byte	Signed 8-bit integer
  uint16	UnsignedInt16	Unsigned 16-bit integer
  sint16	Short	Signed 16-bit integer
  uint32	UnsignedInt32	Unsigned 32-bit integer
  sint32	Integer	Signed 32-bit integer
  uint64	UnsignedInt64	Unsigned 64-bit integer
  sint64	Long	Signed 64-bit integer
  string	String	UCS-2 string
  boolean	Boolean	Boolean
  real32	Float	IEEE 4-byte floating point
  real64	Double	IEEE 8-byte floating point
  datetime	CIMDateTime	String containing a date-time
  classname ref	CIMObjectPath	Strongly typed reference
  char16	Character	16-bit UCS-2 character

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

Example -- Implementing a Method Provider

The code segment in Example 7-4 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 7-4 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;
    }
}
 

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.

Installing a Provider

After you write a Provider, you must specify the location of the provider class files and any shared library files.

How to Install a Provider Program

1. Specify the location of shared library files in one of the following ways:

   • Set the LD_LIBRARY_PATH environment variable to the location of the shared library files. For example, using the C shell:

     % setenv LD_LIBRARY_PATH /wbem/provider/

     For example, using the Borne shell:

     % set LD_LIBRARY_PATH = /wbem/provider/

   • Copy the shared library files to the directory specified by the LD_LIBRARY_PATH environment variable. The installation sets this environment variable to /install_dir/opt/SUNWconn/wbem/lib. For example:

   % cp libnative.so /install_dir/opt/SUNWconn/wbem/lib % cp native.c /install_dir/opt/SUNWconn/wbem/lib

2. Move the provider class files to /install_dir/opt/SUNWconn/wbem/bin.

3. Set the CLASSPATH variable to the directory that contains the provider class files.

   For example, if you put the provider files in:

   /install_dir/opt/SUNWconn/wbem/bin/com/mycomp/wbem/provider/
   

   you would set your CLASSPATH variable as follows, using the C shell:

   % setenv CLASSPATH com/mycomp/wbem/provider/myprovider

   For the Borne shell, use the following syntax:

   $ set CLASSPATH = com/mycomp/wbem/provider/myprovider

4. Make sure the CIM Object Manager is running.

   The installation starts the CIM Object Manager. If it is not running, see "Restarting the CIM Object Manager".

Registering a Provider

Providers register with the CIM Object Manager to publish information about the data and operations they support and their physical implementation. The CIM Object Manager uses this information to load and initialize the provider and to determine the right provider for a particular client request. All types of providers follow the same procedure for registration. Neither the CIM Object Manager or the provider needs to be running during the registration process.

How To Register a Provider

1. Create a MOF file defining a CIM class.

2. Assign the provider qualifier to the class. Assign a provider name to the provider qualifier.

   The provider name identifies the Java class to serve as the provider for this class. You must specify the complete class name. For example:

   ---

   Note -

   We recommend following Java class and package naming conventions for providers so that provider names are unique. The prefix of a unique package name is always written in all-lowercase ASCII letters and should be one of the top-level domain names, currently com, edu, gov, mil, net, org, or one of the English two-letter codes identifying countries as specified in ISO Standards 3166, 1981.

   Subsequent components of the package name vary according to an organizations own internal naming conventions. Such conventions might specify that certain directory name components be division, department, project, machine, or login names, for example com.mycompany.wbem.myprovider.

   ---

   [Provider("com.kailee.wbem.providers.provider_name")]
   Class_name {
   ...
   };

3. Compile the MOF file. For example:

   mofcomp class_name

Example -- Registering a Provider

The sample MOF file in Example 7-5 creates a class called Fruit that registers an instance provider (fruit_class_provider), a property provider (fruit_prop_provider), and a method provider (fruit_method_provider).

Example 7-5 Registering an Instance, Property, and Method Provider

 
// Registers fruit_class_provider as the provider for the Fruit class
[Provider("com.food.fruitprovider.fruit_class_provider")] 
 
Fruit {
 
// fruit_prop_provider is the provider for property a
		[Provider("com.food.fruitprovider.fruit_class_provider")] 
-		string a;
 
		// fruit_prop_provider is also the provider for property b
		[Provider("com.food.fruitprovider.fruit_class_provider")] 
		string b;
 
		// fruit_method_provider is the provider for method b
		[Provider("com.food.fruitprovider.fruit_class_provider")] 
		int b();
};
 

Modifying a Provider

You can make changes to a Provider class while the CIM Object Manager and provider are running. But you must stop and restart the CIM Object Manager to make the changes take effect.

To Modify a Provider

1. Edit the provider source file.

2. Compile the provider source file. For example:

   % java MyProvider.java
   

3. Become root on your system by typing the following command at the system prompt:

   % su

4. Type the root password when you are prompted.

5. Change directories to the location of the init.wbem command by typing the following command:

   # cd /etc/init.d/

6. Stop the CIM Object Manager by typing the following command:

   # init.wbem -stop

7. Restart the CIM Object Manager by typing the following command:

   # init.wbem -start

Provider Examples

Chapter 8, Using Sun WBEM SDK Examples explains how to set up and run the Provider examples.

Chapter 8 Using Sun WBEM SDK Examples

This chapter describes the sample programs provided in the Sun WBEM SDK and includes the following topics:

• About Example Programs

• Using the Client Examples

• Using the Provider Examples

About Example Programs

The Sun WBEM SDK provides example Java programs, which are installed in /install_dir/SUNWconn/wbem/demo. You can use the source code as a basis for developing your own programs. Two types of example programs are provided:

• Client programs - Programs that use the client and CIM application programming interfaces (APIs) to request WBEM operations from the CIM Object Manager

• Provider programs - Programs that communicate with managed objects to access data

Using Client Examples

The client examples use the client APIs to create, delete, and list classes, instances, and namespaces. The five types of client programs are:

• Enumeration - Enumerates classes and instances. It does deep and shallow enumeration on a class that is passed from the command line.

• Logging - Writes and reads log records

• Miscellaneous - Deletes classes and instances.

• Namespace - Creates and deletes namespaces.

• System Information - Displays Solaris process information for the system and network you select.

Client Example Files

The following table describes the example client program files and lists the commands and arguments to run each example.

Running the Client Examples

To run a client example program, type the command:

java program_name

Most of the example programs take required arguments that have default values. For example, the CreateNameSpace example program takes five arguments:

• Host name

• Parent namespace

• Child namespace

• User name

• Password

Use the following syntax to specify default values for command line arguments.

The following example runs the CreateNameSpace example, which connects to the default root\cimv2 namespace on the local host as user admin with password secret.

java CreateNameSpace . "" admin secret

Using the Provider Examples

The example provider is a Java program that returns system properties and prints the string, "Hello World." The provider calls native C methods to execute the code and return the values to the provider.

Provider Example Files

The following table describes the files that make up the example Provider program.

Writing a Native Provider

For detailed information on writing and integrating Java programs with native methods, visit the Java Web page at http://www.javasoft.com/docs/books/tutorial/native1.1/TOC.html.

Setting Up the Provider Example

The example provider program, NativeProvider, enumerates instances and gets properties for instances of the Native_Example class. You can use the CIM WorkShop to view this class and its instances.

How to Set Up the Provider Example

1. Specify the location of shared library files in one of the following ways:

   • Set the LD_LIBRARY_PATH environment variable to the location of the shared library files. For example:

     % set LD_LIBRARY_PATH /install_dir/SUNWconn/wbem/demo/provider/jni/

   • Copy the shared library files to the directory specified by the LD_LIBRARY_PATH environment variable. Installation sets this environment variable to /install_dir/opt/SUNWconn/wbem/lib. For example:

   % cp libnative.so /install_dir/opt/SUNWconn/wbem/lib % cp native.c /install_dir/opt/SUNWconn/wbem/lib % cp Native_Example.h /install_dir/opt/SUNWconn/wbem/lib

2. Move the provider class files to the directory containing the CIM Object Manager. For example:

   % mv Native*.class /install_dir/opt/SUNWconn/wbem/bin

3. Make sure the CIM Object Manager is running.

   The installation starts the CIM Object Manager. If it is not running, see "Restarting the CIM Object Manager".

4. Compile the Native_Example.mof file. For example:

   % mofcomp Native_Example.mof

   Compiling this MOF file loads the Native_Example class in the CIM Object Manager and identifies NativeProvider as its provider.

5. Run CIM WorkShop and view the Native_Example class. For example:

   % /opt/SUNWconn/wbem/bin/cimworkshop &

6. In the Toolbar, click the Find Class icon.

7. In the Input dialog box, type Native_Example and click OK.

Chapter 9 Error Messages

This chapter discusses the error messages generated by components of Solaris WBEM Services and the Sun WBEM SDK. The following topics are covered.

• How Error Messages are Generated

• Parts of Error Messages

• Finding Information About Error Messages

• Generated Error Messages

How Error Messages are Generated

The CIM Object Manager generates initial error messages that are used by both the MOF Compiler and the CIM WorkShop. The MOF Compiler appends a line to the error message indicating where in a .mof file the error occurred.

Parts of Error Messages

Error messages are made up of the following parts:

• Unique identifier - Character string that differentiates the error message from other error messages

• Exception message - Explanation of the error message

• Parameters - Placeholders for the specific classes, methods, and qualifiers that are cited in the exception message

Error Message Example

For example, the MOF Compiler may return the following error message:

REF_REQUIRED = Association class CIM_Docked needs
 at least two refs. Error in line 12.

• REF_REQUIRED is the unique identifier.

• Association class CIM_Docked needs at least two refs is the exception message.

• CIM_Docked is a parameter. A parameter can be replaced with the name of any appropriate class, property, method, or qualifier.

For Developers: Error Message Templates

WBEM provides exception templates for all possible error messages in the ErrorMessages_en.properties file of the APIs. In an exception template that requires parameters, the first parameter is represented as {0} and the second parameter is represented as {1}.

The following exception template is used in the previous example:

REF_REQUIRED = Association class {0} needs at least two refs.

Finding Information About Error Messages

You can search for the unique identifier of an error message in the Javadoc reference pages to receive an explanation about the content of the error message.

The following section provides a detailed explanation of each error message. The error messages are organized by unique identifiers. For each error message, the following types of information are provided, when applicable:

• Unique identifier, displayed as a heading.

• Description of the parameters used in the error message.

• Example of the error message as it is displayed to a user. This example is provided if the error message uses parameters to show how the error message will be displayed when elements, such as a class name, are substituted for the parameters.

• Cause, or reason why the error message was generated, and background or referential information that is helpful for understanding the error message.

• Solution, including steps you can take to resolve the error are provided when available.

Generated Error Messages

The following section lists and describes the error messages generated by the MOF Compiler, CIM Object Manager, and CIM WorkShop.

ABSTRACT_INSTANCE

Description:

The ABSTRACT_INSTANCE error message uses one parameter, {0}, which is replaced by the name of the abstract class.

Example:

ABSTRACT_INSTANCE = Abstract class ExampleClass cannot have instances.

Cause:

Instances were programmed for the specified class. However, the specified class is an abstract class, and abstract classes cannot have instances.

Solution:

Remove the programmed instances.

CHECKSUM_ERROR

The CHECKSUM_ERROR error message uses no parameters.

Example:

CHECKSUM_ERROR = Checksum not valid.

Cause:

The message could not be sent because it was damaged or corrupted. The damage could have occurred accidentally in transit or by a malicious third party.

---

Note -

This error message is displayed when the CIM Object Manager receives an invalid checksum. A checksum is the number of bits in a packet of data passed over the network. This number is used by the sender and the receiver of the information to ensure that the transmission is secure and that the data has not been corrupted or intentionally modified during transit.

An algorithm is run on the data before transmission, and the checksum is generated and included with the data to indicate the size of the data packet. When the message is received, the receiver can recompute the checksum and compare it to the sender's checksum. If the checksums match, the transmission was secure and the data was not corrupted or modified.

---

Solution:

Resend the message using Solaris WBEM Services security features. For information about Solaris WBEM Services security, see Chapter 12, Administering Security.

CIM_ERR_ACCESS_DENIED

Description:

The CIM_ERR_ACCESS_DENIED error message does not use parameters.

Example:

CIM_ERR_ACCESS_DENIED = Insufficient privileges.

Cause:

This error message is displayed when a user does not have the appropriate privileges and permissions to complete an action.

Solution:

See your CIM Object Manager administrator to request privileges to complete the operation.

CIM_ERR_ALREADY_EXISTS

Instance 1: CIM_ERR_ALREADY_EXISTS

Description:

This instance of the CIM_ERR_ALREADY_EXISTS error message uses one parameter, {0}, which is replaced by the name of the duplicate class.

Example:

CIM_ERR_ALREADY_EXISTS = Duplicate class CIMRack

Cause:

The class you attempted to create uses the same name as an existing class.

Solution:

In CIM WorkShop, search for existing classes to see the class names that are in use, then create the class using a unique class name.

Instance 2: CIM_ERR_ALREADY_EXISTS

Description:

This instance of the CIM_ERR_ALREADY_EXISTS error message uses one parameter, {0}, which is replaced by the name of the duplicate instance.

Example:

CIM_ERR_ALREADY_EXISTS = Duplicate instance SolarisRack

Cause:

The instance for a class you attempted to create uses the same name as an existing instance.

Solution:

In CIM WorkShop, search for existing instances to see the names that are in use, then create the instance using a unique name.

Instance 3: CIM_ERR_ALREADY_EXISTS

Description:

This instance of the CIM_ERR_ALREADY_EXISTS error message uses one parameter, {0}, which is replaced by the name of the duplicate namespace.

Example:

CIM_ERR_ALREADY_EXISTS = Duplicate namespace /root/CIMV2

Cause:

The namespace you attempted to create uses the same name as an existing namespace.

Solution:

In CIM WorkShop, search for existing namespaces to see the names that are in use, then create the namespace using a unique name.

Instance 4: CIM_ERR_ALREADY_EXISTS

Description:

This instance of the CIM_ERR_ALREADY_EXISTS error message uses one parameter, {0}, which is replaced by the name of the duplicate qualifier type.

Example:

CIM_ERR_ALREADY_EXISTS = Duplicate qualifier type Key

Cause:

The qualifier type you attempted to create uses the same name as an existing qualifier type of the property it modifies.

Solution:

In CIM WorkShop, search for qualifier types that exist for the property to see the names that are in use, then create the qualifier type using a unique name.

CIM_ERR_FAILED

Description:

Description

The CIM_ERR_FAILED error message uses one parameter, {0}, which is replaced by a character string, a message that explains the error condition and its possible cause.

Example:

Example

CIM_ERR_FAILED=Invalid entry.

Cause:

Cause

The CIM_ERR_FAILED error message is a generic message that can be displayed for a large number of different error conditions.

Solution

Because CIM_ERR_FAILED is a generic error message, many types of conditions can cause the message. The solution varies depending on the error condition.

CIM_ERR_INVALID_PARAMETER

Description:

The CIM_ERR_INVALID_PARAMETER error message uses one parameter, {0}, which is replaced by the name of the class that is missing a schema prefix.

Example:

CIM_ERR_INVALID_PARAMETER = Class System has no schema prefix.

Cause:

A class was created without providing a schema prefix in front of the class name. The Common Information Model requires that all classes are provided with a schema prefix. For example, classes developed as part of the CIM Schema require a CIM prefix: CIM_Container. Classes developed as part of the Solaris Schema require a Solaris prefix: Solaris_System.

Solution:

Provide the appropriate schema prefix for the class definition. Find all instances of the class missing the prefix and replace them with the class name and prefix.

CIM_ERR_INVALID_SUPERCLASS

Description:

The parameter CIM_ERR_INVALID_SUPERCLASS uses two parameters:

• {0} is replaced by the name of the specified subclass.

• {1} is replaced by the name of the class for which a specified subclass does not exist.

Example:

CIM_ERR_INVALID_SUPERCLASS = Superclass CIM_Chassis for class CIM_Container does not exist.

Cause:

A class is specified to belong to a particular superclass, but the superclass does not exist. The specified superclass may be misspelled, or a non-existent superclass name may have been specified accidentally in place of the intended superclass name. Or, the superclass and the subclass may have been interpolated: the specified superclass actually may be a subclass of the specified subclass. In the previous example, CIM_Chassis is specified as the superclass of CIM_Container, but CIM_Chassis is a subclass of CIM_Container.

Solution:

Check the spelling and the name of the superclass to ensure it is correct. Ensure that the superclass exists in the namespace.

CIM_ERR_NOT_FOUND

Instance 1: CIM_ERR_NOT_FOUND

Description:

This instance of the CIM_ERR_NOT_FOUND error message uses one parameter, {0}, which is replaced by the name of the non-existent class.

Example:

CIM_ERR_NOT_FOUND = Class Solaris_Device does not exist.

Cause:

A class is specified, but it does not exist. The specified class may be misspelled, or a non-existent class name may have been specified accidentally in place of the intended class name.

Solution:

Check the spelling and the name of the class to ensure that it is correct. Ensure that the class exists in the namespace.

Instance 2: CIM_ERR_NOT_FOUND

Description:

This instance of the error message CIM_ERR_NOT_FOUND uses two parameters:

• {0} is replaced by the name of the specified instance

• {1} is replaced by the name of the specified class

Example:

CIM_ERR_NOT_FOUND = Instance Solaris_EnterpriseData does not exist for class Solaris_ComputerSystem.

Cause:

The instance does not exist.

Solution:

Create the instance.

Instance 3: CIM_ERR_NOT_FOUND

Description:

This instance of the CIM_ERR_NOT_FOUND error message uses one parameter, {0}, the name of the specified namespace.

Example:

CIM_ERR_NOT_FOUND = Namespace verdant does not exist.

Cause:

The specified namespace is not found. This error may occur if the name of the namespace was entered incorrectly due to a typing error or spelling mistake.

Solution:

Retype the name of the namespace. Ensure that typing and spelling are correct.

CLASS_REFERENCE

Description:

The CLASS_REFERENCE error message uses two parameters.

• {0} parameter is replaced by the name of the class that was defined to participate in a reference.

• {1} parameter is replaced by the name of the reference.

Example:

CLASS_REFERENCE = Class SolarisExample1 must be declared as an association to have reference SolarisExample2

Cause:

A property was defined for a class to indicate that the class has a reference. However, the class is not part of an association relationship. A class can only be defined to have a reference as a property if it participates in an association relationship with another class.

Solution:

Create the association relationship, then set up the reference to the association as a property of this class.

INVALID_CREDENTIAL

Description:

The INVALID_CREDENTIAL error message does not use parameters.

Example:

INVALID_CREDENTIAL = Invalid credentials.

Cause:

This error message is displayed when an invalid password has been entered.

Solution:

If you receive this message from CIM WorkShop, delete the invalid password from the Password field of the CIM WorkShop authentication dialog box and type the password again. If this error message was received from the MOF Compiler, at the system prompt, log in again and type the correct password. Ensure that you spell the password correctly.

INVALID_QUALIFIER_NAME

Description:

The INVALID_QUALIFIER_NAME error message uses one parameter, {0}, which is replaced by the Managed Object Format notation that depicts an empty qualifier name.

Example:

INVALID_QUALIFIER_NAME = Invalid qualifier name " "

Cause:

A qualifier was created for a property, but a qualifier name was not specified.

Solution:

Include the qualifier name in the context of the qualifier definition.

KEY_OVERRIDE

Description:

The KEY_OVERRIDE error message uses two parameters:

• {0} parameter is replaced by the name of the non-abstract class that is put in an override relationship with a class that has one or more Key qualifiers.

• {1} parameter is replaced by the name of the concrete class that has the Key qualifier.

Example:

KEY_OVERRIDE = Non-key Qualifier SolarisCard cannot override key Qualifier SolarisLock.

Cause:

A non-abstract class, referred to as a concrete class, is put into an override relationship with a concrete class that has one or more Key qualifiers. In CIM, all concrete classes require at least one Key qualifier, and a non-Key class cannot override a class that has a Key.

Solution:

Create a Key qualifier for the non-Key class.

KEY_REQUIRED

Description:

The KEY_REQUIRED error message uses one parameter, {0} which is replaced by the name of the class that requires a key.

Example:

KEY_REQUIRED = Concrete (non-abstract) class ClassName needs at least one key.

Cause:

A Key qualifier was not provided for a concrete class. In CIM, all non-abstract classes, referred to as concrete classes, require at least one Key qualifier.

Solution:

Create a Key qualifier for the class.

METHOD_OVERRIDDEN

Description:

The METHOD_OVERRIDDEN command uses three parameters:

• {0} replaced by the name of the method that is trying to override the method represented by parameter {1}.

• {1} is replaced by the name of the method that has already been overridden by the method represented by parameter {2}.

• {2} is replaced by the name of the method that has overridden parameter {1}.

Example:

METHOD_OVERRIDDEN = Method Resume () cannot override Stop() which is already overridden by Start()

Cause:

A method is specified to override another method that has already been overridden by a third method. Once a method has been overridden, it cannot be overridden again.

Solution:

Specify a different method to override.

NEW_KEY

Description:

The NEW KEY error message uses two parameters.

• {0} is replaced by the name of the key.

• {1} is replaced by the name of the class that is trying to define a new key.

Example:

NEW_KEY = Class CIM_PhysicalPackage cannot define new key [Key]

Cause:

A class is trying to define a new key when keys already have been defined in a superclass. Once keys have been defined in a superclass, new keys cannot be introduced into the subclasses.

Solution:

No action can be taken.

NO_CIMOM

Description:

The NO_CIMOM error message uses one parameter, {0} which is replaced by the name of the host that is expected to be running the CIM Object Manager.

Example:

NO_CIMOM = CIMOM molly not detected.

Cause:

The CIM Object Manager is not running on the specified host.

Solution:

Ensure that the CIM Object Manager is running on the host to which you are trying to connect. If the CM Object Manager is not running on that host, connect to a host running the CIM Object Manager.

NO_INSTANCE_PROVIDER

Description:

The NO_INSTANCE_PROVIDER error message uses two parameters:

• {0} is replaced by the name of the class for which the instance provider cannot be found.

• {1} is replaced by the name of the instance provider class that was specified.

Example:

NO_INSTANCE_PROVIDER = Instance provider RPC_prop for class RPC_Agent not found.

Cause:

The Java class of the specified instance provider is not found. This error message indicates that the class path of the CIM Object Manager does not contain one or more of the following:

• Name of the provider class

• Parameters of the provider class

• CIM class for which the provider is defined

Solution:

Set the CIM Object Manager environment variable.

NO_METHOD_PROVIDER

Description:

The NO_METHOD_PROVIDER error message uses two parameters:

• {0} is replaced by the name of the class for which the method provider cannot be found.

• {1} is replaced by the name of the method provider class that was specified.

Example:

NO_METHOD_PROVIDER = Method provider Start_prop for class RPC_Agent not found.

Cause:

The Java class of the specified method provider is not found. This error message indicates that the class path of the CIM Object Manager does not contain one or more of the following:

• Name of the provider class

• Parameters of the provider class

• CIM class for which the provider is defined

Solution:

Set the CIM Object Manager class path.

NO_OVERRIDDEN_METHOD

Description:

The error message NO_OVERRIDDEN_METHOD uses two parameters:

• {0} is replaced by the name of the method that has overridden the method represented by {1}.

• {1} is replaced by the name of the method that has been overridden.

Example:

NO_OVERRIDDEN_METHOD = Method Write overridden by Read does not exist in class hierarchy.

Cause:

The method of a subclass is trying to override the method of the superclass, but the method of the superclass already has been overridden by a method that belongs to another subclass. The overridden method that you are trying to override does not exist in the class hierarchy because it has never been defined.

When you override a method, you override its implementation and its signature.

Solution:

Ensure that the method exists in the superclass.

NO_OVERRIDDEN_PROPERTY

Description:

The NO_OVERRIDDEN_PROPERTY error message uses two parameters.

• {0} is replaced by the name of the property that has overridden {1}.

• {1} is replaced by the name of the overriding property.

Example:

NO_OVERRIDDEN_PROPERTY = Property A overridden by B does not exist in class hierarchy.

Cause:

The property of a subclass is trying to override the property of the superclass, but it doesn't succeed because the property of the superclass already has been overridden. The property that you are trying to override does not exist in the class hierarchy.

Solution:

Ensure that the property exists in the superclass.

NO_PROPERTY_PROVIDER

Description:

The NO_PROPERTY_PROVIDER error message uses two parameters:

• {0} is replaced by the name of the class for which the property provider cannot be found.

• {1} is replaced by the name of the property provider class that was specified.

Example:

NO_PROPERTY_PROVIDER = Property provider Write_prop for class RPC_Agent not found.

Cause:

The Java class of the specified property provider is not found. This error message indicates that the class path of the CIM Object Manager does not contain one or more of the following:

• Name of the provider class

• Parameters of the provider class

• CIM class for which the provider is defined

Solution:

Set the CIM Object Manager class path.

NO_QUALIFIER_VALUE

Description:

The NO_QUALIFIER_VALUE error message uses two parameters:

• {0} is replaced by the name of the qualifier that modifies the element {1}

• {1} is the element to which the qualifier refers. Depending on the qualifier, {1} can be a class, property, method, or reference.

Example:

NO_QUALIFIER_VALUE = Qualifier [SOURCE] for Solaris_ComputerSystem has no value.

Cause:

A qualifier was specified for a property or method, but values were not included for the qualifier. For example, the qualifier VALUES requires a string array to be specified. If the VALUES qualifier is specified without the required string array, the NO_QUALIFIER_VALUE error message is displayed.

Solution:

Specify the required parameters for the qualifier. For information about what attributes are required for which qualifiers, see the CIM Specification by the Distributed Management Task Force at the following URL: http://dmtf.org/spec/cims.html.

NO_SUCH_METHOD

Description:

The NO_SUCH_METHOD error message uses two parameters:

• {0} is replaced by the name of the specified method

• {1} is replaced by the name of the specified class

Example:

NO_SUCH_METHOD = Method Configure() does not exist in class Solaris_ComputerSystem

Cause:

Most likely, the method was not defined for the specified class. If the method is defined for the specified class, another method name may have been mispelled or typed differently in the definition.

Solution:

Define the method as an operation for the specified class. Otherwise, ensure that the method name and class name were typed correctly.

NO_SUCH_PRINCIPAL

Description:

The NO_SUCH_PRINCIPAL error message uses one parameter, {0}, which is replaced by the name of the principal, a user account.

Example:

NO_SUCH_PRINCIPAL = Principal molly not found.

Cause:

The specified user account cannot be found. The user name may have been mistyped upon login, or a user account has not been set up for the user.

Solution:

Ensure that the user name is spelled and typed correctly upon login. Ensure that a user account has been set up for the user.

NO_SUCH_QUALIFIER1

Description:

The NO_SUCH_QUALIFIER1 error message uses one parameter, {0}, which is replaced by the name of the undefined qualifier.

Example:

NO_SUCH_QUALIFIER1 = Qualifier [LOCAL] not found.

Cause:

A new qualifier was specified, but was not defined as part of the extension schema. The qualifier is required to be defined as part of the CIM Schema or an extension schema to be recognized as a valid qualifier for a property or method of a particular class.

Solution:

Define the qualifier as part of the extension schema or use a standard CIM qualifier. For information about standard CIM qualifiers and the usage of qualifiers in the CIM schema, see the CIM Specification by the Distributed Management Task Force at the following URL: http://www.dmtf.org/spec/cims.html.

NO_SUCH_QUALIFIER2

Description:

The NO_SUCH_QUALIFIER2 error message uses two parameters:

• {0} is replaced by the name of the class, property, or method that the qualifier modifies.

• {1} is replaced by the name of the qualifier that cannot be found.

Example:

NO_SUCH_QUALIFIER2 = Qualifier [LOCAL] not found for CIM_LogicalElement

Cause:

A new qualifier was specified to modify a property or method of a particular class. The qualifier was not defined as part of the extension schema. The qualifier is required to be defined as part of the CIM schema or an extension schema to be recognized as a valid qualifier for a property or method of a particular class.

Solution:

Define the qualifier as part of the extension schema or use a standard CIM qualifier. For information about standard CIM qualifiers and the usage of qualifiers in the CIM schema, see the CIM Specification by the Distributed Management Task Force at the URL, http://www.dmtf.org/spec/cims.html .

NO_SUCH_SESSION

Description:

The error message NO_SUCH_SESSION uses one parameter, {0}, which is replaced by the session identifier.

Example:

NO_SUCH_SESSION = No such session 4002.

Cause:

This message is displayed when a session has been infringed upon by an intruder. The CIM Object Manager removes the session when it detects that someone is trying to maliciously change data. For information about Solaris WBEM Services security features, see Chapter 12, Administering Security.

Solution:

Ensure that your CIM environment is secure.

NOT_HELLO

Description:

The NOT_HELLO error message uses no parameters.

Example:

NOT_HELLO = Not a Hello message.

Cause:

This error message is displayed if the data in the hello message--the first message sent to the CIM Object Manager--is corrupted, indicating a security breach.

Solution:

No action is available in response to this error message. For information about Solaris WBEM Services security features, see Chapter 12, Administering Security.

NOT_INSTANCE_PROVIDER

Description:

The NOT_INSTANCE_PROVIDER error message uses two parameters:

• {0} is replaced by the name of the instance for which the InstanceProvider interface is being defined.

• {1} is replaced by the name of the Java provider class that does not implement the InstanceProvider interface. The InstanceProvider interface must be implemented to enumerate all instances of the specified class.

Example:

NOT_INSTANCE_PROVIDER = device_prop_provider for class Solaris_Provider does not implement InstanceProvider.

Cause:

The path to the Java provider class specified by the CLASSPATH environment variable does not implement the InstanceProvider interface.

Solution:

Ensure that the Java provider class present in the class path implements the InstanceProvider interface. Use the following command when you declare the provider: public Solaris implements InstanceProvider. For information about how to implement Solaris WBEM Services providers, see Chapter 7, Writing a Provider Program.

NOT_METHOD_PROVIDER

Description:

The NOT_METHOD_PROVIDER error message uses two parameters:

• {0} is replaced by the name of the method for which the MethodProvider interface is being defined. The MethodProvider causes a specified method to be implemented in a program and enacted.

• {1} is replaced by the name of the Java provider class that does not implement the MethodProvider interface.

Example:

NOT_METHOD_PROVIDER = Provider device_method_provider for class Solaris_Provider does not implement MethodProvider.

Cause:

The Java provider class present in the class path does not implement the MethodProvider interface.

Solution:

Ensure that the Java provider class present in the class path implements the MethodProvider interface. Use the following command when you declare the provider: public Solaris implements MethodProvider. For information about how to implement Solaris WBEM Services providers, see Chapter 7, Writing a Provider Program.

NOT_PROPERTY_PROVIDER

Description:

The NOT_PROPERTY_PROVIDER error message uses two parameters:

• {0} is replaced by the name of the method for which the PropertyProvider interface is being defined. The PropertyProvider interface is required to retrieve the values of the specified property.

• {1}is replaced by the name of the Java provider class that does not implement the PropertyProvider interface.

Example:

NOT_PROPERTY_PROVIDER = Provider device_property_provider for class Solaris_Provider does not implement PropertyProvider.

Cause:

The Java provider class present in the class path does not implement the PropertyProvider interface.

Solution:

Ensure that the Java provider class present in the class path implements the PropertyProvider interface. Use the following command when you declare the provider: public Solaris implements PropertyProvider. For information about how to implement Solaris WBEM Services providers, see Chapter 7, Writing a Provider Program.

NOT_RESPONSE

Description:

The NOT_RESPONSE error message uses no parameters.

Example:

NOT_RESPONSE = Not a response message.

Cause:

This error message is displayed when the data in a first response message from the CIM Object Manager is corrupted, indicating a security breach.

Solution:

No action is available in response to this error message. For information about Solaris WBEM Services security features, see Chapter 12, Administering Security.

PROPERTY_OVERRIDDEN

Description:

The PROPERTY_OVERRIDDEN error message uses three parameters:

• {0} is replaced by the name of the property that is trying to override the property represented by parameter {1}.

• {1} is replaced by the name of the property that already has been overridden.

• {2} is replaced by the name of the property that has overridden the property represented by parameter {1}.

Example:

PROPERTY_OVERRIDDEN = Property Volume cannot override MaxCapacity which is already overridden by RawCapacity

Cause:

A property is specified to override another method that has already been overridden by a third method. Once a property has been overridden, it cannot be overridden again.

Solution:

Specify a different property to override.

PS_CONFIG

The PS_CONFIG error message uses one parameter, {0}, which is replaced by a description of the details that cause the error to occur. The description varies depending on the type of database used for the repository and the type of situation that causes the error message.

PS_CONFIG = The persistent store configuration is incorrect or has not been completed. You may need to run the wbemconfig script.

Cause:

Solaris WBEM Services requires the wbemconfig script to be run after installation. The wbemconfig script configures the persistent store and compiles the MOF files that provide the CIM and Solaris Schema classes. If the wbemconfig script was not run after the Solaris WBEM Services installation, this error message occurs. If the repository was configured after installation and this error message occurs, the database configuration may have become corrupted.

Solution:

Run the wbemconfig script. For information about the wbemconfig script, see "Configuring After Installing in Solaris 7" in the chapter Chapter 10, Installing Solaris WBEM Services.

PS_UNAVAILABLE

Description:

The PS_UNAVAILABLE error message uses one parameter {0}, which is replaced by a message that describes why the persistent store became unavailable.

Example:

PS_UNAVAILABLE = The persistent store is unavailable. The exception thrown by the repository is 'segmentation fault.'

Cause:

This error message is displayed when the CIM Repository is unavailable. This situation could occur if the host on which the CIM Repository resides is brought down temporarily for maintenance, or if the host on which the CIM Repository resides becomes damaged and the repository is taken down and then restored on another host.

Solution:

If you receive this message while working in the CIM WorkShop, click the icon that causes the CIM WorkShop authentication dialog box to display. Then, in the Host field, type the name of another host that is running the CIM Repository and the CIM Object Manager. Type the namespace in the Namespace field, your user name and password, and log in. If you receive this message when running the MOF Compiler, type the following command to point to another host running the CIM Repository and CIM Object Manager: mofcomp -c hostname where mofcomp is the command to start the MOF Compiler, -c is the parameter that enables you to specify a host computer running the CIM Object Manager, and hostname is the name of the specified computer.

QUALIFIER_UNOVERRIDABLE

Description:

The QUALIFIER_UNOVERRIDABLE error message uses two parameters:

• {0} parameter is replaced by the name of the qualifier that is set with the DisableOverride flavor.

• {1} parameter is replaced by the name of the qualifier that is set to be disabled by {0}.

Example:

QUALIFIER_UNOVERRIDABLE = Test cannot override qualifier Standard because it has DisableOverride flavor.

Cause:

The ability of the specified qualifier to override another qualifier is disabled because the flavor of the specified qualifier has been set to DisableOverride or Override=False.

Solution:

Reset the ability of the qualifier to EnableOverride or to Override=True.

REF_REQUIRED

Description:

The REF_REQUIRED error message uses one parameter, {0}, which is replaced by the name of the class specified to participate in an association relationship.

Example:

REF_REQUIRED = Association class CIM_Chassis needs at least two refs.

Cause:

A class was set up to participate in an association, but no references were cited. The rules of the Common Information Model specify that an association must contain two or more references.

Solution:

Set up the references to the class, then set up the association.

SCOPE_ERROR

Description:

The SCOPE_ERROR command uses three parameters:

• {0} is replaced by the name of the class the specified qualifier modifies.

• {1} is replaced by the name of the specified qualifier.

• {2} is replaced by the type of attribute that the qualifier modifies.

Example:

SCOPE_ERROR = Qualifier [UNITS] for CIM_Container does not have a Property scope.

Cause:

A qualifier was specified in a manner that conflicts with the requirements of the CIM Specification. For example, the [READ] qualifier is defined in the CIM Specification to modify a Property. The scope of the [READ] qualifier is the definition that directs the [READ] qualifier to modify a Property. If the [READ] qualifier is used in a manner other than the direction of its scope--for example, if the [READ] qualifier is specified to modify a Method--the SCOPE_ERROR message is returned.

---

Note -

The CIM Specification defines the types of CIM elements that a CIM qualifier can modify. This definition of the way in which a qualifier can be used is referred to as its scope. Most qualifiers, by definition, have a scope that directs them to modify properties or methods or both. Many qualifiers have a scope that directs them to modify parameters, classes, associations, indications, or schemas.

---

Solution:

Confirm the scope of the specified qualifier. Refer to the section, "1.Qualifiers" of the CIM Specification by the Distributed Management Task Force at the following URL:http://www.dmtf.org/spec/cim_spec_v20 for the standard definitions of CIM qualifiers. Use a different qualifier for the results you want to achieve, or change your program to use the qualifier according to its CIM definition.

SIGNATURE_ERROR

Description:

The SIGNATURE_ERROR error message uses no parameters.

Example:

SIGNATURE_ERROR = Signature not verified

Cause:

This message is displayed when a message is corrupted either accidentally or maliciously. It differs from the checksum error in that the message has a valid checksum, but the signature cannot be verified by the public key of the client. This protection ensures that even though the session key has been compromised, only the initial client which created the session is authenticated.

Solution:

No action is provided for this message, which is displayed when a session has been infringed upon by an intruder. For information about Solaris WBEM Services security features, see Chapter 12, Administering Security.

TYPE_ERROR

Description:

The TYPE_ERROR error message uses five parameters:

• {0} is replaced by the name of the specified element, such as a property, method, or qualifier.

• {1} is replaced by the name of the class to which the specified element belongs.

• {2} is replaced by the type defined for the element.

• {3} is replaced by the type of value assigned.

• {4} is replaced by the actual value assigned.

Example:

TYPE_ERROR = Cannot convert sint16 4 to a string for VolumeLabel in class Solaris_DiskPartition

Cause:

The value of a property or method parameter and its defined type are mismatched.

Solution:

Match the value of the property or method with its defined type.

UNKNOWNHOST

Description:

The UNKNOWNHOST error message uses one parameter, {0}, which is replaced by the name of the host.

Example:

UNKNOWNHOST = Unknown host molly

Cause:

A call was made to a specified host. The specified host is unavailable or cannot be located. It is possible that the host name was spelled incorrectly. It is also possible that the host computer was moved to a different domain or that the host name has not been registered in the list of hosts that belong to the domain. The host may be temporarily unavailable due to system conditions.

Solution:

Check the spelling of the host name. Ensure that no typing errors were made. Use the ping command to ensure that the host computer is responding. Check the system conditions of the host. Ensure that the host belongs to the specified domain.

VER_ERROR

Description:

The VER_ERROR error message uses one parameter, {0}, which is replaced by the version number of the running CIM Object Manager.

Example:

VER_ERROR = Unsupported version 0.

Cause:

The upgraded version of Solaris WBEM Services does not support the current CIM Object Manager.

Solution:

Install the supported version.