= 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 }}}}} // 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(); 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 ); OSGEO_FDO_EXPRESSION::Expression* GetExpression(); OSGEO_FDO_FILTER::Filter* GetFilter(); }; }}}