= !MapGuide RFC 82 - Extend Reader 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||Adopted||
||Implementation Status||Implemented||
||Proposed Milestone||(2.2)||
||Assigned PSC guide(s)||(Tom Fukushima)||
||'''Voting History'''||(vote date)||
||+1||Tom, Bruce, Trevor, Harris, Andy, Jason, Kenneth||
||+0||||
||-0||||
||-1||||
||no vote||Bob, Paul||

== 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 reader interfaces 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
    /// Gets the index of the property with the specified property name.
    ///
    /// <!-- Syntax in .Net, Java, and PHP -->
    /// \htmlinclude DotNetSyntaxTop.html
    /// virtual int GetPropertyIndex(string name);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual GetPropertyIndex(string name);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual GetPropertyIndex(string name);
    /// \htmlinclude SyntaxBottom.html
    ///
    /// \param name(string)
    /// The name of the property in the list of
    /// properties belonging to the feature currently
    /// being read.
    ///
    /// \return
    /// Returns the property index.
    ///
    virtual INT32 GetPropertyIndex(STRING name) = 0;

    /////////////////////////////////////////////////////////////////////
    /// \brief
    /// Gets the type of the property at the specified index. See
    /// MgPropertyType for the list of possible values.
    ///
    /// <!-- Syntax in .Net, Java, and PHP -->
    /// \htmlinclude DotNetSyntaxTop.html
    /// virtual int GetPropertyType(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual int GetPropertyType(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual int GetPropertyType(int index);
    /// \htmlinclude SyntaxBottom.html
    ///
    /// \param index (int)
    /// The property index.
    ///
    /// \return
    /// Returns an MgPropertyType value.
    ///
    virtual INT32 GetPropertyType(INT32 index) = 0;

    /////////////////////////////////////////////////////////////////////
    /// \brief
    /// Determines whether the value of the specified property is
    /// null.
    ///
    /// <!-- Syntax in .Net, Java, and PHP -->
    /// \htmlinclude DotNetSyntaxTop.html
    /// virtual bool IsNull(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual boolean IsNull(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual bool IsNull(int index);
    /// \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(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual boolean GetBoolean(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual bool GetBoolean(int index);
    /// \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(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual signed char GetByte(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual int GetByte(int index);
    /// \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(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual MgDateTime GetDateTime(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual MgDateTime GetDateTime(int index);
    /// \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(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual float GetSingle(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual float GetSingle(int index);
    /// \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(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual double GetDouble(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual double GetDouble(int index);
    /// \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(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual short GetInt16(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual int GetInt16(int index);
    /// \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(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual int GetInt32(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual int GetInt32(int index);
    /// \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(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    ///  virtual long GetInt64(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    ///  virtual string GetInt64(int index);
    /// \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(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual String GetString(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual string GetString(int index);
    /// \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(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual MgByteReader GetBLOB(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual MgByteReader GetBLOB(int index);
    /// \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(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual MgByteReader GetCLOB(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual MgByteReader GetCLOB(int index);
    /// \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(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual MgByteReader GetGeometry(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual MgByteReader GetGeometry(int index);
    /// \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(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual MgRaster GetRaster(int index);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual MgRaster GetRaster(int index);
    /// \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 index of the property with the specified property name.
    ///
    /// \param name(string)
    /// The name of the property in the list of
    /// properties belonging to the feature currently
    /// being read.
    ///
    /// \return
    /// Returns the property index.
    ///
    virtual INT32 GetPropertyIndex(STRING name);

    //////////////////////////////////////////////////////////////////
    /// \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;
...
...
...
}}}

The following existing classes in MapGuide will be updated accordingly:

MgProxyFeatureReader, MgProxyDataReader, 
MgServerDataReader, MgServerFeatureReader, 
MgProxySqlDataReader, MgServerSqlDataReader,
MgProxyGwsFeatureReader, MgServerGwsFeatureReader

== 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.

== Addendum, Sept. 15, 2009 ==

A new function of {{{FdoInt32 GetPropertyIndex(FdoString* propertyName);}}} has been added with FDO RFC 34 in order to use access by index on FdoIFeatureReader and FdoIDataReader conveniently and correctly. So that function needs also to be exposed in MapGuide API too that a new method is exposed in MgReader:
{{{
virtual INT32 GetPropertyIndex(STRING name) = 0;
}}}

This method is missing from MgReader while it's added in there with FDO RFC 34. So it needs to be added to MgReader for consistency with FDO. 
{{{
virtual INT32 GetPropertyType(INT32 index)  = 0;
}}}