= 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 [wiki:FDORfcs 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
    /// 
    OSGEO_FDO_EXPRESSION::LiteralValue* 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
    /// 
    OSGEO_FDO_EXPRESSION::LiteralValue* 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
    /// 
    OSGEO_FDO_EXPRESSION::LiteralValue* Evaluate(OSGEO_FDO_EXPRESSION::Identifier* expr);


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

    /// \brief
    /// Checks if passes the filter
    /// 
    /// \param filter
    /// Input filter
    /// 
    /// \return
    /// Returns true id passes the filter, otherwise false
    /// 
    System::Boolean 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 System::Boolean 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();
};
}}}