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. When you connect to a namespace, you can access the classes and instances in that namespace (if they exist) and in any namespaces contained in that namespace. For example, if you create a namespace called child in the root\cimv2 namespace, you could connect to root\cimv2 and access the classes and instances in the root\cimv2 and root\cimv2\child namespaces.

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. If you open a new connection to root\cimv2\child, you can access any classes and instances in that namespace but cannot access the classes and instances in the parent namespace, root\cimv2.

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

  A CIMNameSpace object that contains the names of 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. By default, the guest account allows users read access to all CIM objects in all namespaces.

• 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 class to connect to the CIM Object Manager.

In Example 4–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 4–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 4–3, the application connects to the CIM Object Manager running on the local host, in the default namespace (root\cimv2). The application creates a UserPrincipal object for the root account, which has read and write access to all CIM objects in the default namespaces.

Example 4–3 Connecting to the Root Account

{
    ...

    host as root. Create a namespace object initialized with two null strings
    that specify the default host (the local host) and the default 
    namespace (root\cimv2).*/
 
    CIMNameSpace cns = new CIMNameSpace("", "");

    UserPrincipal up = new UserPrincipal("root");
	   PasswordCredential pc = new PasswordCredential("root_password"); 
    /* Connect to the namespace as root with the 
    root password. */
 
    CIMClient cc = new CIMClient(cns, up, pc");
    ...
}

In Example 4–4, 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 4–4 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");
    UserPrincipal up = new UserPrincipal("Mary");
    PasswordCredential pc = new PasswordCredential("marys_password");
     
    // Connect to the namespace as user Mary.
    cc = new CIMClient(cns, "Mary", "marys_password");
    ...

} 

Example 4–5 Authenticating as an RBAC Role Identity

Authenticating a user's role identity requires using the SolarisUserPrincipal and SolarisPasswordCredential classes. The following examples authenticates as Mary and assumes the role Admin.

{
...
CIMNameSpace cns = new CIMNameSpace("happy", "A");
SolarisUserPrincipal sup = new SolarisUserPrincipal("Mary", "Admin");
SolarisPasswordCredential spc = new
        SolarisPasswordCredential("marys_password", "admins_password");
CIMClient cc = new CIMClient(cns, sup, spc);

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();