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