This class defines a set of functions that support the manipulation of instances of a CIM object class and their properties.

Documentation

This class defines a set of functions that support the manipulation of instances of a CIM object class and their properties.

The Instance Provider is the most common provider, and is the provider interface used by the CIM Server to perform instance and property manipulation requests from CIM clients. Instance providers may be implemented for any CIM class, including Association classes.

In addition to functions inherited from the CIMProvider interface, the functions in the Instance Provider interface are:

• getInstance
• enumerateInstances
• enumerateInstanceNames
• modifyInstance
• createInstance
• deleteInstance

The Instance Provider receives operation requests from clients through calls to these functions by the CIM Server. Its purpose is to convert these to calls to system services, operations on system resources, or whatever platform-specific behavior is required to perform the operation modeled by the request. The specific requirements for each of the interface functions are discussed in their respective sections.

Inheritance:

Public Methods

	CIMInstanceProvider (void) Constructor.
virtual	~CIMInstanceProvider (void) Destructor.
virtual void	getInstance ( const OperationContext & context, const CIMObjectPath & instanceReference, const Boolean includeQualifiers, const Boolean includeClassOrigin, const CIMPropertyList & propertyList, InstanceResponseHandler & handler) Return a single instance.
virtual void	enumerateInstances ( const OperationContext & context, const CIMObjectPath & classReference, const Boolean includeQualifiers, const Boolean includeClassOrigin, const CIMPropertyList & propertyList, InstanceResponseHandler & handler) Return all instances of the specified class.
virtual void	enumerateInstanceNames ( const OperationContext & context, const CIMObjectPath & classReference, ObjectPathResponseHandler & handler) Return all instance names of a single class.
virtual void	modifyInstance ( const OperationContext & context, const CIMObjectPath & instanceReference, const CIMInstance & instanceObject, const Boolean includeQualifiers, const CIMPropertyList & propertyList, ResponseHandler & handler) Replace the current instance specified in the instanceReference parameter.
virtual void	createInstance ( const OperationContext & context, const CIMObjectPath & instanceReference, const CIMInstance & instanceObject, ObjectPathResponseHandler & handler) Create a new instance.
virtual void	deleteInstance ( const OperationContext & context, const CIMObjectPath & instanceReference, ResponseHandler & handler) Delete the instance specified by the instanceReference parameter.

Inherited from CIMProvider:

Public Methods

virtual void initialize(CIMOMHandle & cimom)

virtual void terminate(void)

virtual Boolean tryTerminate(void)

CIMInstanceProvider(void)

Constructor. The constructor should not do anything.

virtual ~CIMInstanceProvider(void)

Destructor. The destructor should not do anything.

virtual void getInstance( const OperationContext & context, const CIMObjectPath & instanceReference, const Boolean includeQualifiers, const Boolean includeClassOrigin, const CIMPropertyList & propertyList, InstanceResponseHandler & handler) = 0

Return a single instance.

getInstance is called with an instanceReference specifying a CIM instance to be returned. The provider should determine whether the specification corresponds to a valid instance. If so, it will construct a CIMInstance and deliver this to the CIM Server via the ResponseHandler callback. If the specified instance does not exist, this function should throw an CIMObjectNotFoundException.

A provider can be implemented and registered to perform operations for several levels of the same line of descent (e.g., CIM_ComputerSystem and CIM_UnitaryComputerSystem). When this is done, care must be taken to return the same set of key values regardless of which class was specified in the operation.

Throws:

CIMNotSupportedException
CIMInvalidParameterException
CIMObjectNotFoundException
CIMAccessDeniedException
CIMOperationFailedException

Parameters:

context - specifies the client user's context for this operation, including the User ID.
instanceReference - specifies the fully qualified object path of the instance of interest.
includeQualifiers - indicates whether the returned instance must include the qualifiers for the instance and properties. Qualifiers may be included even if this flag is false.
includeClassOrigin - indicates whether the returned instance must include the class origin for each of the instance elements.
propertyList - if not null, this parameter specifies the minimum set of properties required in instances returned by this operation. Because support for this parameter is optional, the instances may contain additional properties not specified in the list. NOTE: The provider does NOT receive the client filtering parameter localOnly. This is resolved in the CIMOM into the propertyList so that the property list represents the complete set of properties to be returned. If the propertyList is NULL all properties are returned. If it is nonNULL but empty, no properites are to be returned.
handler - a ResponseHandler object used to deliver results to the CIM Server.

virtual void enumerateInstances( const OperationContext & context, const CIMObjectPath & classReference, const Boolean includeQualifiers, const Boolean includeClassOrigin, const CIMPropertyList & propertyList, InstanceResponseHandler & handler) = 0

Return all instances of the specified class.

A typical implementation of this function will call the processing function in the handler object, then iterate over the system resources representing instances of the CIM object, calling deliver on each iteration. It must call deliver with an argument of type CIMInstance. Finally, it will call complete to inform the CIM Server that it has delivered all known instances.

A provider can be implemented and registered to perform operations for several levels of the same line of descent (e.g., CIM_ComputerSystem and CIM_UnitaryComputerSystem). When this is done, the provider must return instances only for the deepest class for which it is registered, since the CIM Server will invoke enumerateInstances for all classes at and beneath that specified in the classReference.

Throws:

CIMNotSupportedException
CIMInvalidParameterException
CIMObjectNotFoundException
should never be thrown by this function; if there are no instances to return, this function should deliver an empty set of instances by calling the handler's processing and complete functions without calling deliver.
CIMAccessDeniedException
CIMOperationFailedException

Parameters:

context - specifies the client user's context for this operation, including the User ID.
classReference - specifies the fully qualified object path to the class of interest.
includeQualifiers - indicates whether the returned instances must include the qualifiers for the instance and properties. Qualifiers may be included even if this flag is false.
includeClassOrigin - indicates whether the returned instances must include the class origin for each of the instance elements.
propertyList - If not null, this parameter specifies the minimum set of properties required in instances returned by this operation. Because support for this parameter is optional, the instances may contain additional properties not specified in the list. NOTE: The provider does NOT receive the client filtering parameters localOnly or deepInheritance. These are resolved in the CIMOM into the propertyList.
handler - ResponseHandler object for delivery of results.

virtual void enumerateInstanceNames( const OperationContext & context, const CIMObjectPath & classReference, ObjectPathResponseHandler & handler) = 0

Return all instance names of a single class.

Like enumerateInstances, a typical implementation of enumerateInstanceNames will call the processing function in the handler object, then iterate over the system resources representing instances of the CIM object, calling deliver on each iteration. It must call deliver with an argument of type CIMObjectPath containing the information that uniquely identifies each instance. Finally, it will call complete to inform the CIM Server that it has delivered all known instances.

A provider can be implemented and registered to perform operations for several levels of the same line of descent (e.g., CIM_ComputerSystem and CIM_UnitaryComputerSystem). When this is done, the provider must return instance names only for the deepest class for which it is registered, since the CIM Server will invoke enumerateInstanceNames for all classes at and beneath that specified in the classReference.

Throws:

CIMNotSupportedException
CIMInvalidParameterException
CIMObjectNotFoundException
CIMAccessDeniedException
CIMOperationFailedException

Parameters:

context - specifies the client user's context for this operation, including the User ID.
classReference - specifies the fully qualified object path to the class of interest.
handler - ResponseHandler object for delivery of results.

virtual void modifyInstance( const OperationContext & context, const CIMObjectPath & instanceReference, const CIMInstance & instanceObject, const Boolean includeQualifiers, const CIMPropertyList & propertyList, ResponseHandler & handler) = 0

Replace the current instance specified in the instanceReference parameter.

modifyInstance sets the values of properties of the instance specified by the instanceReference parameter to those specified in the instanceObject parameter, as controlled by the propertyList parameter. If the propertyList is NULL, then the operation sets all properties. Otherwise, it sets only those specified in the propertyList. Properties specified in the propertyList but not present in the instanceObject are replaced by the class default values or left null.

Ideally, modifyInstance is intended to be an atomic operation on values of the instance. That is, concurrent accesses to the instance by other threads should be blocked during the operation, so that all of the affected property values can be changed without intervening accesses by concurrent requests. Otherwise, other requests could obtain intermediate, and possibly inconsistent, results.

If the specified instance does not exist, the provider should throw an ObjectNotFound exception.

Throws:

CIMNotSupportedException
CIMInvalidParameterException
CIMObjectNotFoundException
CIMAccessDeniedException
CIMOperationFailedException

Parameters:

context - specifies the client user's context for this operation, including the User ID.
instanceReference - specifies the fully qualified object path of the instance of interest.
instanceObject - contains the partial or complete set of properties whose values should be changed.
includeQualifiers - indicates whether the instance qualifiers must be updated as specified in the modified instance. If false, no qualifiers are explicitly modified by this operation.
propertyList - If not null, this parameter specifies the set of properties required to be updated in the instance. Support for this parameter is NOT optional. Providers that do not support this feature must throw a CIMNotSupportedException exception. NOTE: The provider does NOT receive the client filtering parameters localOnly or deepInheritance. These are resolved in the CIMOM into the propertyList.
handler - ResponseHandler object for delivery of results.

virtual void createInstance( const OperationContext & context, const CIMObjectPath & instanceReference, const CIMInstance & instanceObject, ObjectPathResponseHandler & handler) = 0

Create a new instance.

Create a new instance of the specified class as specified by the instanceReference and instanceObject parameters.

Throws:

CIMNotSupportedException
CIMInvalidParameterException
CIMObjectAlreadyExistsException
CIMAccessDeniedException
CIMOperationFailedException

Parameters:

context - specifies the client user's context for this operation, including the User ID.
instanceReference - Specifies the namespace and class name of the instance to create. The key bindings are not present in the instanceReference, because an instance name is not defined until after the instance has been created.
instanceObject - contains the partial or complete instance to create. If a key property is null, the provider must supply a valid value for the property or throw a {@link CIMInvalidParameterException CIMInvalidParameterException}. If any property value is invalid, the provider should throw a {@link CIMInvalidParameterException CIMInvalidParameterException}.
handler - ResponseHandler object for delivery of results. If the operation is successful, the provider must deliver the complete instance name of the created instance.

virtual void deleteInstance( const OperationContext & context, const CIMObjectPath & instanceReference, ResponseHandler & handler) = 0

Delete the instance specified by the instanceReference parameter.

Throws:

CIMNotSupportedException
CIMInvalidParameterException
CIMObjectNotFoundException
CIMAccessDeniedException
CIMOperationFailedException

Parameters:

context - specifies the client user's context for this operation, including the User ID.
instanceReference - specifies the fully qualified object path of the instance to delete. If the specified object does not exist, the provider should throw an ObjectNotFound exception.
handler - ResponseHandler object for delivery of results.

This class has no child classes.

Alphabetic index HTML hierarchy of classes or Java