(file) Return to readme.pulloperations CVS log (file) (dir) Up to [Pegasus] / pegasus

Diff for /pegasus/readme.pulloperations between version 1.3 and 1.4

version 1.3, 2014/11/12 13:34:09 version 1.4, 2014/11/13 13:29:21
Line 1 
Line 1 
         Using the CIM/XML Pull Operations and FQL query Language         Using the CIM/XML Pull Operations and FQL query Language
  
   Date: 12 November 2014
   
 STATUS STATUS
  
 The Pull operations and FQL query language are incorporated into  The client pull operations and FQL query language are incorporated into
 OpenPegasus 2.14.  This readme defines the characteristics, limitations,  OpenPegasus 2.14. consistent and compatible with the DMTF specifications for
   the pull operations (DMTF DSP0200 v 1.4, and DMTF DSP0212 v 1.01.
   This readme defines the characteristics, limitations,
 etc. for that implementation. etc. for that implementation.
  
 =========================================== ===========================================
 OVERVIEW: OVERVIEW:
  
 The operation extensions for pull operations defined in the DMTF specification The operation extensions for pull operations defined in the DMTF specification
 DSP0200 V 1.4 were implemented in Pegasus effective Pegasus version 2.14  DSP0200 V 1.4 were implemented in OpenPegasus effective version 2.14
 including Client and Server. including Client and Server.
  
 These operations extend the CIM/XML  individual operations to operation These operations extend the CIM/XML  individual operations to operation
Line 20 
Line 24 
  
 The following new CIM/XML operations as defined in DSP0200 are included; The following new CIM/XML operations as defined in DSP0200 are included;
  
     -OpenEnumerateInstances      -openEnumerateInstances
     -OpenEnumerateInstancePaths      -openEnumerateInstancePaths
     -OpenReferenceInstances      -openReferenceInstances
     -OpenReferenceInstancePaths      -openReferenceInstancePaths
     -OpenAssociatiorInstances      -openAssociatiorInstances
     -OpenAssociatorInstancePaths      -openAssociatorInstancePaths
     -OpenQueryInstances      -openQueryInstances
     -PullInstancesWithPath      -pullInstancesWithPath
     -PullInstancePaths      -pullInstancePaths
     -PullInstances      -pullInstances
     -CloseEnumeration      -closeEnumeration
     -EnumerationCount (deprecated by DMTF and incomplete)      -enumerationCount (deprecated by DMTF and incomplete)
  
 Since the concept of sequences of operations linked together (open, pull, close) Since the concept of sequences of operations linked together (open, pull, close)
 is a major extension to the original CIM/XML operation concept of completely is a major extension to the original CIM/XML operation concept of completely
Line 52 
Line 56 
 The new operations follow the same pattern as the APIs for existing operations The new operations follow the same pattern as the APIs for existing operations
 in that: in that:
  
 1. All errors are handled as CIMException and Exception  1. All errors are handled as CIMException and Exception the same as the
      original client operations.  Note, however, that there are additional
      CIMStatusCodes for the new operations.
  
 2. The means of inputting parameters are the same except that there are 2. The means of inputting parameters are the same except that there are
    significantly more input parameters with the open operations and for the    significantly more input parameters with the open operations and for the
    first time operations return parameters as well as objects in the    first time operations return parameters as well as objects in the
    response.  Specifically the open and pull operations return values for    response.  Specifically the open and pull operations return values for
    enumerationContext which is the identity for a pull sequence and     the enumerationContext argument which is the identity for a pull sequence and
    endOfSequence which is the marker the server sends in open and pull     the endOfSequence argument which is the marker the server sends in open and
    responses when it has no more objects to send.     pull responses when it has no more objects to send.
  
 The significant differences between the open... and original enumerate, The significant differences between the open... and original enumerate,
 associator, and reference operations includes: associator, and reference operations includes:
  
 1. The new pull client operations typically require multiple client operations 1. The new pull client operations typically require multiple client operations
    to retrieve a complete set of data (ex. OpenEnumerateInstances and     to retrieve a complete set of data (ex. openEnumerateInstances and
    PullInstancesWithPath) are equivalent to the old EnumerateInstances     pullInstancesWithPath) are equivalent to the old enumerateInstances
    client request.     client request.  While the whole collection of responses might be returned
      on the open if the maxObjectCount argument is set larger than the the number
      of objects in the total response, depending on the speed of delivery of
      objects from providers, the response might still not deliver everything
      in the initial response.  The client code writer should always assume that
      multiple requests will be required.
  
 2. Processing of parameters on responses (i.e. the endOfSequence and 2. Processing of parameters on responses (i.e. the endOfSequence and
    enumerationContext parameters are returned for open and pull operations)     enumerationContext arguments are returned for open and pull operations)
    These return arguments are used to control the loop retrieving data    These return arguments are used to control the loop retrieving data
    for an enumeration sequence (ex. the sequence of OpenEnumerateInstances    for an enumeration sequence (ex. the sequence of OpenEnumerateInstances
    and PullInstancesWithPath that represents a complete enumeration    and PullInstancesWithPath that represents a complete enumeration
Line 89 
Line 100 
    rather than CIMObject.    rather than CIMObject.
  
 5. Paths are returned for the instance operations as part of the returned 5. Paths are returned for the instance operations as part of the returned
    instances (ex. OpenEnumerateInstances and PullInstancesWithPath) where     instances (ex. openEnumerateInstances and pullInstancesWithPath) where
    they were not with EnumerateInstances.    they were not with EnumerateInstances.
  
 6. The client must maintain state between operations in an enumeration 6. The client must maintain state between operations in an enumeration
Line 105 
Line 116 
  
 OPENPEGASUS SERVER OPENPEGASUS SERVER
  
 The Pegasus server attempts to always deliver at least some objects  The OpenPegasus server attempts to always deliver at least some objects
 in a response.  It does not wait to deliver the exact number requested but in a response.  It does not wait to deliver the exact number requested but
 waits to deliver at least some. The sever will wait about 15 seconds to waits to deliver at least some. The sever will wait about 15 seconds to
 deliver and if there is nothing delivered from the providers it will then deliver and if there is nothing delivered from the providers it will then
Line 113 
Line 124 
 timeout.  This would only occur if the providers are extremely slow (i.e. timeout.  This would only occur if the providers are extremely slow (i.e.
 greater than 15 seconds) in preparing response objects to be delivered. greater than 15 seconds) in preparing response objects to be delivered.
  
 The Pegasus server always closes an enumeration sequence upon receipt of any  The OpenPegasus server always closes an enumeration sequence upon receipt of any
 error from the providers, repository, etc. Therefore the server will reject error from the providers, repository, etc. Therefore the server will reject
 any request that has continueOnError = true;  any request that has the continueOnError argument = true;
  
 Expansion to allow the continue on error may be added in a future version. Expansion to allow the continue on error may be added in a future version.
 In any case, the whole purpose of the continue on error is really to allow In any case, the whole purpose of the continue on error is really to allow
Line 161 
Line 172 
 In other words, the time to process large sets of responses from the provider In other words, the time to process large sets of responses from the provider
 now depends on the speed of handling the client. now depends on the speed of handling the client.
  
 It is important to remember in developing providers that the Pegasus server  It is important to remember in developing providers that the OpenPegasus server
 can most efficiently process responses if they are passed from the provider can most efficiently process responses if they are passed from the provider
 to the server individually or in small arrays of objects rather than the to the server individually or in small arrays of objects rather than the
 provider gathering very large arrays of objects and sending them to the provider gathering very large arrays of objects and sending them to the
Line 175 
Line 186 
 1. The regex for the LIKE operation is the same as CQL basic. It provides 1. The regex for the LIKE operation is the same as CQL basic. It provides
    only the following special characters   "." and  "*".    only the following special characters   "." and  "*".
 2. The implementation does not include the comparison of 2. The implementation does not include the comparison of
    embeddedInstances     embeddedInstances functionality.
 3. The implementation does not include the handling of Uint8[] as 3. The implementation does not include the handling of Uint8[] as
    strings.    strings.
   4. Since the cimserver provides the filtering, it can only filter properties
      that are returned from the providers.  Therefore all of the properties in
      the filter MUST BE included in any property list provided with the request.
  
 For more details on the FQL implementation see the readme.txt in the For more details on the FQL implementation see the readme.txt in the
     directory pegasus/src/Pegasus/FQL.     directory pegasus/src/Pegasus/FQL.
Line 194 
Line 208 
 ================================================================== ==================================================================
 LIMITATIONS IN OPENPEGASUS 2.14 LIMITATIONS IN OPENPEGASUS 2.14
  
 1. The openQueryInstances does not allow requesting the class on response.  1. The openQueryInstances does not allow requesting the class on response
      (i.e. the returnQueryResultClass argument must be false in this version).
      Since OpenPegasus is actively proposing that this argument be deprecated
      we will see what happens in future releases.
  
 2. The openEnumerateInstanceNames, openAssociatorNames, and openReferenceNames 2. The openEnumerateInstanceNames, openAssociatorNames, and openReferenceNames
 do not allow use of the query filter.  This is because     do not allow use of the query filter.  This is because:
    a. The intention is to deprecate these operations completely and remove    a. The intention is to deprecate these operations completely and remove
       them in a future version        them in a future versionof both the specificatons and OpenPegasus.
    b. They require that the server call the providers with the corresponding    b. They require that the server call the providers with the corresponding
       enumerate, associators, references to get the full instances to       enumerate, associators, references to get the full instances to
       filter        filter and then remap this to the corresponding Names operation.
         We propose that if the user wants just the paths, this can be achieved
         with the instances operation with the propertylist set empty which
         requests that the server return no properties.
  
 3. The filterQuery filtering is done by the server, not the providers in this 3. The filterQuery filtering is done by the server, not the providers in this
    version of OpenPegasus. This will be modified in a future version of    version of OpenPegasus. This will be modified in a future version of
    OpenPegasus when the provider API extensions for the pull operations    OpenPegasus when the provider API extensions for the pull operations
    have been resolved.  Version 2.1 of the CMPI specification will resolve    have been resolved.  Version 2.1 of the CMPI specification will resolve
    this issue.     this issue.  However, this has imposed another limitation as mentioned above,
      the properties that are part of the filter MUST BE included in any
      propertyList in the request.  OpenPegasus does not check to be sure that
      all properties in the filter are also in the request and would therefore
      try to filter the response on non-existent properties.
  
 4. The input parameter continueOnError is processed correctly by the client 4. The input parameter continueOnError is processed correctly by the client
    but the Pegasus server only provides code for 'false' value, since the server    but the Pegasus server only provides code for 'false' value, since the server
Line 241 
Line 265 
 or pull response and the receipt of the next pull or a close operation before or pull response and the receipt of the next pull or a close operation before
 the server may close the enumeration. the server may close the enumeration.
 The specification allows the server to set a maximum interoperation time and The specification allows the server to set a maximum interoperation time and
 refuse open requests that with requested operationTimeout greater than that time.  refuse open requests that with requested operationTimeout greater than that
   time.
  
 2. Maximum number of objects returned in a single open or pull operation 2. Maximum number of objects returned in a single open or pull operation
 (pullOperationsMaxObjectCount) - The server can set a maximum limit on the (pullOperationsMaxObjectCount) - The server can set a maximum limit on the
Line 255 
Line 280 
 the value defined by this runtime configuration variable.  The default the value defined by this runtime configuration variable.  The default
 is 30 seconds. is 30 seconds.
  
   STATISTICS
   
   The server does maintain some statistics on the pull operations and outputs
   these to the console when the server is shutdown.  In this version there
   is no way to output these statistics other than to the console and at
   shutdown.
   
 COMPILE TIME CONFIGURATION PARAMETERS COMPILE TIME CONFIGURATION PARAMETERS
  
 1. Whether the server allows 0 as an interoperation timeout value - The value 1. Whether the server allows 0 as an interoperation timeout value - The value
Line 310 
Line 342 
 runtime parameters in Constants.h runtime parameters in Constants.h
  
 =================================================================== ===================================================================
 TESTING  TESTING PULL OPERATIONS
  
 The pull operations are tested primarily with two client programs in the The pull operations are tested primarily with two client programs in the
 directory Pegasus/Client/tests directory Pegasus/Client/tests
Line 346 
Line 378 
    2. Minor TODOs, diagnostics, etc. still in the code. Reduced almost to    2. Minor TODOs, diagnostics, etc. still in the code. Reduced almost to
       none now.  We are leaving some in as PEGASUS_DEBUG       none now.  We are leaving some in as PEGASUS_DEBUG
    3. Extension to avoid double move of objects in CIMResponseData (one    3. Extension to avoid double move of objects in CIMResponseData (one
       into enumerationContext queue and second to new cimResponseData for        into enumerationContext queue and second to new CIMResponseData for
       response.  Want to avoid second move by extending Open/Pull response        response.  Want to avoid second move by extending open/pull response
       messages to include count and CIMResponse data to count objects out       messages to include count and CIMResponse data to count objects out
       of queue when converting (avoids the second move). This would mean       of queue when converting (avoids the second move). This would mean
       extending the output writers to allow the count field to be supplied       extending the output writers to allow the count field to be supplied
Line 403 
Line 435 
    12. Define a simpler iteration interface for the client so that    12. Define a simpler iteration interface for the client so that
        the client does not have to directly control the open, pull, etc.        the client does not have to directly control the open, pull, etc.
        operations.        operations.
      13. Map properties in the FQL Filter to properties in any property list
          provided.
      14. Output statistical information on a regular basis rather than just
          as server shutdown and to the log or somewhere else than just the
          console.
  

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