FDO RFC 17 - Add a Managed API for the FDO Expression Engine

This page contains a request for comments document (RFC) for the FDO Open Source project. More FDO RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	March 20, 2008
Last Modified	Greg Boone Timestamp
Author	Greg Boone
RFC Status	Draft
Implementation Status	Under Consideration
Proposed Milestone	3.4.0.0
Assigned PSC guide(s)	Greg Boone
Voting History	TBD
+1
+0
-0
-1

Overview

The purpose of this RFC is to determine if there is a need to design and add a Managed API for the FDO Expression Engine.

Motivation

The Unmanaged FDO Expression Engine has a set of unmanaged interfaces but does not have a corresponding managed set of interfaces. The general rule has been that if an unmanaged component of the API is released in the SDK for external use, it should have a corresponding managed API as well.

Proposed Solution

The following shows the proposed additions for the Managed API

Namespace Additions

// Utilities
#define BEGIN_NAMESPACE_OSGEO_FDO_UTILITIES namespace OSGeo { namespace FDO { namespace Utilities {
#define BEGIN_NAMESPACE_OSGEO_FDO_UTILITIES }}}}

// Expression Engine
#define BEGIN_NAMESPACE_OSGEO_FDO_UTILITIES_EXPRESSIONENGINE namespace OSGeo { namespace FDO { namespace Utilities { namespace ExpressionEngine {
#define END_NAMESPACE_ASGEO_FDO_UTILITIES_EXPRESSIONENGINE }}}}}

// Utilities
#define NAMESPACE_OSGEO_FDO_UTILITIES OSGeo::FDO::Utilities
#define NAMESPACE_OSGEO_FDO_UTILITIES_EXPRESSIONENGINE OSGeo::FDO::Utilities::ExpressionEngine

Expression Engine

public __gc class ExpressionEngine : public NAMESPACE_OSGEO_RUNTIME::Disposable
{
public:
    /// \brief
    /// Constructs an instance of an ExpressionEngine
    /// 
    /// \param reader 
    /// Input FDO feature reader
    /// 
    /// \param classDef
    /// Input FDO class definition
    ///
    /// \param userDefinedFunctions
    /// Input User defined functions
    ///
    ExpressionEngine(OSGEO_FDO_COMMANDS_FEATURE::IReader* reader, 
                     OSGEO_FDO_SCHEMA::ClassDefinition* classDef, 
                     OSGEO_FDO_UTILITIES_EXPRESSIONENGINE::FunctionCollection *userDefinedFunctions);

    /// \brief
    /// Constructs an instance of an ExpressionException.
    /// 
    /// \param reader 
    /// Input reader
    /// 
    /// \param classDef
    /// Input class definition
    ///
    /// \param classDef
    /// Input identifiers
    ///
    /// \param userDefinedFunctions
    /// Input user defined functions
    ///
    /// \return
    /// Returns ExpressionEngine
    /// 
    ExpressionEngine(OSGEO_FDO_COMMANDS_FEATURE::IReader* reader, 
                     OSGEO_FDO_SCHEMA::ClassDefinition* classDef, 
                     OSGEO_FDO_COMMANDS::IdentifierCollection* identifiers, 
                     OSGEO_FDO_UTILITIES_EXPRESSIONENGINE::FunctionCollection *userDefinedFunctions);

    /// \brief
    /// Evaluates an expression
    /// 
    /// \param expression 
    /// Input expression
    /// 
    /// \return
    /// Returns a literal value. This value is valid until the next Evaluate call
    /// 
    FdoLiteralValue* Evaluate(OSGEO_FDO_EXPRESSION::Expression *expression);

    /// \brief
    /// Evaluates a name
    /// 
    /// \param name 
    /// Input identifier
    /// 
    /// \return
    /// Returns a literal value. This value is valid until the next Evaluate call
    /// 
    FdoLiteralValue* Evaluate(System::String* name);

    /// \brief
    /// Evaluates an identifier
    /// 
    /// \param identifier
    /// Input identifier
    /// 
    /// \return
    /// Returns a literal value. This value is valid until the next Evaluate call
    /// 
    FdoLiteralValue* Evaluate(OSGEO_FDO_EXPRESSION::Identifier* expr);


    /// \brief
    /// Evaluates an aggregate functions
    /// 
    /// \return
    /// Returns the aggragate results
    /// 
    FdoPropertyValueCollection* RunQuery();

    /// \brief
    /// Checks if passes the filter
    /// 
    /// \param filter
    /// Input filter
    /// 
    /// \return
    /// Returns true id passes the filter, otherwise false
    /// 
    bool ProcessFilter(OSGEO_FDO_FILTER::Filter *filter);

    /// \brief
    /// Returns the default functions plus the user defined functions
    /// 
    /// \return
    /// Returns the functions
    /// 
    OSGEO_FDO_CONNECTIONS_CAPABILITIES::FunctionDefinitionCollection *GetAllFunctions();

    /// \brief
    /// Returns the default functions the expression engine supports
    /// 
    /// \return
    /// Returns the functions
    /// 
    static OSGEO_FDO_CONNECTIONS_CAPABILITIES::FunctionDefinitionCollection *GetStandardFunctions();

    /// \brief
    /// Checks if the filter is valid
    /// 
    /// \param cls
    /// Input class definition
    /// 
    /// \param filter
    /// Input filter
    /// 
    /// \param selIds
    /// Input identifier collection
    /// 
    /// \param filterCapabilities
    /// Input filter capabilities
    /// 
    /// \return
    /// Throws an exception is filter is not valid
    /// 
    static System::Void ValidateFilter(OSGEO_FDO_SCHEMA::ClassDefinition *cls, 
                                       OSGEO_FDO_FILTER::Filter *filter, 
                                       OSGEO_FDO_COMMANDS::IdentifierCollection *selIds = NULL, 
                                       OSGEO_FDO_CONNECTIONS_CAPABILITIES::IFilterCapabilities *filterCapabilities = NULL);

    /// \brief
    /// Optimizes the filter
    /// 
    /// \param filter
    /// Input the filter
    ///
    /// \return
    /// The optimized filter
    /// 
    static OSGEO_FDO_FILTER::Filter* OptimizeFilter( OSGEO_FDO_FILTER::Filter *filter );

    /// \brief
    /// Checks if the function name is a aggregate function
    /// 
    /// \param funcDefs
    /// Input the list of functions
    ///
    /// \param name
    /// Input the function name
    ///
    /// \return
    /// True if the function is an aggregate function otherwise false
    /// 
    static bool IsAggregateFunction(OSGEO_FDO_CONNECTIONS_CAPABILITIES::FunctionDefinitionCollection *funcDefs, 
                                    System::String *name);

    /// \brief
    /// Returns the type of expression
    /// 
    /// \param functions
    /// Input the list of functions
    ///
    /// \param originalClassDef
    /// Input the class definition
    ///
    /// \param propType
    /// Output the property type
    ///
    /// \param dataType
    /// Output the data type
    ///
    /// \return
    /// Returns nothing
    /// 
    static System::Void GetExpressionType(OSGEO_FDO_CONNECTIONS_CAPABILITIES::FunctionDefinitionCollection *functionDefinitions, 
                                          OSGEO_FDO_SCHEMA::ClassDefinition* originalClassDef, 
                                          OSGEO_FDO_EXPRESSION::Expression *expr, 
                                          OSGEO_FDO_SCHEMA::PropertyType &retPropType, 
                                          OSGEO_FDO_SCHEMA::DataType &retDataType);

    /// \brief
    /// Returns the type of expression
    ///
    /// \param originalClassDef
    /// Input the class definition
    ///
    /// \param propType
    /// Output the property type
    ///
    /// \param dataType
    /// Output the data type
    ///
    /// \return
    /// Returns nothing
    /// 
    static System::Void GetExpressionType(OSGEO_FDO_SCHEMA::ClassDefinition* originalClassDef, 
                                          OSGEO_FDO_EXPRESSION::Expression *expr, 
                                          OSGEO_FDO_SCHEMA::PropertyType &retPropType, 
                                          OSGEO_FDO_SCHEMA::DataType &retDataType);

    /// \brief
    /// Registers the user-defined functions
    ///
    /// \param userDefinedFunctions
    /// Input the user-defined functions
    ///
    /// \return
    /// Returns nothing
    /// 
    static System::Void RegisterFunctions(OSGEO_FDO_UTILITIES_EXPRESSIONENGINE::FunctionCollection *userDefinedFunctions);

};

Expression Engine Copy Filter

//
// This helper class traverse the filter object and creates a deep copy.
public __gc class CopyFilter : 
    public virtual OSGEO_FDO_EXPRESSION::IExpressionProcessor, 
    public virtual OSGEO_FDO_FILTER::IFilterProcessor
{
public: 
    /// \brief
    /// Constructs a new instance of ExpressionEngineCopyFilter
    /// 
    CopyFilter();

    /// \brief
    /// Constructs an instance of an ExpressionEngine
    /// 
    static OSGEO_FDO_FILTER::Filter* Copy( OSGEO_FDO_FILTER::Filter *filter );
    static OSGEO_FDO_EXPRESSION::Expression* Copy( OSGEO_FDO_EXPRESSION::Expression *expression );
    static OSGEO_FDO_FILTER::Filter* Copy( OSGEO_FDO_FILTER::Filter *filter, OSGEO_FDO_COMMANDS::IdentifierCollection* idList  );
    static OSGEO_FDO_EXPRESSION::Expression* Copy( OSGEO_FDO_EXPRESSION::Expression *expression, OSGEO_FDO_COMMANDS::IdentifierCollection* idList  );
	
    /// \brief
    /// Gets the FDO Expression associated to the CopyFilter
    /// 
    OSGEO_FDO_EXPRESSION::Expression* GetExpression();

    /// \brief
    /// Gets the FDO Filter associated to the CopyFilter
    /// 
    OSGEO_FDO_FILTER::Filter* GetFilter();
};

Util Feature Reader

/// \brief
/// A generic feature reader. The underlying feature reader and the ExpressionEngine
/// are used to get the value of a property, computed identifiers and expressions
///
public __gc class UtilFeatureReader : public OSGEO_FDO_COMMANDS::FEATURE::IFeatureReader
{
public:

    /// \brief
    /// Constructs an instance of a UtilFeatureReader
    /// 
    UtilFeatureReader (OSGEO_FDO_SCHEMA::ClassDefinition* classDef, 
                       OSGEO_FDO_COMMANDS::FEATURE::IFeatureReader* reader, 
                       OSGEO_FDO_FILTER::Filter *filter, 
                       OSGEO_FDO_COMMANDS::IdentifierCollection* selectedIds, 
                       OSGEO_FDO_UTILITIES_EXPRESSIONENGINE::FunctionCollection *userDefinedFunctions);

public:
    /// \brief
    /// Gets the Boolean value of the specified property. No conversion is
    /// performed, thus the property must be Boolean or an
    /// exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the Boolean value
    /// 
    System::Boolean GetBoolean(System::String* propertyName);

    /// \brief
    /// Gets the byte value of the specified property. No conversion is
    /// performed, thus the property must be Byte or an
    /// exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the byte value.
    /// 
    System::Byte GetByte(System::String* propertyName);

    /// \brief
    /// Gets the date time value of the specified property. No conversion
    /// is performed, thus the property must be DateTime or
    /// an exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the date and time value.
    /// 
    OSGEO_FDO_SCHEMA::DateTime GetDateTime(System::String* propertyName);

    /// \brief
    /// Gets the double-precision floating point value of the specified property.
    /// No conversion is performed, thus the property must be of type
    /// Double or an exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the double value.
    /// 
    System::Double GetDouble(System::String* propertyName);

    /// \brief
    /// Gets the signed 16-bit integer value of the specified property. No conversion is
    /// performed, thus the property must be Int16 or an
    /// exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the FdoInt16 value.
    /// 
    System::Int16 GetInt16(System::String* propertyName);

    /// \brief
    /// Gets the signed 32-bit integer value of the specified property. No conversion is
    /// performed, thus the property must be Int32 or an
    /// exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the System::Int32 value.
    /// 
    System::Int32 GetInt32(System::String* propertyName);

    /// \brief
    /// Gets the signed 64-bit integer value of the specified property. No conversion
    /// is performed, thus the property must be Int64 or an
    /// exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the FdoInt64 value.
    /// 
    System::Int64 GetInt64(System::String* propertyName);

    /// \brief
    /// Gets the single-precision floating point value of the specified property.
    /// No conversion is performed, thus the property must be Double
    /// or an exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the single value
    /// 
    System::Double GetSingle(System::String* propertyName);

    /// \brief
    /// Gets the string value of the specified property. No conversion is
    /// performed, thus the property must be String or an
    /// exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the string value.
    /// 
    System::String* GetString(System::String* propertyName);

    /// \brief
    /// Gets a LOBValue reference. The LOB is fully read in and data available.
    /// Because no conversion is performed, the property must be BLOB or
    /// CLOB etc. (a LOB type)
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the reference to LOBValue
    /// 
    OSGEO_FDO_EXPRESSION::LOBValue* GetLOB(System::String* propertyName);

    /// \brief
    /// Gets a reference of the specified LOB property as a BLOBStreamReader or
    /// CLOBStreamReader etc. to allow reading in blocks of data.
    /// Because no conversion is performed, the property must be BLOB 
    /// or CLOB etc. (a LOB type)
    /// Cast the IStreamReader to the appropiate LOB Stream Reader.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns a reference to a LOB stream reader
    /// 
    OSGEO_FDO_COMMON::IStreamReader* GetLOBStreamReader(System::String* propertyName );

    /// \brief
    /// Returns true if the value of the specified property is null.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns true if the value is null.
    /// 
    System::Boolean IsNull(System::String* propertyName);

    /// \brief
    /// Gets the geometry value of the specified property as a byte array
    /// in FGF format. No conversion is performed, thus the property
    /// must be of Geometric type or an exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the FGF byte array value.
    /// 
    System::ByteArray* GetGeometry(System::String* propertyName);

    /// \brief
    /// Gets the raster object of the specified property.
    /// Because no conversion is performed, the property must be
    /// of Raster type; otherwise, an exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the raster object.
    /// 
    OSGEO_FDO_RASTER::IRaster* GetRaster(System::String* propertyName);

    /// \brief
    /// Advances the reader to the next item. The default position of the
    /// reader is prior to the first item. Thus, you must call ReadNext
    /// to begin accessing any data.
    /// 
    /// \return
    /// Returns true if there is a next item.
    /// 
    System::Boolean ReadNext();

    /// \brief
    /// Closes the IDataReader object, freeing any resources it may be holding.
    /// 
    /// \return
    /// Returns nothing
    /// 
    System::Void Close();

    /// \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.
    /// 
    OSGEO_FDO_SCHEMA::ClassDefinition* GetClassDefinition();

    /// \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
    /// 
    System::Int32 GetDepth();

    /// \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.
    /// 
    const System::Byte * GetGeometry(System::String* propertyName, System::Int32 * count);


    /// \brief
    /// Gets a reference to an IFeatureReader 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
    /// 
    OSGEO_FDO_COMMANDS_FEATURE::IFeatureReader* GetFeatureObject(System::String* propertyName);
};