Changes between Initial Version and Version 1 of MapGuideRfc82

Timestamp:

Aug 13, 2009, 9:23:15 PM (15 years ago)

Author:

klain

Comment:

--

MapGuideRfc82

@@ +1 @@
+= !MapGuide RFC 82 - Extend MgReader Access by Index =
+
+This page contains a change request (RFC) for the !MapGuide Open Source project.
+More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page.
+
+== Status ==
+
+||RFC Template Version||(1.0)||
+||Submission Date||August 14, 2009||
+||Last Modified||(Klain Qin) (Fri Aug 14 09:46:19 2009)||
+||Author||(Klain Qin)||
+||RFC Status||Draft||
+||Implementation Status||(pending)||
+||Proposed Milestone||(2.2)||
+||Assigned PSC guide(s)||(Tom Fukushima)||
+||'''Voting History'''||(vote date)||
+||+1||||
+||+0||||
+||-0||||
+||-1||||
+
+== Overview ==
+
+This proposal is a continuation of FDO RFC 34(http://trac.osgeo.org/fdo/wiki/FDORfc34). FDO RFC 34 has enhanced the capability of FdoIReader to support indexed access. This proposal is to enhance the MgReader in MapGuide Feature Service API to support indexed access too. 
+
+== Motivation ==
+
+To provide faster access to data returned from MapGuide Feature Service API. 
+To provide enhanced compatibility with ADO.Net Reader/Record Interfaces. 
+
+== Proposed Solution ==
+
+The following reader interfaces will be updated to allow for indexed access. 
+
+=== Interface MgReader ===
+{{{
+/////////////////////////////////////////////////////////////////
+/// \brief
+/// Provides a forward-only, read-only iterator for reading data.
+/// You must call ReadNext before you can access any data. This
+/// is a base class for MgDataReader, MgFeatureReader, and
+/// MgSqlDataReader.
+///
+
+class MG_PLATFORMBASE_API  MgReader : public MgSerializable
+{
+PUBLISHED_API:
+...
+...
+...
+    /////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Determines whether the value of the specified property is
+    /// null.
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual bool IsNull(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual boolean IsNull(String propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual bool IsNull(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param index (int)
+    /// The position of the property in the list of
+    /// properties belonging to the feature currently
+    /// being read.
+    ///
+    /// \return
+    /// Returns true if the value is null; otherwise returns false.
+    ///
+    virtual bool IsNull(INT32 index) = 0;
+
+    /////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Gets the Boolean value of the specified property.
+    ///
+    /// \remarks
+    /// No conversion is performed. Therefore, the property must be of
+    /// MgPropertyType::Boolean type or an
+    /// MgInvalidPropertyTypeException is thrown.
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual bool GetBoolean(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual boolean GetBoolean(String propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual bool GetBoolean(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param index (int)
+    /// The position of the property in the list of
+    /// properties belonging to the feature currently
+    /// being read.
+    ///
+    /// \return
+    /// Returns the Boolean value.
+    ///
+    /// \exception MgInvalidPropertyTypeException.
+    ///
+    ///
+    virtual bool GetBoolean(INT32 index) = 0;
+
+    /////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Gets the Byte value of the specified property.
+    ///
+    /// \remarks
+    /// No conversion is performed. Therefore, the property must be
+    /// of type MgPropertyType::Byte or an
+    /// MgInvalidPropertyTypeException is thrown.
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual unsigned char GetByte(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual signed char GetByte(String propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual int GetByte(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param index (int)
+    /// The position of the property in the list of
+    /// properties belonging to the feature currently
+    /// being read.
+    ///
+    /// \return
+    /// Returns the Byte value.
+    ///
+    /// \exception MgInvalidPropertyTypeException.
+    ///
+    ///
+    virtual BYTE GetByte(INT32 index) = 0;
+
+    /////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Gets the MgDateTime value of the specified property.
+    ///
+    /// \remarks
+    /// No conversion is performed. Therefore, the property must be
+    /// of type MgPropertyType::DateTime or an
+    /// MgInvalidPropertyTypeException is thrown.
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual MgDateTime GetDateTime(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual MgDateTime GetDateTime(String propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual MgDateTime GetDateTime(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param index (int)
+    /// The position of the property in the list of
+    /// properties belonging to the feature currently
+    /// being read.
+    ///
+    /// \return
+    /// Returns an MgDateTime object.
+    ///
+    /// \exception MgInvalidPropertyTypeException.
+    ///
+    ///
+    virtual MgDateTime* GetDateTime(INT32 index) = 0;
+
+    /////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Gets the Single value of the specified property.
+    ///
+    /// \remarks
+    /// No conversion is performed. Therefore, the property must be a
+    /// of type MgPropertyType::Single or an
+    /// MgInvalidPropertyTypeException is thrown.
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual float GetSingle(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual float GetSingle(String propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual float GetSingle(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param index (int)
+    /// The position of the property in the list of
+    /// properties belonging to the feature currently
+    /// being read.
+    ///
+    /// \return
+    /// Returns the single value.
+    ///
+    /// \exception MgInvalidPropertyTypeException.
+    ///
+    ///
+    virtual float GetSingle(INT32 index) = 0;
+
+    /////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Gets the Double value of the specified property.
+    ///
+    /// \remarks
+    /// No conversion is performed. Therefore, the property must be a
+    /// of type MgPropertyType::Double or an
+    /// MgInvalidPropertyTypeException is thrown.
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual double GetDouble(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual double GetDouble(String propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual double GetDouble(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param index (int)
+    /// The position of the property in the list of
+    /// properties belonging to the feature currently
+    /// being read.
+    ///
+    /// \return
+    /// Returns the double value.
+    ///
+    /// \exception MgInvalidPropertyTypeException.
+    ///
+    ///
+    virtual double GetDouble(INT32 index) = 0;
+
+    /////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Gets the 16 bit integer value of the specified property.
+    ///
+    /// \remarks
+    /// No conversion is performed. Therefore the property must be a
+    /// of type MgPropertyType::Int16 or an
+    /// MgInvalidPropertyTypeException is thrown.
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual short GetInt16(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual short GetInt16(String propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual int GetInt16(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param index (int)
+    /// The position of the property in the list of
+    /// properties belonging to the feature currently
+    /// being read.
+    ///
+    /// \return
+    /// Returns the 16 bit integer value.
+    ///
+    /// \exception MgInvalidPropertyTypeException
+    ///
+    ///
+    virtual INT16 GetInt16(INT32 index) = 0;
+
+    /////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Gets the 32 bit integer value of the specified property.
+    ///
+    /// \remarks
+    /// No conversion is performed. Therefore, the property must be a
+    /// of type MgPropertyType::Int32 or an
+    /// MgInvalidPropertyTypeException is thrown.
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual int GetInt32(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual int GetInt32(String propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual int GetInt32(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param index (int)
+    /// The position of the property in the list of
+    /// properties belonging to the feature currently
+    /// being read.
+    ///
+    /// \return
+    /// Returns the integer 32 bits value.
+    ///
+    /// \exception MgInvalidPropertyTypeException.
+    ///
+    ///
+    virtual INT32 GetInt32(INT32 index) = 0;
+
+    /////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Gets the 64 bit integer value of the specified property.
+    ///
+    /// \remarks
+    /// No conversion is performed. Therefore, the property must be a
+    /// of type MgPropertyType::Int64 or an
+    /// MgInvalidPropertyTypeException is thrown.
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    ///  virtual long GetInt64(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    ///  virtual long GetInt64(String propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    ///  virtual string GetInt64(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param index (int)
+    /// The position of the property in the list of
+    /// properties belonging to the feature currently
+    /// being read.
+    ///
+    /// \return
+    /// Returns the integer 64 bits value.
+    ///
+    /// \exception MgInvalidPropertyTypeException.
+    ///
+    /// \note
+    /// INT64 is actually a pointer to an Integer64 object
+    ///
+    virtual INT64 GetInt64(INT32 index) = 0;
+
+    /////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Gets the string value of the specified property.
+    ///
+    /// \remarks
+    /// No conversion is performed. Therefore, the property must be a
+    /// of type MgPropertyType::String or an
+    /// MgInvalidPropertyTypeException is thrown.
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual string GetString(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual String GetString(String propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual string GetString(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param index (int)
+    /// The position of the property in the list of
+    /// properties belonging to the feature currently
+    /// being read.
+    ///
+    /// \return
+    /// Returns the string value.
+    ///
+    /// \exception MgInvalidPropertyTypeException.
+    ///
+    ///
+    virtual STRING GetString(INT32 index) = 0;
+
+    /////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Gets the \link BLOB BLOB \endlink value of the specified property.
+    ///
+    /// \remarks
+    /// No conversion is performed. Therefore, the property must be
+    /// of type MgPropertyType::Blob or an
+    /// MgInvalidPropertyTypeException is thrown.
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual MgByteReader GetBLOB(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual MgByteReader GetBLOB(String propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual MgByteReader GetBLOB(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param index (int)
+    /// The position of the property in the list of
+    /// properties belonging to the feature currently
+    /// being read.
+    ///
+    /// \return
+    /// Returns the BLOB value in an MgByteReader object.
+    ///
+    /// \exception MgInvalidPropertyTypeException
+    ///
+    ///
+    virtual MgByteReader* GetBLOB(INT32 index) = 0;
+
+    /////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Gets the CLOB value of the specified property.
+    ///
+    /// \remarks
+    /// No conversion is performed. Therefore, the property must be a
+    /// of type MgPropertyType::Clob or an
+    /// MgInvalidPropertyTypeException is thrown.
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual MgByteReader GetCLOB(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual MgByteReader GetCLOB(String propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual MgByteReader GetCLOB(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param index (int)
+    /// The position of the property in the list of
+    /// properties belonging to the feature currently
+    /// being read.
+    ///
+    /// \return
+    /// Returns the CLOB value in an MgByteReader object.
+    ///
+    /// \exception MgInvalidPropertyTypeException.
+    ///
+    ///
+    virtual MgByteReader* GetCLOB(INT32 index) = 0;
+
+    /////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Gets the Geometry for the specified property.
+    ///
+    /// \remarks
+    /// No conversion is performed. Therefore, the property must be a
+    /// of type MgPropertyType::Geometry or an
+    /// MgInvalidPropertyTypeException is thrown.
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual MgByteReader GetGeometry(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual MgByteReader GetGeometry(String propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual MgByteReader GetGeometry(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param index (int)
+    /// The position of the property in the list of
+    /// properties belonging to the feature currently
+    /// being read.
+    ///
+    /// \return
+    /// Returns a geometry in AGF binary format in an MgByteReader
+    /// object.
+    ///
+    /// \exception MgInvalidPropertyTypeException
+    ///
+    ///
+    virtual MgByteReader* GetGeometry(INT32 index) = 0;
+
+    ///////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Gets the raster object of the specified property.
+    ///
+    /// \remarks
+    /// The property must be of type MgPropertyType::Raster, or an
+    /// MgInvalidPropertyTypeException is thrown.
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual MgRaster GetRaster(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual MgRaster GetRaster(String propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual MgRaster GetRaster(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param index (int)
+    /// The position of the property in the list of
+    /// properties belonging to the feature currently
+    /// being read.
+    ///
+    /// \return
+    /// Returns an MgRaster object.
+    ///
+    /// \exception MgConnectionNotOpenException MgNullPropertyValueException
+    /// \exception MgFdoException MgInvalidPropertyTypeException
+    /// \exception MgInvalidPropertyTypeException.
+    ///
+    ///
+    virtual MgRaster* GetRaster(INT32 index) = 0;
+};
+}}}
+
+=== Interface MgFeatureReader ===
+{{{
+class MG_PLATFORMBASE_API MgFeatureReader : public MgReader
+{
+    DECLARE_CLASSNAME(MgFeatureReader)
+
+PUBLISHED_API:
+...
+...
+...
+    ///////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Use this method to obtain the values of the properties
+    /// belonging to an object contained in the feature class
+    /// instance. Such an object is a property of the feature class
+    /// instance with a type of MgPropertyType::Feature.
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual MgFeatureReader GetFeatureObject(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual MgFeatureReader GetFeatureObject(String propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual MgFeatureReader GetFeatureObject(string propertyName);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param index (int)
+    /// The position of the property in the list of
+    /// properties belonging to the feature currently
+    /// being read.
+    ///
+    /// \return
+    /// Returns an MgFeatureReader object, which can be used to
+    /// access properties of an object contained in the feature
+    /// object.
+    ///
+    /// \exception MgInvalidArgumentException
+    ///  if the property type is not a
+    ///  feature.
+    /// \exception MgConnectionNotOpenException
+    /// \exception MgNullPropertyValueException
+    /// \exception MgFdoException
+    ///
+    virtual MgFeatureReader* GetFeatureObject(INT32 index) = 0;
+
+INTERNAL_API:
+
+    //////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Gets the Geometry for the specified property. No conversion is
+    /// performed, thus the property must be a of type Geometry or the result
+    /// is NULL
+    ///
+    /// \param index (int)
+    /// The position of the property in the list of
+    /// properties belonging to the feature currently
+    /// being read.
+    ///
+    /// \return
+    /// Returns a ByteReader object
+    ///
+    virtual BYTE_ARRAY_OUT GetGeometry(INT32 index, INT32& length) = 0;
+...
+...
+...
+}}}
+== Implications ==
+
+This RFC depends on FDO RFC 34 (http://trac.osgeo.org/fdo/wiki/FDORfc34). If FDORfc34 can't be approved, this RFC won't be approved either. 
+
+It adds new virtual functions to existing reader interfaces, so API documentation needs to be updated. However, there will be no impact on existing applications. 
+
+== Test Plan ==
+
+New unit tests will be added to test the indexed access.
+
+== Funding/Resources ==
+
+Supplied by Autodesk.