Changes between Version 32 and Version 33 of FDORfc34

Timestamp:

08/26/09 18:51:40 (4 years ago)

Author:

klain

Comment:

--

FDORfc34

@@ -64 +64 @@
 == Requirements ==
 
-The following FDO reader interfaces will be updated to allow for indexed access. Providers will be required to implement these method. 
+The following FDO reader interfaces will be updated to allow for indexed access. Providers will be required to implement these methods.
 
 === Interface IReader ===
@@ -281 +281 @@
 {
 public:
-    /// \brief
-    /// Gets the number of properties in the result set.
-    /// 
-    /// \return
-    /// Returns the number of columns.
-    /// 
-    FDO_API virtual FdoInt32 GetPropertyCount() = 0;
-
+...
+...
+...
     /// \brief
     /// Gets the name of the property at the given ordinal position.
@@ -299 +294 @@
     /// 
     FDO_API virtual FdoString* GetPropertyName(FdoInt32 index) = 0;
-
-    /// \brief
-    /// Gets the index of the property with the given name.
-    /// 
-    /// \param index 
-    /// Input the name of the property.
-    /// 
-    /// \return
-    /// Returns the property index
-    /// 
-    FDO_API virtual FdoInt32 GetPropertyIndex(FdoString* propertyName) = 0;
-
-    /// \brief
-    /// Gets the type of the property at the given ordinal position.
-    /// 
-    /// \param index 
-    /// Input the position of the property.
-    /// 
-    /// \return
-    /// Returns the type of the property.
-    /// 
-    FDO_API virtual FdoPropertyType GetPropertyType(FdoInt32 index) = 0;
-
-    /// \brief
-    /// Gets the type of the property with the given name.
-    /// 
-    /// \param index 
-    /// Input the name of the property.
-    /// 
-    /// \return
-    /// Returns the type of the property.
-    /// 
-    FDO_API virtual FdoPropertyType GetPropertyType(FdoString* propertyName) = 0;
-
-    /// \brief
-    /// Gets the data type of the property at the specified ordinal position.
-    /// 
-    /// \param index 
-    /// Input the index of the property.
-    /// 
-    /// \return
-    /// Returns the data type of the property.
-    /// 
-    FDO_API virtual FdoDataType GetDataType(FdoInt32 index) = 0;
-
-    /// \brief
-    /// Gets the data type of the property with the specified name.
-    /// 
-    /// \param index 
-    /// Input the name of the property.
-    /// 
-    /// \return
-    /// Returns the data type of the property.
-    /// 
-    FDO_API virtual FdoDataType GetDataType(FdoInt32 index) = 0;
-
-    /// \brief
-    /// Gets the definition of the object currently being read. If the user
-    /// has requested only a subset of the class properties, the class 
-    /// definition reflects what the user has asked, rather than the full class 
-    /// definition.
-    /// 
-    /// \return
-    /// Returns the class definition object.
-    /// 
-    FDO_API virtual FdoClassDefinition* GetClassDefinition() = 0;
-
-    /// \brief
-    /// Gets a value indicating the depth of nesting for the current reader.
-    /// The depth value increases each time GetFeatureObject is called and a new 
-    /// reader is returned. The outermost reader has a depth of 0.
-    /// 
-    /// \return
-    /// Returns the depth
-    /// 
-    FDO_API virtual FdoInt32 GetDepth() = 0;
-
-    /// \brief
-    /// Gets the geometry value of the specified property as a byte array in 
-    /// FGF format. Because no conversion is performed, the property must be
-    /// of Geometric type; otherwise, an exception is thrown. 
-    /// This method is a language-specific performance optimization that returns a
-    /// pointer to the array data, rather than to an object that encapsulates
-    /// the array.  The array's memory area is only guaranteed to be valid
-    /// until a call to ReadNext() or Close(), or the disposal of this reader
-    /// object.
-    /// 
-    /// \param propertyName 
-    /// Input the property name.
-    /// \param count 
-    /// Output the number of bytes in the array.
-    /// 
-    /// \return
-    /// Returns a pointer to the byte array in FGF format.
-    /// 
-    FDO_API virtual const FdoByte * GetGeometry(FdoString* propertyName, FdoInt32* count) = 0;
 
     /// \brief
@@ -415 +314 @@
     /// 
     FDO_API virtual const FdoByte * GetGeometry(FdoInt32 index, FdoInt32* count) = 0;
-
-    /// \brief
-    /// Gets a reference to an FdoIFeatureReader to read the data contained in
-    /// the object or object collection property. If the property is not an
-    /// object property, an exception is thrown.
-    /// 
-    /// \param propertyName 
-    /// Input the property name.
-    /// 
-    /// \return
-    /// Returns the nested feature reader
-    /// 
-    FDO_API virtual FdoIFeatureReader* GetFeatureObject(FdoString* propertyName) = 0;
+    
+         /// \brief
+    /// Gets the geometry value of the specified index as a byte array in 
+    /// FGF format. Because no conversion is performed, the property must be
+    /// of Geometric type; otherwise, an exception is thrown.
+    /// 
+    /// \param index 
+    /// Input the index of the property.
+    /// 
+    /// \return
+    /// Returns the byte array in FGF format.
+    /// 
+    FDO_API virtual FdoByteArray* GetGeometry(FdoInt32* index) = 0;
 
     /// \brief
@@ -484 +383 @@
     FDO_API virtual FdoPropertyType GetPropertyType(FdoInt32 index) = 0;
 };
+
 }}}
 
@@ -514 +414 @@
 
     /// \brief
-    /// Gets the index of the column with the given name.
-    /// 
-    /// \param index 
-    /// Input the name of the property.
-    /// 
-    /// \return
-    /// Returns the property index
-    /// 
-    FDO_API virtual FdoInt32 GetColumnIndex(FdoString* propertyName)
-
-    /// \brief
     /// Gets the data type of the column at the specified index.
     /// 
@@ -708 +597 @@
 }}}
 
+=== Default implementation ===
+
+A high level class diagram of existing reader related interfaces in FDO is as illustrated below. 
+ 
+Both 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:
+
+class FdoIDataReader: public FdoIReader
+{
+public:
+    virtual FdoInt32 GetInt32(FdoInt32 index);
+}
+
+An implementation file (IDataReader.cpp) needs to be added:
+
+FdoInt32 FdoIDataReader::GetInt32(FdoInt32 index)
+{
+    FdoStringP propName = GetPropertyName(index);
+    return GetInt32(propName);
+}
+
+Note 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. 
+
+In 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. 
+
 === Managed FDO API ===
 
@@ -714 +627 @@
 == Provider Implementation ==
 
-Providers will be required to implement the above functionality. 
-
-It is expected that resourcing will be supplied to modify all the existing FDO Open Source providers.
+Providers 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:
+
+{{{
+class FdoIFeatureReaderDefault: public FdoIFeatureReader
+{
+public:
+    FDO_API virtual FdoBoolean IsNull(FdoInt32 index);
+    FDO_API virtual FdoBoolean GetBoolean(FdoInt32 index);
+    FDO_API virtual FdoByte GetByte(FdoInt32 index);
+    FDO_API virtual FdoDateTime GetDateTime(FdoInt32 index);
+    FDO_API virtual FdoDouble GetDouble(FdoInt32 index);
+    FDO_API virtual FdoInt16 GetInt16(FdoInt32 index);
+    FDO_API virtual FdoInt32 GetInt32(FdoInt32 index);
+    FDO_API virtual FdoInt64 GetInt64(FdoInt32 index);
+    FDO_API virtual FdoFloat GetSingle(FdoInt32 index);
+    FDO_API virtual FdoString* GetString(FdoInt32 index); 
+    FDO_API virtual FdoLOBValue* GetLOB(FdoInt32 index);
+    FDO_API virtual FdoIStreamReader* GetLOBStreamReader(FdoInt32 index);
+    FDO_API virtual FdoByteArray* GetGeometry(FdoInt32 index);
+    FDO_API virtual FdoIRaster* GetRaster(FdoInt32 index); 
+    FDO_API virtual FdoString* GetPropertyName(FdoInt32 index);
+    FDO_API virtual const FdoByte * GetGeometry(FdoInt32 index, FdoInt32* count);
+    FDO_API virtual FdoByteArray* GetGeometry(FdoInt32* index);
+    FDO_API virtual FdoIFeatureReader* GetFeatureObject(FdoInt32 index);
+};
+}}}
+All pure virtual functions for access by index are overrided with the default implementation in a similar way. e.g. 
+{{{
+FdoBoolean FdoIFeatureReaderByIndex ::IsNull(FdoInt32 index)
+{
+    FdoStringP propName = GetPropertyName(index);
+    Return IsNull(propName);
+}
+
+}}}
+Changes to provider specific implementation:
+{{{
+Class XYZFeatureReader: public FdoIFeatureReaderDefault
+{
+    // no other changes 
+}
+}}}
+It 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. 
 
 == Test Plan ==