javax.wbem.client
Class CIMClient

java.lang.Object
  javax.wbem.client.CIMClient

All Implemented Interfaces:

CIMOMHandle

public class CIMClient

extends java.lang.Object

implements CIMOMHandle

Constructs a CIM client on the local host (default) or the specified host. This class connect to the WBEM Server for this client session to perform WBEM operations, such as, adding, modifying, or deleting a CIM class, CIM instance, and CIM qualifier type in a namespace.

A WBEM client application connects to a WBEM Server to establish an initial connection when it needs to perform WBEM operations.

Since:

WBEM 1.0

Field Summary

static java.lang.String

CIM_XML Constant identifying the CIM operations over XML protocol.

Constructor Summary

CIMClient(CIMNameSpace name, java.security.Principal principal, java.lang.Object credential)
Creates a new client connection to the WBEM Server on the host and namespace specified in the namespace object, using the specified principal and credential to authenticate the client user identity to the WBEM Server.

CIMClient(CIMNameSpace name, javax.security.auth.Subject subject)
Creates a new client connection to the WBEM Server on the host and namespace specified in the namespace object, using the specified principal and credential to authenticate the client user identity to the WBEM Server.

CIMClient(CIMNameSpace name, javax.security.auth.Subject subject, java.util.Locale[] locales)
Creates a new client connection to the WBEM Server on the host and namespace specified in the namespace object, using the specified principal and credential to authenticate the client user identity to the WBEM Server.

Method Summary

void	addCIMListener(CIMListener l) Adds the specified CIMListener to receive Indications from the CIM Server.
void	addCIMListener(CIMListener l, int p) Adds the specified CIMListener to receive Indications from the CIM Server.
java.util.Enumeration	associatorNames(CIMObjectPath objectName, java.lang.String assocClass, java.lang.String resultClass, java.lang.String role, java.lang.String resultRole) Enumerates the CIMObjectPaths of CIM Objects that are associated to a particular source CIM Object.
java.util.Enumeration	associators(CIMObjectPath objectName, java.lang.String assocClass, java.lang.String resultClass, java.lang.String role, java.lang.String resultRole, boolean includeQualifiers, boolean includeClassOrigin, java.lang.String[] propertyList) Enumerate CIM Objects that are associated to a specified source CIM Object.
void	close() Closes the client connection to the WBEM Server.
void	createClass(CIMObjectPath name, CIMClass cc) Adds the CIM class to the specified namespace.
CIMObjectPath	createInstance(CIMObjectPath name, CIMInstance ci) Adds the specified CIM Instance to the specified namespace.
void	deleteClass(CIMObjectPath path) Deletes the CIM class for the object specified by the CIM object path.
void	deleteInstance(CIMObjectPath path) Deletes the CIM instance specified by the CIM object path.
void	deleteQualifierType(CIMObjectPath path) Deletes the CIM qualfier type in the namespace specified by the CIM object path.
java.util.Enumeration	enumerateClasses(CIMObjectPath path, boolean deep, boolean localOnly, boolean includeQualifiers, boolean includeClassOrigin) Enumerates the class specified in the path.
java.util.Enumeration	enumerateClassNames(CIMObjectPath path, boolean deep) Enumerates the class specified in the path.
java.util.Enumeration	enumerateInstanceNames(CIMObjectPath path) Returns the object paths of all instances of the class specified.
java.util.Enumeration	enumerateInstances(CIMObjectPath path, boolean deep, boolean localOnly, boolean includeQualifiers, boolean includeClassOrigin, java.lang.String[] propertyList) Returns an enumeration of all instances of the class specified by the CIMObjectPath argument.
java.util.Enumeration	enumQualifierTypes(CIMObjectPath path) Enumerates the qualifiers defined in the specified namespace.
java.util.Enumeration	execQuery(CIMObjectPath path, java.lang.String query, java.lang.String ql) Executes a query to retrieve objects.
CIMClass	getClass(CIMObjectPath name, boolean localOnly, boolean includeQualifiers, boolean includeClassOrigin, java.lang.String[] propertyList) Returns the CIMClass for the specified CIMObjectPath.
CIMInstance	getIndicationListener(CIMListener cl) This method returns an Instance of the subclass of CIM_ListenerDestination defined for the client's protocol.
CIMInstance	getInstance(CIMObjectPath name, boolean localOnly, boolean includeQualifiers, boolean includeClassOrigin, java.lang.String[] propertyList) Returns the CIMInstance for the specified CIMObjectPath.
CIMQualifierType	getQualifierType(CIMObjectPath name) Gets the CIMQualifierType specified.
CIMValue	invokeMethod(CIMObjectPath name, java.lang.String methodName, CIMArgument[] inArgs, CIMArgument[] outArgs) Executes the specified method on the specified object.
BatchResult	performBatchOperations(BatchHandle bc) Executes the batch operations contained in the specified BatchHandle object.
java.util.Enumeration	referenceNames(CIMObjectPath objectName, java.lang.String resultClass, java.lang.String role) Enumerates the CIMObjectPaths of Association Objects that are refer to a particular source CIM Object.
java.util.Enumeration	references(CIMObjectPath objectName, java.lang.String resultClass, java.lang.String role, boolean includeQualifiers, boolean includeClassOrigin, java.lang.String[] propertyList) Enumerates the Association Objects that refer to a specified source CIM Object.
void	removeCIMListener(CIMListener l) Removes the specified CIMListener that is receiving Indications from the CIM Server.
void	setClass(CIMObjectPath name, CIMClass cc) Modifies the CIMClass in the specified namespace.
void	setInstance(CIMObjectPath name, CIMInstance ci, boolean includeQualifiers, java.lang.String[] propertyList) Modifies some or all of the properties of the specified CIMInstance in the specified namespace.
void	setQualifierType(CIMObjectPath name, CIMQualifierType qt) Adds the specified CIMQualifierType to the specified namespace if it does not already exist.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface javax.wbem.client.CIMOMHandle

createQualifierType, getIndicationHandler, setInstance

Field Detail

CIM_XML

public static final java.lang.String CIM_XML

Constant identifying the CIM operations over XML protocol.

See Also:

Constant Field Values

Constructor Detail

CIMClient

public CIMClient(CIMNameSpace name,
                 java.security.Principal principal,
                 java.lang.Object credential)
          throws CIMException

Creates a new client connection to the WBEM Server on the host and namespace specified in the namespace object, using the specified principal and credential to authenticate the client user identity to the WBEM Server.

Parameters:

name - The namespace in which operations will be performed. This can be a URL that includes the protocol scheme and optional port information. See the DMTF WBEM URI Specification for the format. Example: https://192.168.0.4:5989/interop. This will use the https protocol to connect on port 5989

principal - The client user principal identity.

credential - The client user credential for authentication.

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   NO_SUCH_PRINCIPAL (user account does not exist),
   INVALID_CREDENTIAL (invalid password),
   CIM_ERR_NOT_SUPPORTED,
   CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized 
   or otherwise incorrect parameters),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

CIMClient

public CIMClient(CIMNameSpace name,
                 javax.security.auth.Subject subject)
          throws CIMException

Creates a new client connection to the WBEM Server on the host and namespace specified in the namespace object, using the specified principal and credential to authenticate the client user identity to the WBEM Server. This connection uses the specified protocol to send messages to the WBEM Server.

Parameters:

name - The namespace in which operations will be performed

subject - The principal/credential pairs for this connection

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   NO_SUCH_PRINCIPAL (user account does not exist),
   INVALID_CREDENTIAL (invalid password),
   CIM_ERR_NOT_SUPPORTED,
   CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized 
   or otherwise incorrect parameters),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

CIMClient

public CIMClient(CIMNameSpace name,
                 javax.security.auth.Subject subject,
                 java.util.Locale[] locales)
          throws CIMException

Creates a new client connection to the WBEM Server on the host and namespace specified in the namespace object, using the specified principal and credential to authenticate the client user identity to the WBEM Server. This connection uses the specified protocol to send messages to the WBEM Server.

Parameters:

name - The namespace in which operations will be performed

subject - The principal/credential pairs for this connection

locales - An array of locales in priority of preference

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   NO_SUCH_PRINCIPAL (user account does not exist),
   INVALID_CREDENTIAL (invalid password),
   CIM_ERR_NOT_SUPPORTED,
   CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized 
   or otherwise incorrect parameters),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

Method Detail

addCIMListener

public void addCIMListener(CIMListener l)
                    throws CIMException

Adds the specified CIMListener to receive Indications from the CIM Server. In order to force the client to stop listening for Indications, close() must be called. If close() is not called, listening for Indications may still continue. The calling client program will not be able to exit without calling System.exit(). Any duplicate listeners are ignored.

Specified by:

addCIMListener in interface CIMOMHandle

Parameters:

l - The CIMListener to add to receive Indications from the CIM Server.

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED (if CIMOM does not support events),
   CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized 
   or otherwise incorrect parameters),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

See Also:

close()

addCIMListener

public void addCIMListener(CIMListener l,
                           int p)
                    throws CIMException

Adds the specified CIMListener to receive Indications from the CIM Server. In order to force the client to stop listening for Indications, close() must be called. If close() is not called, listening for Indications may still continue. The calling client program will not be able to exit without calling System.exit(). Any duplicate listeners are ignored.

Parameters:

l - The CIMListener to add to receive Indications from the CIM Server.

p - The port to receive Indications on

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED (if CIMOM does not support events),
   CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized 
   or otherwise incorrect parameters),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

See Also:

close()

associatorNames

public java.util.Enumeration associatorNames(CIMObjectPath objectName,
                                             java.lang.String assocClass,
                                             java.lang.String resultClass,
                                             java.lang.String role,
                                             java.lang.String resultRole)
                                      throws CIMException

Enumerates the CIMObjectPaths of CIM Objects that are associated to a particular source CIM Object. If the source Object is a CIM Class, then an Enumeration of CIMObjectPaths of the classes associated to the source Object is returned. If the source Object is a CIM Instance, then an Enumeration of CIMObjectPaths of the CIMInstance objects associated to the source Object is returned.

Specified by:

associatorNames in interface CIMOMHandle

Parameters:

objectName - CIMObjectPath defining the source CIM Object whose associated Objects are to be returned. This argument may contain either a Class name or the modelpath of an Instance. (i.e. Keys populated)

assocClass - This string MUST either contain a valid CIM Association class name or be null. It filters the Objects returned to contain only Objects associated to the source Object via this CIM Association class or one of its subclasses.

resultClass - This string MUST either contain a valid CIM Class name or be null. It filters the Objects returned to contain only the Objects of this Class name or one of its subclasses.

role - This string MUST either contain a valid Property name or be null. It filters the Objects returned to contain only Objects associated to the source Object via an Association class in which the source Object plays the specified role. (i.e. the Property name in the Association class that refers to the source Object matches this value) If "Antecedent" is specified, then only Associations in which the source Object is the "Antecedent" reference are examined.

resultRole - This string MUST either contain a valid Property name or be null. It filters the Objects returned to contain only Objects associated to the source Object via an Association class in which the Object returned plays the specified role. (i.e. the Property name in the Association class that refers to the Object returned matches this value) If "Dependent" is specified, then only Associations in which the Object returned is the "Dependent" reference are examined.

Returns:

If successful, an Enumeration containing zero or more CIMObjectPath objects of the CIM Classes or CIM Instances meeting the specified criteria is returned. If no such Objects are found, null is returned.

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED
   CIM_ERR_NOT_SUPPORTED
   CIM_ERR_INVALID_NAMESPACE
   CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized 
   or otherwise incorrect parameters)
   CIM_ERR_FAILED (some other unspecified error occurred)
 

associators

public java.util.Enumeration associators(CIMObjectPath objectName,
                                         java.lang.String assocClass,
                                         java.lang.String resultClass,
                                         java.lang.String role,
                                         java.lang.String resultRole,
                                         boolean includeQualifiers,
                                         boolean includeClassOrigin,
                                         java.lang.String[] propertyList)
                                  throws CIMException

Enumerate CIM Objects that are associated to a specified source CIM Object. If the source object is a CIM Class, then an Enumeration of CIMClass objects is returned containing the classes associated to the source Object. If the source object is a CIM Instance, then an Enumertion of CIMInstance objects is returned containing the instances associated to the source Object.

Specified by:

associators in interface CIMOMHandle

Parameters:

objectName - CIMObjectPath defining the source CIM Object whose associated Objects are to be returned. This argument may contain either a Class name or the modelpath of an Instance. (i.e. Keys populated)

assocClass - This string MUST either contain a valid CIM Association class name or be null. It filters the Objects returned to contain only Objects associated to the source Object via this CIM Association class or one of its subclasses.

resultClass - This string MUST either contain a valid CIM Class name or be null. It filters the Objects returned to contain only the Objects of this Class name or one of its subclasses.

role - This string MUST either contain a valid Property name or be null. It filters the Objects returned to contain only Objects associated to the source Object via an Association class in which the source Object plays the specified role. (i.e. the Property name in the Association class that refers to the source Object matches this value) If "Antecedent" is specified, then only Associations in which the source Object is the "Antecedent" reference are examined.

resultRole - This string MUST either contain a valid Property name or be null. It filters the Objects returned to contain only Objects associated to the source Object via an Association class in which the Object returned plays the specified role. (i.e. the Property name in the Association class that refers to the Object returned matches this value) If "Dependent" is specified, then only Associations in which the Object returned is the "Dependent" reference are examined.

includeQualifiers - If true, all Qualifiers for each Object (including Qualifiers on the Object and on any returned Properties) MUST be included in the Objects returned. If false, no Qualifiers are present in each Object returned.

includeClassOrigin - If true, the CLASSORIGIN attribute will be present on all appropriate elements in the Objects returned. If false, no CLASSORIGIN attributes are present in the Objects returned. CLASSORIGIN is attached to an element (properties, methods, references) to indicate the class in which it was first defined.

propertyList - An array of property names used to filter what is contained in the Objects returned. Each CIMClass or CIMInstance returned only contains elements for the properties of the names specified. Duplicate and invalid property names are ignored and the request is otherwise processed normally. An empty array indicates that no properties should be included in the Objects returned. A null value indicates that all properties should be contained in the Objects returned. NOTE: Properties should not be specified in this parameter unless a non-null value is specified in the resultClass parameter.

Returns:

If successful, an Enumeration containing zero or more CIMClass or CIMInstance Objects meeting the specified criteria is returned. If no such Objects are found, null is returned.

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED
   CIM_ERR_NOT_SUPPORTED
   CIM_ERR_INVALID_NAMESPACE
   CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized 
   or otherwise incorrect parameters)
   CIM_ERR_FAILED (some other unspecified error occurred)
 

close

public void close()
           throws CIMException

Closes the client connection to the WBEM Server. This will enable the WBEM Server to free resources related to the client session. Additionally local indication listeners will be stopped.

Specified by:

close in interface CIMOMHandle

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED,
   CIM_ERR_FAILED (some other unspecified error occurred)
 

createClass

public void createClass(CIMObjectPath name,
                        CIMClass cc)
                 throws CIMException

Adds the CIM class to the specified namespace.

Specified by:

createClass in interface CIMOMHandle

Parameters:

name - CIMObjectPath that identifies the CIMClass to be added

cc - CIMClass to be added

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED,
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized 
   or otherwise incorrect parameters),
   CIM_ERR_ALREADY_EXISTS (the CIM Class already exists)
   CIM_ERR_INVALID_SUPERCLASS (the putative CIM Class declares a
   non-existent superclass),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

createInstance

public CIMObjectPath createInstance(CIMObjectPath name,
                                    CIMInstance ci)
                             throws CIMException

Adds the specified CIM Instance to the specified namespace.

Specified by:

createInstance in interface CIMOMHandle

Parameters:

name - CIM object path that identifies the CIM instance to be added. Only the namespace component is used. All other information (e.g. keys) is ignored.

ci - CIM instance to be created. Its keys and properties may be initialized by either the client or server.

Returns:

CIMObjectPath of the instance created.

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED (provider does not support this method),
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (for this method),
   CIM_ERR_INVALID_CLASS (in this namespace),
   CIM_ERR_ALREADY_EXISTS,
   CIM_ERR_FAILED (some other unspecified error occurred)
 

deleteClass

public void deleteClass(CIMObjectPath path)
                 throws CIMException

Deletes the CIM class for the object specified by the CIM object path.

Specified by:

deleteClass in interface CIMOMHandle

Parameters:

path - The CIMObjectPath identifying the class to delete

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED,
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized 
   or otherwise incorrect parameters),
   CIM_ERR_NOT_FOUND (the CIM Class to be deleted does not exisT),
   CIM_ERR_CLASS_HAS_CHILDREN (the CIM Class has one or more subclasses
   which cannot be deleted),
   CIM_ERR_CLASS_HAS_INSTANCES (the CIM Class has one or more instances
   which cannot be deleted),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

deleteInstance

public void deleteInstance(CIMObjectPath path)
                    throws CIMException

Deletes the CIM instance specified by the CIM object path. The following code sample uses instance name enumeration to retrieve the names of all instances of the specified class, prints the name of each instance, then deletes the instance.

 CIMObjectPath cop = new CIMObjectPath("CIM_FooClass");
 Enumeration e = cimomHandle.enumerateInstanceNames(cop);
 while(e.hasMoreElements()) {
      CIMObjectPath op = (CIMObjectPath)e.nextElement();
      System.out.println(op.toString());
      cimomHandle.deleteInstance(op);
 }
 

Specified by:

deleteInstance in interface CIMOMHandle

Parameters:

path - The object path of the instance to be deleted. It must include all of the keys.

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED (provider does not support this method),
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (for this method),
   CIM_ERR_INVALID_CLASS (in this namespace),
   CIM_ERR_NOT_FOUND (if the instance does not exist),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

deleteQualifierType

public void deleteQualifierType(CIMObjectPath path)
                         throws CIMException

Deletes the CIM qualfier type in the namespace specified by the CIM object path.

Specified by:

deleteQualifierType in interface CIMOMHandle

Parameters:

path - the CIMObjectPath identifying the CIM qualifier to delete

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED,
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized 
   or otherwise incorrect parameters),
   CIM_ERR_NOT_FOUND (the requested Qualifier declaration did not exist),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

enumerateClasses

public java.util.Enumeration enumerateClasses(CIMObjectPath path,
                                              boolean deep,
                                              boolean localOnly,
                                              boolean includeQualifiers,
                                              boolean includeClassOrigin)
                                       throws CIMException

Enumerates the class specified in the path. The entire class contents, not just the class names, are returned.

Specified by:

enumerateClasses in interface CIMOMHandle

Parameters:

path - The object path of the class to be enumerated. Only the name space and class name components are used. Any other information (e.g. Keys) is ignored.

deep - If true, the enumeration returned contains the specified class and all subclasses. If false, the enumeration returned contains only the contents of the first level children of the specified class.

localOnly - If true, only elements (properties, methods and qualifiers) defined in, or overridden in the class are included in the response. If false, all elements of the class definition are returned.

includeQualifiers - If true, all Qualifiers for each Class and its elements (properties, methods, references). If false, no Qualifiers are present in the classes returned

includeClassOrigin - If true, the CLASSORIGIN attribute MUST be present on all appropriate elements in each classes returned. If false, no CLASSORIGIN attributes are present in each class returned. CLASSORIGIN is attached to an element to indicate the class in which it was first defined.

Returns:

Enumeration of CIMClass. If none are found, NULL is returned.

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED,
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized 
   or otherwise incorrect parameters),
   CIM_ERR_INVALID_CLASS (the CIM Class that is the basis for this
   enumeration does not exist),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

See Also:

enumerateClassNames(CIMObjectPath), enumerateClasses(CIMObjectPath)

enumerateClassNames

public java.util.Enumeration enumerateClassNames(CIMObjectPath path,
                                                 boolean deep)
                                          throws CIMException

Enumerates the class specified in the path. The class names are returned as an enumeration of CIMObjectPath.

Specified by:

enumerateClassNames in interface CIMOMHandle

Parameters:

path - The CIMObjectPath identifying the class to be enumerated. If the class name in the object path specified is null, all base classes in the target namespace are returned.

deep - If true, the enumeration returned will contain the names of all classes derived from the class being enumerated. If false, the enumeration returned contains only the names of the first level children of the class.

Returns:

Enumeration of class names as CIMObjectPaths.

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED,
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized 
   or otherwise incorrect parameters),
   CIM_ERR_INVALID_CLASS (the CIM Class that is the basis for this
   enumeration does not exist),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

enumerateInstanceNames

public java.util.Enumeration enumerateInstanceNames(CIMObjectPath path)
                                             throws CIMException

Returns the object paths of all instances of the class specified. The object paths of all derived instances of the specified classes are also returned.

Specified by:

enumerateInstanceNames in interface CIMOMHandle

Parameters:

path - The CIMObjectPath identifying the class whose instances are to be enumerated. Only the name space and class name components are used. All other information (e.g. Keys) is ignored.

Returns:

Enumeration of instance names as CIMObjectPaths. If no instances are found, NULL is returned.

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED (provider does not support this method),
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (for this method),
   CIM_ERR_INVALID_CLASS (in this namespace),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

enumerateInstances

public java.util.Enumeration enumerateInstances(CIMObjectPath path,
                                                boolean deep,
                                                boolean localOnly,
                                                boolean includeQualifiers,
                                                boolean includeClassOrigin,
                                                java.lang.String[] propertyList)
                                         throws CIMException

Returns an enumeration of all instances of the class specified by the CIMObjectPath argument. The entire instances, not just the object paths to the instances, are returned. The enumeration returned could include instances of all the classes in the specified class's hierarchy.

Specified by:

enumerateInstances in interface CIMOMHandle

Parameters:

path - The object path of the class to be enumerated. Only the name space and class name components are used. Any other information (e.g. Keys) is ignored.

deep - If true, the enumeration returned contains all instances of the specified class and all classes derived from it. If false, only names of instances of the specified class are returned.

localOnly - If true, only elements (properties, methods, references) overridden or defined in the class are included in the instances returned.

includeQualifiers - If true, all Qualifiers for each instance are included in the instances returned. If false, no Qualifier information is contained in the Instances returned.

includeClassOrigin - If true, the CLASSORIGIN attribute will be present on all appropriate elements in the instances returned. If false, no CLASSORIGIN attributes are present in the instances returned. CLASSORIGIN is attached to an element (properties, methods, references) to indicate the class in which it was first defined.

propertyList - An array of property names used to filter what is contained in the instances returned. Each instance returned only contains elements for the properties of the names specified. Duplicate and invalid property names are ignored and the request is otherwise processed normally. An empty array indicates that no properties should be returned. A null value indicates that all properties should be returned.

Returns:

Enumeration of CIMInstance. Each instance is filtered as indicated by the parameters specified. If no CIMInstances of the specified class are found, null is returned.

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED,
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (for this method),
   CIM_ERR_INVALID_CLASS (in this namespace),
   CIM_ERR_FAILED (some other unspecified error occurred)
 	

enumQualifierTypes

public java.util.Enumeration enumQualifierTypes(CIMObjectPath path)
                                         throws CIMException

Enumerates the qualifiers defined in the specified namespace.

Specified by:

enumQualifierTypes in interface CIMOMHandle

Parameters:

path - The CIMObjectPath identifying the namespace whose qualifier definitions are to be enumerated.

Returns:

Enumeration of CIMQualifierType objects. If no qualifiers are found, null is returned.

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED,
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized 
   or otherwise incorrect parameters),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

execQuery

public java.util.Enumeration execQuery(CIMObjectPath path,
                                       java.lang.String query,
                                       java.lang.String ql)
                                throws CIMException

Executes a query to retrieve objects. The WBEM Query Language (WQL) is a subset of standard American National Standards Institute Structured Query Language (ANSI SQL) with semantic changes to support WBEM. In this release, unlike SQL, WQL is a retrieval-only language. WQL cannot be used to modify, insert, or delete information. For more information on WQL and constructing a query, see the Developer's Guide.

NOTE: The CIMInstances returned by this method contain all Qualifier information, all local and inherited elements (properties, methods, references), and CLASSORIGIN information.

Specified by:

execQuery in interface CIMOMHandle

Parameters:

path - CIMObjectPath identifying the class to query. Only the namespace and class name components are used. All other information (e.g. Keys) is ignored.

query - A string containing the text of the query. The value specified cannot be null.

ql - A string that identifies the query language to use to parse the query string specified. (e.g. "WQL") WQL Level 1 is currently the only supported query language.

Returns:

An enumeration of all CIMInstances of the specified class and instances of all classes derived from the specified class, that match the query string.

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

    CIM_ERR_ACCESS_DENIED,
    CIM_ERR_NOT_SUPPORTED (provider does not support this method),
    CIM_ERR_INVALID_NAMESPACE,
    CIM_ERR_INVALID_PARAMETER (including missing, duplicate, 
    unrecognized or otherwise incorrect parameters),
    CIM_ERR_QUERY_LANGUAGE_NOT_SUPPORTED (the requested query language is
    not recognized),
    CIM_ERR_INVALID_QUERY (the query is not a valid query in the specified
    query language),
    CIM_ERR_FAILED (some other unspecified error occurred)
 

getClass

public CIMClass getClass(CIMObjectPath name,
                         boolean localOnly,
                         boolean includeQualifiers,
                         boolean includeClassOrigin,
                         java.lang.String[] propertyList)
                  throws CIMException

Returns the CIMClass for the specified CIMObjectPath.

Specified by:

getClass in interface CIMOMHandle

Parameters:

name - The object path of the class to be returned. Only the name space and class name components are used. All other information (e.g. keys) is ignored.

localOnly - If true, only elements (properties, methods, references) overridden or defined in the class are included in the CIMClass returned. If false, all elements of the class definition are returned.

includeQualifiers - If true, all Qualifiers for the class and its elements are included in the CIMClass returned. If false, no Qualifier information is contained in the CIMClass returned.

includeClassOrigin - If true, the CLASSORIGIN attribute will be present on all appropriate elements in the CIMClass returned. If false, no CLASSORIGIN attributes are present in the CIMClass returned. CLASSORIGIN is attached to an element (properties, methods, references) to indicate the class in which it was first defined.

propertyList - An array of property names used to filter what is contained in the CIMClass returned. The CIMClass returned only contains elements for the properties of the names specified. Duplicate and invalid property names are ignored and the request is otherwise processed normally. An empty array indicates that no properties should be returned. A null value indicates that all properties should be returned.

Returns:

The CIM class identified by the CIMObjectPath

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized 
   or otherwise incorrect parameters),
   CIM_ERR_NOT_FOUND (the request CIM Class does not exist in the
   specified namespace) 
   CIM_ERR_FAILED (some other unspecified error occurred)
 

See Also:

enumerateClasses(CIMObjectPath), enumerateClassNames(CIMObjectPath)

getIndicationListener

public CIMInstance getIndicationListener(CIMListener cl)
                                  throws CIMException

This method returns an Instance of the subclass of CIM_ListenerDestination defined for the client's protocol. Thus, for HTTP, an Instance of CIM_ListenerDestinationCIMXML is returned. For RMI, an Instance of the subclass of CIM_ListenerDestination defined for RMI is returned. The returned Instance of the subclass of CIM_ListenerDestination should then be passed to createInstance() to establish a handler in the WBEM Server. Using this method, a client can create a protocol independent implementation for creating a CIM_ListenerDestination subclass Instance.

Parameters:

cl - CIMListener for which a CIM_ListenerDestination subclass is being returned. If null, the Instance of the CIM_ListenerDestination subclass returned can be used to deliver Indications to all listeners that have been added by the addCIMListener() call. If non-null, the returned handler can be used to deliver Indications to a specific listener. NOTE: Unique listeners should return unique values in their hashCode methods in order to be differentiated. Also note that some implementations may have partial support. For example, they may set cl to null or non-null.

Returns:

Instance of the CIM_ListenerDestination subclass defined for the client's protocol.

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED (if CIMOM does not support events),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

getInstance

public CIMInstance getInstance(CIMObjectPath name,
                               boolean localOnly,
                               boolean includeQualifiers,
                               boolean includeClassOrigin,
                               java.lang.String[] propertyList)
                        throws CIMException

Returns the CIMInstance for the specified CIMObjectPath.

Specified by:

getInstance in interface CIMOMHandle

Parameters:

name - The object path of the instance to be returned. The Keys in this CIMObjectPath must be populated.

localOnly - If true, only elements (properties, methods, references) overridden or defined in the class are included in the CIMInstance returned. If false, all elements of the class definition are returned.

includeQualifiers - If true, all Qualifiers for the instance and its elements are included in the CIMInstance returned. If false, no Qualifier information is contained in the CIMInstance returned.

includeClassOrigin - If true, the CLASSORIGIN attribute will be present on all appropriate elements in the CIMInstance returned. If false, no CLASSORIGIN attributes are present in the CIMInstance returned. CLASSORIGIN is attached to an element (properties, methods, references) to indicate the class in which it was first defined.

propertyList - An array of property names used to filter what is contained in the CIMClass returned. The CIMClass returned only contains elements for the properties of the names specified. Duplicate and invalid property names are ignored and the request is otherwise processed normally. An empty array indicates that no properties should be returned. A null value indicates that all properties should be returned.

Returns:

The CIM instance identified by the CIMObjectPath specified.

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED (provider does not support this method),
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (for this method),
   CIM_ERR_INVALID_CLASS (in this namespace),
   CIM_ERR_NOT_FOUND (if instance does not exist),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

See Also:

enumerateInstances(CIMObjectPath), enumerateInstanceNames(CIMObjectPath)

getQualifierType

public CIMQualifierType getQualifierType(CIMObjectPath name)
                                  throws CIMException

Gets the CIMQualifierType specified.

Specified by:

getQualifierType in interface CIMOMHandle

Parameters:

name - CIMObjectPath that identifies the CIMQualifierType to return.

Returns:

The CIMQualifierType object

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED,
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized 
   or otherwise incorrect parameters),
   CIM_ERR_NOT_FOUND (the requested Qualifier declaration did not exist),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

invokeMethod

public CIMValue invokeMethod(CIMObjectPath name,
                             java.lang.String methodName,
                             CIMArgument[] inArgs,
                             CIMArgument[] outArgs)
                      throws CIMException

Executes the specified method on the specified object.

Specified by:

invokeMethod in interface CIMOMHandle

Parameters:

name - CIM object path of the object whose method must be invoked. It must include all of the keys.

methodName - the name of the method to be invoked.

inArgs - the CIMArgument array of method input parameters.

outArgs - the CIMArgument array of method output parameters. The array should be allocated large enough to hold all returned parameters, but should not initialize any elements.

Returns:

The return value of the specified method.

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

 
   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED (CIM Server DOES NOT support ANY
   Extrinsic Method Invocation),
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (for this method),
   CIM_ERR_NOT_FOUND (if instance does not exist),
   CIM_ERR_METHOD_NOT_FOUND,
   CIM_ERR_METHOD_NOT_AVAILABLE,
   CIM_ERR_FAILED (some other unspecified error occurred)
 

performBatchOperations

public BatchResult performBatchOperations(BatchHandle bc)
                                   throws CIMException

Executes the batch operations contained in the specified BatchHandle object. A BatchResult object is returned that contains the return value or CIMException result from the execution of each operation. The operations are performed in the order in which they were specified in the BatchHandle argument.

Example:

The following code example demonstrates how to enumerate instances of Classes CIM_Foo and CIM_Bar as batch operations.

 BatchCIMClient batchClient = new BatchCIMClient();
 CIMObjectPath fooCOP = new CIMObjectPath("CIM_Foo"); 
 CIMObjectPath barCOP = new CIMObjectPath("CIM_Bar"); 
 int enumFooID = batchClient.enumerateInstances(fooCOP,
         false, true, false, false, null); 
 int enumBarID = batchClient.enumerateInstances(barCOP,
         false, true, false, false, null);
 // perform the Batch operations on an existing CIMOMHandle
 BatchResult batchRes = cimomHandle.performBatchOperations(
         batchClient);
 

Specified by:

performBatchOperations in interface CIMOMHandle

Parameters:

bc - The BatchHandle that contains the list of operations to be performed.

Returns:

BatchResult containing the return value or CIMException result from the execution of each operation.

Throws:

CIMException - If batch mode is turned off or the list of CIM operations is null.

referenceNames

public java.util.Enumeration referenceNames(CIMObjectPath objectName,
                                            java.lang.String resultClass,
                                            java.lang.String role)
                                     throws CIMException

Enumerates the CIMObjectPaths of Association Objects that are refer to a particular source CIM Object. If the source Object is a CIM Class, then an Enumeration of CIMObjectPaths of the Association classes that refer to the source Object is returned. If the source Object is a CIM Instance, then an Enumeration of CIMObjectPaths of the CIMInstance objects that refer to the source Object is returned.

Specified by:

referenceNames in interface CIMOMHandle

Parameters:

objectName - CIMObjectPath defining the source CIM Object whose referring Objects are to be returned. This argument may contain either a Class name or the modelpath of an Instance. (i.e. Keys populated)

resultClass - This string MUST either contain a valid CIM Class name or be null. It filters the Objects returned to contain only the Objects of this Class name or one of its subclasses.

role - This string MUST either contain a valid Property name or be null. It filters the Objects returned to contain only Objects referring to the source Object via a Property with the specified name. If "Antecedent" is specified, then only Associations in which the source Object is the "Antecedent" reference are returned.

Returns:

If successful, an Enumeration containing zero or more CIMObjectPath objects of the CIM Classes or CIM Instances meeting the specified criteria is returned. If no such Objects are found, null is returned.

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED
   CIM_ERR_NOT_SUPPORTED
   CIM_ERR_INVALID_NAMESPACE
   CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized 
   or otherwise incorrect parameters)
   CIM_ERR_FAILED (some other unspecified error occurred)
 

references

public java.util.Enumeration references(CIMObjectPath objectName,
                                        java.lang.String resultClass,
                                        java.lang.String role,
                                        boolean includeQualifiers,
                                        boolean includeClassOrigin,
                                        java.lang.String[] propertyList)
                                 throws CIMException

Enumerates the Association Objects that refer to a specified source CIM Object. If the source Object is a CIM Class, an Enumeration of CIMClass objects is returned containing the Association classes that refer to the source Object. If the source Object is a CIM Instance, an Enumeration of CIMInstance objects is returned containing the Association class instances that refer to the source Object.

Specified by:

references in interface CIMOMHandle

Parameters:

objectName - CIMObjectPath defining the source CIM Object whose referring Objects are to be returned. This argument may contain either a Class name or the modelpath of an Instance. (i.e. Keys populated)

resultClass - This string MUST either contain a valid CIM Class name or be null. It filters the Objects returned to contain only the Objects of this Class name or one of its subclasses.

role - This string MUST either contain a valid Property name or be null. It filters the Objects returned to contain only Objects referring to the source Object via a Property with the specified name. If "Antecedent" is specified, then only Associations in which the source Object is the "Antecedent" reference are returned.

includeQualifiers - If true, all Qualifiers for each Object (including Qualifiers on the Object and on any returned Properties) MUST be included in the Objects returned. If false, no Qualifiers are present in each Object returned.

includeClassOrigin - If true, the CLASSORIGIN attribute will be present on all appropriate elements in the Objects returned. If false, no CLASSORIGIN attributes are present in the Objects returned. CLASSORIGIN is attached to an element (properties, methods, references) to indicate the class in which it was first defined.

propertyList - An array of property names used to filter what is contained in the Objects returned. Each CIMClass or CIMInstance returned only contains elements for the properties of the names specified. Duplicate and invalid property names are ignored and the request is otherwise processed normally. An empty array indicates that no properties should be included in the Objects returned. A null value indicates that all properties should be contained in the Objects returned. NOTE: Properties should not be specified in this parameter unless a non-null value is specified in the resultClass parameter.

Returns:

If successful, an Enumeration containing zero or more CIMClass or CIMInstance Objects meeting the specified criteria is returned. If no such Objects are found, null is returned.

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED
   CIM_ERR_NOT_SUPPORTED
   CIM_ERR_INVALID_NAMESPACE
   CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized 
   or otherwise incorrect parameters)
   CIM_ERR_FAILED (some other unspecified error occurred)
 

removeCIMListener

public void removeCIMListener(CIMListener l)
                       throws CIMException

Removes the specified CIMListener that is receiving Indications from the CIM Server. No exception is thrown if the specified CIMListener is null or if it is not receiving Indications from the CIM Server.

Specified by:

removeCIMListener in interface CIMOMHandle

Parameters:

l - The CIMListener to remove from the CIM Server.

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED (if CIMOM does not support events),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

setClass

public void setClass(CIMObjectPath name,
                     CIMClass cc)
              throws CIMException

Modifies the CIMClass in the specified namespace.

Specified by:

setClass in interface CIMOMHandle

Parameters:

name - CIMObjectPath that identifies the CIM class to be modified

cc - CIMClass to be modified

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED,
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized 
   or otherwise incorrect parameters),
   CIM_ERR_INVALID_SUPERCLASS (the putative CIM Class declares a
   non-existent superclass),
   CIM_ERR_CLASS_HAS_CHILDREN (the modification could not be performed
   because it was not possible to update the subclasses of the Class
   in a consistent fashion),
   CIM_ERR_CLASS_HAS_INSTANCES (the modification could not be performed
   because it was not possible to update the instances of the Class in
   a consistent fashion)  
   CIM_ERR_FAILED (some other unspecified error occurred)
 

setInstance

public void setInstance(CIMObjectPath name,
                        CIMInstance ci,
                        boolean includeQualifiers,
                        java.lang.String[] propertyList)
                 throws CIMException

Modifies some or all of the properties of the specified CIMInstance in the specified namespace.

Specified by:

setInstance in interface CIMOMHandle

Parameters:

name - CIMObjectPath that identifies the namespace in which the specified CIMInstance should be modified. All other information (e.g. Keys) is ignored.

ci - CIMInstance to be modified. Its properties may be initialized by either the client or server.

includeQualifiers - This argument is ignored. Qualifiers cannot be modified on a per-Instance basis. It exists for backward compatibility only.

propertyList - An array of property names used to specify which values from the CIMInstance specified to set. Properties not specified in this list but set in the CIMInstance specified are not modified. Duplicate and invalid property names are ignored and the request is otherwise processed normally. An empty array indicates that no properties should be modified. A null value indicates that all properties should be modified.

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED (provider does not support this method),
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (for this method),
   CIM_ERR_INVALID_CLASS (in this namespace),
   CIM_ERR_NOT_FOUND (if instance does not exist),
   CIM_ERR_NO_SUCH_PROPERTY (in this instance),
   CIM_ERR_FAILED (some other unspecified error occurred)
 

setQualifierType

public void setQualifierType(CIMObjectPath name,
                             CIMQualifierType qt)
                      throws CIMException

Adds the specified CIMQualifierType to the specified namespace if it does not already exist. Otherwise, it sets the qualifier type to the value specified.

Specified by:

setQualifierType in interface CIMOMHandle

Parameters:

name - CIM object path that identifies the CIM qualifier type

qt - the CIM qualifier type to be added

Throws:

CIMException - If unsuccessful, one of the following status codes must be returned. The ORDERED list is:

   CIM_ERR_ACCESS_DENIED,
   CIM_ERR_NOT_SUPPORTED,
   CIM_ERR_INVALID_NAMESPACE,
   CIM_ERR_INVALID_PARAMETER (including missing, duplicate, unrecognized 
   or otherwise incorrect parameters),
   CIM_ERR_FAILED (some other unspecified error occurred)