{{{ }}} = 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 === Expression Engine === {{{ public __gc class OSGeo::FDO::Utilities::ExpressionEngine::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); }; }}} === Copy Filter === {{{ /// \brief /// This helper class traverse the filter object and creates a deep copy. /// public __gc class OSGeo::FDO::Utilities::ExpressionEngine::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(); }; }}} === Function Collection === {{{ /// \brief /// The FunctionCollection class represents a collection of Expression Engine IFunction objects. /// [System::Reflection::DefaultMemberAttribute("RealTypeItem")] public __sealed __gc class OSGeo::FDO::Utilities::ExpressionEngine::FunctionCollection : public OSGeo::Runtime::Disposable, public System::Collections::IList { public: /// \brief /// Constructs a FunctionCollection object /// /// \param parent /// Input A Pointer to the parent schema object of the collection /// FunctionCollection(OSGeo::FDO::Schema::SchemaElement* parent); /// \brief /// Constructs a FunctionCollection object based on an unmanaged instance of the object /// /// \param unmanaged /// Input A Pointer to the unmanaged object. /// /// \param autoDelete /// Input Indicates if the constructed object should be automatically deleted /// once it no longer referenced. /// FunctionCollection(System::IntPtr unmanaged, System::Boolean autoDelete); /// \brief /// Gets the count of items in collection. /// /// \return /// Returns the number of items in the collection. /// __property System::Int32 get_Count(System::Void); /// \brief /// Gets an enumerator that can iterate through a collection. /// /// \return /// Returns an enumerator on the dictionary. /// __sealed System::Collections::IEnumerator* GetEnumerator(System::Void); /// \brief /// Removes the index-th IFunction from this collection. /// /// \param index /// Input index of the element to remove. /// System::Void RemoveAt(System::Int32 index); /// \brief /// Removes all elements from the collection. /// System::Void Clear(); /// \brief /// Adds a IFunction object into the collection. /// /// \param value /// Input the IFunction object to add. /// /// \return /// Returns the position into which the new element was inserted. /// System::Int32 Add(OSGeo::FDO::Utilities::ExpressionEngine::IFunction* value); /// \brief /// Determines the index of a specific IFunction object. /// /// \param value /// Input the IFunction object to locate in the collection. /// /// \return /// The index of value if found in the collection; otherwise, -1. /// System::Int32 IndexOf(OSGeo::FDO::Utilities::ExpressionEngine::IFunction* value); /// \brief /// Determines the index of a specific IFunction object. /// /// \param name /// Input the name of the object to locate in the collection. /// /// \return /// The index of value if found in the collection; otherwise, -1. /// System::Int32 IndexOf(String* name); /// \brief /// Inserts a IFunction object into the collection at the specified position. /// /// \param index /// Input the zero-based index at which value should be inserted. /// \param value /// Input the IFunction object to insert. /// System::Void Insert(System::Int32 index, OSGeo::FDO::Utilities::ExpressionEngine::IFunction* value); /// \brief /// Removes the first occurrence of a specific IFunction object. /// /// \param value /// Input the IFunction object to remove from the collection. /// System::Void Remove(OSGeo::FDO::Utilities::ExpressionEngine::IFunction* value); /// \brief /// Determines whether the collection contains a specific IFunction object. /// /// \param value /// Input The IFunction object to search in the collection. /// /// \return /// Returns true if the value is found in the collection; otherwise, false. /// System::Boolean Contains(OSGeo::FDO::Utilities::ExpressionEngine::IFunction* value); /// \brief /// Determines whether the collection contains a specific IFunction object. /// /// \param name /// Input The name of the IFunction object to search in the collection. /// /// \return /// Returns true if the value is found in the collection; otherwise, false. /// System::Boolean Contains(String* name); /// \brief /// Copies the elements of the collection to an array. /// /// \param array /// Output the one-dimensional Array that is the destination of the elements copied from this collection. /// /// \param startAt /// Input an integer that represents the index in array at which copying begins. /// System::Void CopyTo(OSGeo::FDO::Utilities::ExpressionEngine::IFunction* array[],System::Int32 startAt); /// \brief /// Gets the item in the collection at the specified index. /// /// \param index /// The index of the item in the collection. The index is 0 based. /// /// \return /// Returns an instance of a the collected item. /// Throws an instance of Exception if the index is out of range or an error occurs. /// __property OSGeo::FDO::Utilities::ExpressionEngine::IFunction* get_RealTypeItem(System::Int32 index); /// \brief /// Gets the item in the collection by name. /// /// \param index /// The name of the item in the collection. /// /// \return /// Returns an instance of a the collected item. /// __property OSGeo::FDO::Utilities::ExpressionEngine::IFunction* get_RealTypeItem(System::String* index); /// \brief /// Sets the value of the item at the specified index /// /// \param index /// Input index of the item to set. /// /// \param value /// Input the value of the item /// __property System::Void set_RealTypeItem(System::Int32 index, OSGeo::FDO::Utilities::ExpressionEngine::IFunction* value); /// \brief /// Gets an item in the collection. /// /// \param index /// Input index of the item to retrieve. /// /// \return /// Returns the item at the specified index /// __property OSGeo::FDO::Utilities::ExpressionEngine::IFunction* get_Item(System::Int32 index); /// \brief /// Sets the value of the item at the specified index /// /// \param index /// Input index of the item to set. /// /// \param value /// Input the value of the item /// __property System::Void set_Item(System::Int32 index, OSGeo::FDO::Utilities::ExpressionEngine::IFunction* value); }; }}} === IFunction Interface === {{{ /// \brief /// This class defines the base interface from which all Function classes derive. /// public __gc class OSGeo::FDO::Utilities::ExpressionEngine::IFunction : public OSGeo::Runtime::Disposable { public: /// \brief /// Returns the function definition for the function. /// The definition includes the list of supported signatures for the /// function. __property OSGeo::FDO::Connections::Capabilities::FunctionDefinition *get_FunctionDefinition (); }; }}} === IAggregateFunction Interface === {{{ /// \brief /// This class defines the base interface from which all Aggregate Function classes derive. /// public __gc class OSGeo::FDO::Utilities::ExpressionEngine::IAggregateFunction : public OSGeo::FDO::Utilities::ExpressionEngine::IFunction { public: /// \brief /// Executes the call of the function on an expression value. System::Void Process(OSGeo::FDO::Expression::LiteralValueCollection *literal_values); /// \brief // Returns the result of the function. __property OSGeo::FDO::Expression::LiteralValue *get_Result(); }; }}} === INonAggregateFunction Interface === {{{ /// \brief /// This class defines the base interface from which all Non-Aggregate Function classes derive. /// public __gc class OSGeo::FDO::Utilities::ExpressionEngine::INonAggregateFunction : public OSGeo::FDO::Utilities::ExpressionEngine::IFunction { public: /// \brief /// The function determines the function result and returns it back to /// the calling routine. __property OSGeo::FDO::Expression::LiteralValue * Evaluate(OSGeo::FDO::Expression::LiteralValueCollection *literalValues); }; }}}