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

    /// \brief
    /// Constructs an instance of an ExpressionEngine
    /// 
    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();
};
}}}


=== Util Feature Reader ===

{{{
/// \brief
/// A generic feature reader. The underlying feature reader and the ExpressionEngine
/// are used to get the value of a property, computed identifiers and expressions
///
public __gc class UtilFeatureReader : public OSGEO_FDO_COMMANDS::FEATURE::IFeatureReader
{
public:

    /// \brief
    /// Constructs an instance of a UtilFeatureReader
    /// 
    UtilFeatureReader (OSGEO_FDO_SCHEMA::ClassDefinition* classDef, 
                       OSGEO_FDO_COMMANDS::FEATURE::IFeatureReader* reader, 
                       OSGEO_FDO_FILTER::Filter *filter, 
                       OSGEO_FDO_COMMANDS::IdentifierCollection* selectedIds, 
                       OSGEO_FDO_UTILITIES_EXPRESSIONENGINE::FunctionCollection *userDefinedFunctions);

public:
    /// \brief
    /// Gets the Boolean value of the specified property. No conversion is
    /// performed, thus the property must be Boolean or an
    /// exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the Boolean value
    /// 
    System::Boolean GetBoolean(System::String* propertyName);

    /// \brief
    /// Gets the byte value of the specified property. No conversion is
    /// performed, thus the property must be Byte or an
    /// exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the byte value.
    /// 
    System::Byte GetByte(System::String* propertyName);

    /// \brief
    /// Gets the date time value of the specified property. No conversion
    /// is performed, thus the property must be DateTime or
    /// an exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the date and time value.
    /// 
    OSGEO_FDO_SCHEMA::DateTime GetDateTime(System::String* propertyName);

    /// \brief
    /// Gets the double-precision floating point value of the specified property.
    /// No conversion is performed, thus the property must be of type
    /// Double or an exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the double value.
    /// 
    System::Double GetDouble(System::String* propertyName);

    /// \brief
    /// Gets the signed 16-bit integer value of the specified property. No conversion is
    /// performed, thus the property must be Int16 or an
    /// exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the FdoInt16 value.
    /// 
    System::Int16 GetInt16(System::String* propertyName);

    /// \brief
    /// Gets the signed 32-bit integer value of the specified property. No conversion is
    /// performed, thus the property must be Int32 or an
    /// exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the System::Int32 value.
    /// 
    System::Int32 GetInt32(System::String* propertyName);

    /// \brief
    /// Gets the signed 64-bit integer value of the specified property. No conversion
    /// is performed, thus the property must be Int64 or an
    /// exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the FdoInt64 value.
    /// 
    System::Int64 GetInt64(System::String* propertyName);

    /// \brief
    /// Gets the single-precision floating point value of the specified property.
    /// No conversion is performed, thus the property must be Double
    /// or an exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the single value
    /// 
    System::Double GetSingle(System::String* propertyName);

    /// \brief
    /// Gets the string value of the specified property. No conversion is
    /// performed, thus the property must be String or an
    /// exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the string value.
    /// 
    System::String* GetString(System::String* propertyName);

    /// \brief
    /// Gets a LOBValue reference. The LOB is fully read in and data available.
    /// Because no conversion is performed, the property must be BLOB or
    /// CLOB etc. (a LOB type)
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the reference to LOBValue
    /// 
    OSGEO_FDO_EXPRESSION::LOBValue* GetLOB(System::String* propertyName);

    /// \brief
    /// Gets a reference of the specified LOB property as a BLOBStreamReader or
    /// CLOBStreamReader etc. to allow reading in blocks of data.
    /// Because no conversion is performed, the property must be BLOB 
    /// or CLOB etc. (a LOB type)
    /// Cast the IStreamReader to the appropiate LOB Stream Reader.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns a reference to a LOB stream reader
    /// 
    OSGEO_FDO_COMMON::IStreamReader* GetLOBStreamReader(System::String* propertyName );

    /// \brief
    /// Returns true if the value of the specified property is null.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns true if the value is null.
    /// 
    System::Boolean IsNull(System::String* propertyName);

    /// \brief
    /// Gets the geometry value of the specified property as a byte array
    /// in FGF format. No conversion is performed, thus the property
    /// must be of Geometric type or an exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the FGF byte array value.
    /// 
    System::ByteArray* GetGeometry(System::String* propertyName);

    /// \brief
    /// Gets the raster object of the specified property.
    /// Because no conversion is performed, the property must be
    /// of Raster type; otherwise, an exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the raster object.
    /// 
    OSGEO_FDO_RASTER::IRaster* GetRaster(System::String* propertyName);

    /// \brief
    /// Advances the reader to the next item. The default position of the
    /// reader is prior to the first item. Thus, you must call ReadNext
    /// to begin accessing any data.
    /// 
    /// \return
    /// Returns true if there is a next item.
    /// 
    System::Boolean ReadNext();

    /// \brief
    /// Closes the IDataReader object, freeing any resources it may be holding.
    /// 
    /// \return
    /// Returns nothing
    /// 
    System::Void Close();

    /// \brief
    /// Gets the definition of the object currently being read. If the user
    /// has requested only a subset of the class properties, the class 
    /// definition reflects what the user has asked, rather than the full class 
    /// definition.
    /// 
    /// \return
    /// Returns the class definition object.
    /// 
    OSGEO_FDO_SCHEMA::ClassDefinition* GetClassDefinition();

    /// \brief
    /// Gets a value indicating the depth of nesting for the current reader.
    /// The depth value increases each time GetFeatureObject is called and a new 
    /// reader is returned. The outermost reader has a depth of 0.
    /// 
    /// \return
    /// Returns the depth
    /// 
    System::Int32 GetDepth();

    /// \brief
    /// Gets the geometry value of the specified property as a byte array in 
    /// FGF format. Because no conversion is performed, the property must be
    /// of Geometric type; otherwise, an exception is thrown. 
    /// This method is a language-specific performance optimization that returns a
    /// pointer to the array data, rather than to an object that encapsulates
    /// the array.  The array's memory area is only guaranteed to be valid
    /// until a call to ReadNext() or Close(), or the disposal of this reader
    /// object.
    /// 
    /// \param propertyName 
    /// Input the property name.
    ///
    /// \param count 
    /// Output the number of bytes in the array.
    /// 
    /// \return
    /// Returns a pointer to the byte array in FGF format.
    /// 
    const System::Byte * GetGeometry(System::String* propertyName, System::Int32 * count);


    /// \brief
    /// Gets a reference to an IFeatureReader to read the data contained in
    /// the object or object collection property. If the property is not an
    /// object property, an exception is thrown.
    /// 
    /// \param propertyName 
    /// Input the property name.
    /// 
    /// \return
    /// Returns the nested feature reader
    /// 
    OSGEO_FDO_COMMANDS_FEATURE::IFeatureReader* GetFeatureObject(System::String* propertyName);
};

}}}