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

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

Expression Engine 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);
};

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

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


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


}}}
}}}