= 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::OSGeo::FDO::Utilities namespace OSGeo { namespace FDO { namespace Utilities {
#define BEGIN::OSGeo::FDO::Utilities }}}}

// Expression Engine
#define BEGIN::OSGeo::FDO::Utilities::ExpressionEngine namespace OSGeo { namespace FDO { namespace Utilities { namespace ExpressionEngine {
#define END::NAMESPACE::ASGEO::FDO::Utilities::ExpressionEngine }}}}}
}}}

=== Expression Engine ===

{{{

public __gc class ExpressionEngine : public 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, 
                                       OSGeo::FDO::Connections::Capabilities::IFilterCapabilities *filterCapabilities);

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