Changes between Version 32 and Version 33 of FDORfc34


Ignore:
Timestamp:
Aug 26, 2009, 6:51:40 PM (15 years ago)
Author:
klain
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • FDORfc34

    v32 v33  
    6464== Requirements ==
    6565
    66 The following FDO reader interfaces will be updated to allow for indexed access. Providers will be required to implement these method.
     66The following FDO reader interfaces will be updated to allow for indexed access. Providers will be required to implement these methods.
    6767
    6868=== Interface IReader ===
    … …  
    281281{
    282282public:
    283     /// \brief
    284     /// Gets the number of properties in the result set.
    285     ///
    286     /// \return
    287     /// Returns the number of columns.
    288     ///
    289     FDO_API virtual FdoInt32 GetPropertyCount() = 0;
    290 
     283...
     284...
     285...
    291286    /// \brief
    292287    /// Gets the name of the property at the given ordinal position.
    … …  
    299294    ///
    300295    FDO_API virtual FdoString* GetPropertyName(FdoInt32 index) = 0;
    301 
    302     /// \brief
    303     /// Gets the index of the property with the given name.
    304     ///
    305     /// \param index
    306     /// Input the name of the property.
    307     ///
    308     /// \return
    309     /// Returns the property index
    310     ///
    311     FDO_API virtual FdoInt32 GetPropertyIndex(FdoString* propertyName) = 0;
    312 
    313     /// \brief
    314     /// Gets the type of the property at the given ordinal position.
    315     ///
    316     /// \param index
    317     /// Input the position of the property.
    318     ///
    319     /// \return
    320     /// Returns the type of the property.
    321     ///
    322     FDO_API virtual FdoPropertyType GetPropertyType(FdoInt32 index) = 0;
    323 
    324     /// \brief
    325     /// Gets the type of the property with the given name.
    326     ///
    327     /// \param index
    328     /// Input the name of the property.
    329     ///
    330     /// \return
    331     /// Returns the type of the property.
    332     ///
    333     FDO_API virtual FdoPropertyType GetPropertyType(FdoString* propertyName) = 0;
    334 
    335     /// \brief
    336     /// Gets the data type of the property at the specified ordinal position.
    337     ///
    338     /// \param index
    339     /// Input the index of the property.
    340     ///
    341     /// \return
    342     /// Returns the data type of the property.
    343     ///
    344     FDO_API virtual FdoDataType GetDataType(FdoInt32 index) = 0;
    345 
    346     /// \brief
    347     /// Gets the data type of the property with the specified name.
    348     ///
    349     /// \param index
    350     /// Input the name of the property.
    351     ///
    352     /// \return
    353     /// Returns the data type of the property.
    354     ///
    355     FDO_API virtual FdoDataType GetDataType(FdoInt32 index) = 0;
    356 
    357     /// \brief
    358     /// Gets the definition of the object currently being read. If the user
    359     /// has requested only a subset of the class properties, the class
    360     /// definition reflects what the user has asked, rather than the full class
    361     /// definition.
    362     ///
    363     /// \return
    364     /// Returns the class definition object.
    365     ///
    366     FDO_API virtual FdoClassDefinition* GetClassDefinition() = 0;
    367 
    368     /// \brief
    369     /// Gets a value indicating the depth of nesting for the current reader.
    370     /// The depth value increases each time GetFeatureObject is called and a new
    371     /// reader is returned. The outermost reader has a depth of 0.
    372     ///
    373     /// \return
    374     /// Returns the depth
    375     ///
    376     FDO_API virtual FdoInt32 GetDepth() = 0;
    377 
    378     /// \brief
    379     /// Gets the geometry value of the specified property as a byte array in
    380     /// FGF format. Because no conversion is performed, the property must be
    381     /// of Geometric type; otherwise, an exception is thrown.
    382     /// This method is a language-specific performance optimization that returns a
    383     /// pointer to the array data, rather than to an object that encapsulates
    384     /// the array.  The array's memory area is only guaranteed to be valid
    385     /// until a call to ReadNext() or Close(), or the disposal of this reader
    386     /// object.
    387     ///
    388     /// \param propertyName
    389     /// Input the property name.
    390     /// \param count
    391     /// Output the number of bytes in the array.
    392     ///
    393     /// \return
    394     /// Returns a pointer to the byte array in FGF format.
    395     ///
    396     FDO_API virtual const FdoByte * GetGeometry(FdoString* propertyName, FdoInt32* count) = 0;
    397296
    398297    /// \brief
    … …  
    415314    ///
    416315    FDO_API virtual const FdoByte * GetGeometry(FdoInt32 index, FdoInt32* count) = 0;
    417 
    418     /// \brief
    419     /// Gets a reference to an FdoIFeatureReader to read the data contained in
    420     /// the object or object collection property. If the property is not an
    421     /// object property, an exception is thrown.
    422     ///
    423     /// \param propertyName
    424     /// Input the property name.
    425     ///
    426     /// \return
    427     /// Returns the nested feature reader
    428     ///
    429     FDO_API virtual FdoIFeatureReader* GetFeatureObject(FdoString* propertyName) = 0;
     316   
     317        /// \brief
     318    /// Gets the geometry value of the specified index as a byte array in
     319    /// FGF format. Because no conversion is performed, the property must be
     320    /// of Geometric type; otherwise, an exception is thrown.
     321    ///
     322    /// \param index
     323    /// Input the index of the property.
     324    ///
     325    /// \return
     326    /// Returns the byte array in FGF format.
     327    ///
     328    FDO_API virtual FdoByteArray* GetGeometry(FdoInt32* index) = 0;
    430329
    431330    /// \brief
    … …  
    484383    FDO_API virtual FdoPropertyType GetPropertyType(FdoInt32 index) = 0;
    485384};
     385
    486386}}}
    487387
    … …  
    514414
    515415    /// \brief
    516     /// Gets the index of the column with the given name.
    517     ///
    518     /// \param index
    519     /// Input the name of the property.
    520     ///
    521     /// \return
    522     /// Returns the property index
    523     ///
    524     FDO_API virtual FdoInt32 GetColumnIndex(FdoString* propertyName)
    525 
    526     /// \brief
    527416    /// Gets the data type of the column at the specified index.
    528417    ///
    … …  
    708597}}}
    709598
     599=== Default implementation ===
     600
     601A high level class diagram of existing reader related interfaces in FDO is as illustrated below.
     602 
     603Both FdoISqlReader and FdoIDataReader have the function to get the column name or property name according to the index. With this capability, it should be pretty easy to provide default implementation for all indexed access functions. Take FdoIDataReader as an example:
     604
     605class FdoIDataReader: public FdoIReader
     606{
     607public:
     608    virtual FdoInt32 GetInt32(FdoInt32 index);
     609}
     610
     611An implementation file (IDataReader.cpp) needs to be added:
     612
     613FdoInt32 FdoIDataReader::GetInt32(FdoInt32 index)
     614{
     615    FdoStringP propName = GetPropertyName(index);
     616    return GetInt32(propName);
     617}
     618
     619Note here, FdoIDataReader is overriding the GetInt32(FdoInt32 index) derived from FdoIReader. So providers can inherit the default implementation automatically without changing any codes. It only needs a recompile. Off course, providers can choose to override the default implementation by theirs if they like.
     620
     621In order to make it work in all cases, FdoIFeatureReader also needs to expose a function of FdoString* GetPropertyName(FdoInt32 index) and each provider needs to override it. It has been illustrated in above updated FdoIFeatureReader interface. This work is avoidless that each provider has to know how to map between property name and index for the default implementation.
     622
    710623=== Managed FDO API ===
    711624
    … …  
    714627== Provider Implementation ==
    715628
    716 Providers will be required to implement the above functionality.
    717 
    718 It is expected that resourcing will be supplied to modify all the existing FDO Open Source providers.
     629Providers will be required to implement the above functionality. Instead of each provider to implement all of newly added pure virtual functions, three utility abstract classes are added to provide the default implementation as mentioned above under Fdo/Utilities/Common: FdoIFeatureReaderDefault, FdoIDataReaderDefault, FdoISqlReaderDefault. Then the provider specific implementation will simply derive from the new classes. That involves changing one line in header file for each provider (some providers may not link FdoCommon and need to add that dependancy). Take FdoIDataReaderDefault as an example:
     630
     631{{{
     632class FdoIFeatureReaderDefault: public FdoIFeatureReader
     633{
     634public:
     635    FDO_API virtual FdoBoolean IsNull(FdoInt32 index);
     636    FDO_API virtual FdoBoolean GetBoolean(FdoInt32 index);
     637    FDO_API virtual FdoByte GetByte(FdoInt32 index);
     638    FDO_API virtual FdoDateTime GetDateTime(FdoInt32 index);
     639    FDO_API virtual FdoDouble GetDouble(FdoInt32 index);
     640    FDO_API virtual FdoInt16 GetInt16(FdoInt32 index);
     641    FDO_API virtual FdoInt32 GetInt32(FdoInt32 index);
     642    FDO_API virtual FdoInt64 GetInt64(FdoInt32 index);
     643    FDO_API virtual FdoFloat GetSingle(FdoInt32 index);
     644    FDO_API virtual FdoString* GetString(FdoInt32 index);
     645    FDO_API virtual FdoLOBValue* GetLOB(FdoInt32 index);
     646    FDO_API virtual FdoIStreamReader* GetLOBStreamReader(FdoInt32 index);
     647    FDO_API virtual FdoByteArray* GetGeometry(FdoInt32 index);
     648    FDO_API virtual FdoIRaster* GetRaster(FdoInt32 index);
     649    FDO_API virtual FdoString* GetPropertyName(FdoInt32 index);
     650    FDO_API virtual const FdoByte * GetGeometry(FdoInt32 index, FdoInt32* count);
     651    FDO_API virtual FdoByteArray* GetGeometry(FdoInt32* index);
     652    FDO_API virtual FdoIFeatureReader* GetFeatureObject(FdoInt32 index);
     653};
     654}}}
     655All pure virtual functions for access by index are overrided with the default implementation in a similar way. e.g.
     656{{{
     657FdoBoolean FdoIFeatureReaderByIndex ::IsNull(FdoInt32 index)
     658{
     659    FdoStringP propName = GetPropertyName(index);
     660    Return IsNull(propName);
     661}
     662
     663}}}
     664Changes to provider specific implementation:
     665{{{
     666Class XYZFeatureReader: public FdoIFeatureReaderDefault
     667{
     668    // no other changes
     669}
     670}}}
     671It is expected that resourcing will be supplied to modify all the existing FDO Open Source providers. Unless there are noticeable performance complaints, all of the open source providers will use the default implementation for this release.
    719672
    720673== Test Plan ==