(file) Return to CIMInstanceProvider.h CVS log (file) (dir) Up to [Pegasus] / pegasus / src / Pegasus / Provider

Diff for /pegasus/src/Pegasus/Provider/CIMInstanceProvider.h between version 1.25 and 1.26

version 1.25, 2006/11/14 18:34:54 version 1.26, 2008/02/27 20:28:19
Line 50 
Line 50 
  
 <p>The Instance Provider is the most common provider, and <p>The Instance Provider is the most common provider, and
 is the provider interface used by the CIM Server to perform instance is the provider interface used by the CIM Server to perform instance
 and property  and property manipulation operations.</p>
 manipulation requests from CIM clients. Instance providers  
 may be implemented for any CIM class, including <i>Association</i>  
 classes.</p>  
   
 <p>In addition to  
 functions inherited from the  
 {@link CIMProvider CIMProvider} interface,  
 the functions in the Instance Provider interface are:</p>  
   
 <p><ul>  
 <li>{@link getInstance getInstance}</li>  
 <li>{@link enumerateInstances enumerateInstances}</li>  
 <li>{@link enumerateInstanceNames enumerateInstanceNames}</li>  
 <li>{@link modifyInstance modifyInstance}</li>  
 <li>{@link createInstance createInstance}</li>  
 <li>{@link deleteInstance deleteInstance}</li>  
 </ul></p>  
  
 <p>The Instance Provider receives operation requests from <p>The Instance Provider receives operation requests from
 clients through calls to these functions by the CIM Server. Its clients through calls to these functions by the CIM Server. Its
Line 93 
Line 76 
     virtual ~CIMInstanceProvider();     virtual ~CIMInstanceProvider();
  
     /**     /**
         \Label{getInstance}  
         Return a single instance.         Return a single instance.
  
         <p><tt>getInstance</tt> is called with an          <p><tt>getInstance</tt> is called with a CIMObjectPath
         {@link CIMObjectPath instanceReference} specifying a CIM          <tt>instanceReference</tt> specifying a CIM instance to be returned.
         instance to be returned. The provider should determine whether          The provider should determine whether the specification corresponds to
         the specification corresponds to a valid instance. If so, it will          a valid instance. If so, it will construct a <tt>CIMInstance</tt>
         construct a <tt>{@link CIMInstance CIMInstance}</tt>          and deliver this to the CIM Server via the <tt>ResponseHandler</tt>
         and deliver this to the CIM Server via the  
         <tt>{@link ResponseHandler ResponseHandler}</tt>  
         callback. If the specified instance does not exist, this         callback. If the specified instance does not exist, this
         function should throw an          function should throw a CIMObjectNotFoundException.
         <tt>{@link CIMObjectNotFoundException CIMObjectNotFoundException}.</tt>  
         </p>         </p>
  
         <p>A provider can be implemented and registered to perform         <p>A provider can be implemented and registered to perform
         operations for          operations for several levels of the same line of descent (e.g.,
         several levels of the same line of descent (e.g.,  
         CIM_ComputerSystem and CIM_UnitaryComputerSystem). When this         CIM_ComputerSystem and CIM_UnitaryComputerSystem). When this
         is done, care must be taken to return the same set of key         is done, care must be taken to return the same set of key
         values regardless of which class was specified in the         values regardless of which class was specified in the
Line 141 
Line 119 
         If the propertyList is NULL all properties are returned.  If it is         If the propertyList is NULL all properties are returned.  If it is
         nonNULL but empty, no properites are to be returned.         nonNULL but empty, no properites are to be returned.
  
         @param handler a {@link ResponseHandler ResponseHandler} object used          @param handler ResponseHandler object for delivery of results.
         to deliver results to the CIM Server.  
  
         @exception CIMNotSupportedException         @exception CIMNotSupportedException
         @exception CIMInvalidParameterException         @exception CIMInvalidParameterException
Line 159 
Line 136 
         InstanceResponseHandler& handler) = 0;         InstanceResponseHandler& handler) = 0;
  
     /**     /**
         \Label{enumerateInstances}  
         Return all instances of the specified class.         Return all instances of the specified class.
  
         <p>A typical implementation of this function will call the         <p>A typical implementation of this function will call the
         <tt>{@link processing processing}</tt> function in the          <tt>processing</tt> function in the <tt>ResponseHandler</tt> object,
         <tt>{@link ResponseHandler handler}</tt> object, then          then iterate over the system resources representing instances of
         iterate over the system resources representing instances of          the CIM object, calling <tt>deliver</tt> on each iteration. It must
         the CIM object, calling <tt>{@link deliver deliver}</tt> on          call <tt>deliver</tt> with an argument of type <tt>CIMInstance</tt>.
         each iteration. It must call <tt>deliver</tt> with an          Finally, it will call <tt>complete</tt> to inform the CIM Server that
         argument of type <tt>{@link CIMInstance CIMInstance}</tt>.          it has delivered all known instances. It is correct to call
         Finally, it will call <tt>{@link complete complete}</tt> to          <tt>complete</tt> without calling <tt>deliver</tt> if no instances
         inform the CIM Server that it has delivered all known instances.</p>          exist.</p>
  
         <p>A provider can be implemented and registered to perform         <p>A provider can be implemented and registered to perform
         operations for several levels of the same line of descent (e.g.,         operations for several levels of the same line of descent (e.g.,
Line 178 
Line 154 
         is done, the provider must return instances <i>only</i>         is done, the provider must return instances <i>only</i>
         for the deepest class for which it is registered, since         for the deepest class for which it is registered, since
         the CIM Server will invoke <tt>enumerateInstances</tt> for all         the CIM Server will invoke <tt>enumerateInstances</tt> for all
         classes at and beneath that specified in the          classes at and beneath that specified in the classReference.</p>
         {@link CIMObjectPath classReference}.</p>  
  
         @param context specifies the client user's context for this operation,         @param context specifies the client user's context for this operation,
         including the User ID.         including the User ID.
Line 202 
Line 177 
         or deepInheritance.  These are resolved in the CIM Server into the         or deepInheritance.  These are resolved in the CIM Server into the
         propertyList.         propertyList.
  
         @param handler {@link ResponseHandler ResponseHandler} object for          @param handler ResponseHandler object for delivery of results.
         delivery of results.  
  
         @exception CIMNotSupportedException         @exception CIMNotSupportedException
         @exception CIMInvalidParameterException         @exception CIMInvalidParameterException
         @exception CIMObjectNotFoundException  
         <br>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 <tt>{@link processing processing} </tt> and  
         <tt>{@link complete complete}</tt> functions without calling  
         <tt>{@link deliver deliver}</tt>.  
   
         @exception CIMAccessDeniedException         @exception CIMAccessDeniedException
         @exception CIMOperationFailedException         @exception CIMOperationFailedException
     */     */
Line 227 
Line 193 
         InstanceResponseHandler& handler) = 0;         InstanceResponseHandler& handler) = 0;
  
     /**     /**
         \Label{enumerateInstanceNames}  
         Return all instance names of a single class.         Return all instance names of a single class.
  
         <p>Like <tt>enumerateInstances</tt>, a typical implementation         <p>Like <tt>enumerateInstances</tt>, a typical implementation
         of <tt>enumerateInstanceNames</tt> will call the          of <tt>enumerateInstanceNames</tt> will call the <tt>processing</tt>
         <tt>{@link processing processing}</tt> function in the          function in the <tt>ResponseHandler</tt> object, then
         <tt>{@link ResponseHandler handler}</tt> object, then  
         iterate over the system resources representing instances of         iterate over the system resources representing instances of
         the CIM object, calling <tt>{@link deliver deliver}</tt> on          the CIM object, calling <tt>deliver</tt> on each iteration. It must
         each iteration. It must call {@link deliver deliver} with an          call <tt>deliver</tt> with an argument of type <tt>CIMObjectPath</tt>
         argument of type <tt>{@link CIMObjectPath CIMObjectPath}</tt>          containing the information that uniquely identifies each instance.
         containing the information that uniquely identifies each          Finally, it will call <tt>complete</tt> to inform the CIM Server that
         instance.          it has delivered the names of all known instances. It is correct to
         Finally, it will call <tt>{@link complete complete}</tt> to          call <tt>complete</tt> without calling <tt>deliver</tt> if no instances
         inform the CIM Server that it has delivered all known instances.</p>          exist.</p>
  
         <p>A provider can be implemented and registered to perform         <p>A provider can be implemented and registered to perform
         operations for several levels of the same line of descent (e.g.,         operations for several levels of the same line of descent (e.g.,
Line 250 
Line 214 
         for the deepest class for which it is registered, since         for the deepest class for which it is registered, since
         the CIM Server will invoke <tt>enumerateInstanceNames</tt> for all         the CIM Server will invoke <tt>enumerateInstanceNames</tt> for all
         classes at and beneath that specified in the         classes at and beneath that specified in the
         {@link CIMObjectPath classReference}.</p>          classReference.</p>
  
         @param context specifies the client user's context for this operation,         @param context specifies the client user's context for this operation,
         including the User ID.         including the User ID.
Line 258 
Line 222 
         @param classReference specifies the fully qualified object path to         @param classReference specifies the fully qualified object path to
         the class of interest.         the class of interest.
  
         @param handler {@link ResponseHandler ResponseHandler} object for          @param handler ResponseHandler object for delivery of results.
         delivery of results.  
  
         @exception CIMNotSupportedException         @exception CIMNotSupportedException
         @exception CIMInvalidParameterException         @exception CIMInvalidParameterException
         @exception CIMObjectNotFoundException  
         @exception CIMAccessDeniedException         @exception CIMAccessDeniedException
         @exception CIMOperationFailedException         @exception CIMOperationFailedException
     */     */
Line 273 
Line 235 
         ObjectPathResponseHandler& handler) = 0;         ObjectPathResponseHandler& handler) = 0;
  
     /**     /**
         \Label{modifyInstance}  
         Replace the current instance specified in the         Replace the current instance specified in the
         instanceReference parameter.         instanceReference parameter.
  
Line 298 
Line 259 
         possibly inconsistent, results.</p>         possibly inconsistent, results.</p>
  
         <p>If the specified instance does not exist, the provider         <p>If the specified instance does not exist, the provider
         should throw an {@link CIMObjectNotFoundException ObjectNotFound}          should throw an CIMObjectNotFoundException.
         exception.  
  
         @param context specifies the client user's context for this operation,         @param context specifies the client user's context for this operation,
         including the User ID.         including the User ID.
Line 317 
Line 277 
         @param propertyList If not null, this parameter specifies the set         @param propertyList If not null, this parameter specifies the set
         of properties required to be updated in the instance. Support for         of properties required to be updated in the instance. Support for
         this parameter is NOT optional.  Providers that do not support this         this parameter is NOT optional.  Providers that do not support this
         feature must throw a          feature must throw a CIMNotSupportedException.
         {@link CIMNotSupportedException CIMNotSupportedException} exception.  
         NOTE: The provider does NOT receive the client filtering parameters         NOTE: The provider does NOT receive the client filtering parameters
         localOnly or deepInheritance.  These are resolved in the CIMOM into         localOnly or deepInheritance.  These are resolved in the CIMOM into
         the propertyList.         the propertyList.
  
         @param handler {@link ResponseHandler ResponseHandler} object for          @param handler ResponseHandler} object for delivery of results.
         delivery of results.  
  
         @exception CIMNotSupportedException         @exception CIMNotSupportedException
         @exception CIMInvalidParameterException         @exception CIMInvalidParameterException
Line 341 
Line 299 
         ResponseHandler& handler) = 0;         ResponseHandler& handler) = 0;
  
     /**     /**
         \Label{createInstance}  
         Create a new instance.         Create a new instance.
  
         <p>Create a new instance of the specified class as specified         <p>Create a new instance of the specified class as specified
Line 358 
Line 315 
  
         @param instanceObject contains the partial or complete instance to         @param instanceObject contains the partial or complete instance to
         create.  If a key property is null, the provider <em>must</em> supply         create.  If a key property is null, the provider <em>must</em> supply
         a valid value for the property or throw a          a valid value for the property or throw a CIMInvalidParameterException.
         {@link CIMInvalidParameterException CIMInvalidParameterException}.  
         If any property value is invalid, the provider should throw a         If any property value is invalid, the provider should throw a
         {@link CIMInvalidParameterException CIMInvalidParameterException}.          CIMInvalidParameterException.
  
         @param handler {@link ResponseHandler ResponseHandler} object for          @param handler ResponseHandler object for delivery of results.  If the
         delivery of results.  If the operation is successful, the provider must          operation is successful, the provider must deliver the complete
         deliver the complete instance name of the created instance.          instance name of the created instance.
  
         @exception CIMNotSupportedException         @exception CIMNotSupportedException
         @exception CIMInvalidParameterException         @exception CIMInvalidParameterException
Line 380 
Line 336 
         ObjectPathResponseHandler& handler) = 0;         ObjectPathResponseHandler& handler) = 0;
  
     /**     /**
         \Label{deleteInstance}  
         Delete the instance specified by the instanceReference parameter.         Delete the instance specified by the instanceReference parameter.
  
         @param context specifies the client user's context for this operation,         @param context specifies the client user's context for this operation,
Line 388 
Line 343 
  
         @param instanceReference specifies the fully qualified object         @param instanceReference specifies the fully qualified object
         path of the instance to delete. If the specified object does         path of the instance to delete. If the specified object does
         not exist, the provider should throw an          not exist, the provider should throw a CIMObjectNotFoundException.
         {@link CIMObjectNotFoundException ObjectNotFound} exception.  
  
         @param handler {@link ResponseHandler ResponseHandler} object for          @param handler ResponseHandler object for delivery of results.
         delivery of results.  
  
         @exception CIMNotSupportedException         @exception CIMNotSupportedException
         @exception CIMInvalidParameterException         @exception CIMInvalidParameterException

Legend:
Removed from v.1.25  
changed lines
  Added in v.1.26
No CVS admin address has been configured
 Powered by
ViewCVS 0.9.2