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

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.