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 }}}}}

// Namespaces
#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

/// \brief
/// 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
    /// Static methods needed for copy/constructing filter and expression objects 
    /// 
    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();
};