FDO RFC 5 - Modify Fdo API FdoFunctionDefinition

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	Jul 16, 2007
Last Modified	Greg Boone Timestamp
Author	Thomas Knoell
RFC Status	Draft
Implementation Status	Under Development
Proposed Milestone	3.3.0.0
Assigned PSC guide(s)	Greg Boone
Voting History	TBD
+1
+0
-0
-1

Overview

The purpose of this RFC is to enhance the class FdoFunctionDefinition. This class allows a provider to define a set of supported expression functions. The list of supported expression functions is accessible as part of the expression capabilities that can be retrieved from a connection.

The enhancement will add a new property to the class allowing the specification of the function class type a given function belongs to. The valid function types will be defined in an enumeration and initially contain values to indicate aggregate, conversion, date, mathematical, numeric, string, geometry and custom functions. The enumeration will also include a value to indicate an upspecified function class type. This function class type will represent the default value.

The enhancement will allow a consumer of the list of supported expression functions to sort them according to their class type. This may help in presenting the functions in a user-defined UI as similar functions can be grouped. The following shows examples of functions grouped according to their corresponding function class:

AGGREGATE: Avg, Max, Min, Sum

CONVERSION: ToDate, ToDouble, ToFloat, !ToInt32, !ToInt64

DATE: AddMonths, CurrentDate, ToString

MATH: Asin, Atan, Cos, Exp, Ln, Log, Sqrt

NUMERIC: Ceil, Floor, Round, Sign

STRING: Concat, Instr, Lower, Lpad, Ltrim, Upper

GEOMETRY: Area, Length

Any provider may support additional functions that may not be classified as either a aggregate, conversion, date, mathematical, numeric, string or geometry function. Those functions may be grouped as !FdoFunctionClassType_Custom instead.

The function class will be set via the currently available interfaces (create method). To allow this the interfaces will be enhanced with an optional function class type parameter which will be set to the default value.

Proposed Solution

This section outlines the necessary code changes in the unmanaged and managed code.

Unmanaged Code

Changes in the unmanaged code include the addition of a new enumeration and changes to the class FdoFunctionDefinition. The following figure shows the new enumeration.

enum FdoFunctionClassType {

                 FdoFunctionClassType_Aggregate,
                 FdoFunctionClassType_Conversion,
                 FdoFunctionClassType_Custom,
                 FdoFunctionClassType_Date,
                 FdoFunctionClassType_Geometry,
                 FdoFunctionClassType_Math,
                 FdoFunctionClassType_Numeric,
                 FdoFunctionClassType_String,
                 FdoFunctionClassType_Unspecified 

}  //  enum FdoFunctionClassType

The following figure shows the required changes to the class FdoFunctionDefinition. Note that the listing only shows the modified or added specifications.

class FdoFunctionDefinition : public FdoIDisposable
{
...
protected:
    FdoFunctionDefinition (FdoString                       *name,
                           FdoString                       *description,
                           FdoDataType                     returnType,
                           FdoArgumentDefinitionCollection *arguments,
                           FdoFunctionClassType            functionClassType);

    FdoFunctionDefinition (FdoString                       *name,
                           FdoString                       *description,
                           FdoPropertyType                 returnPropertyType,
                           FdoDataType                     returnType,
                           FdoArgumentDefinitionCollection *arguments,
                           FdoFunctionClassType            functionClassType);

    FdoFunctionDefinition (FdoString                        *name,
                           FdoString                        *description,
                           bool                             isAggregate,
                           FdoSignatureDefinitionCollection *signatures,
                           FdoFunctionClassType             functionClassType);
...

public:
...
    /// \brief
    /// Returns the function class for the current function definition.
    /// 
    /// \return
    /// Returns FdoFunctionClassType
    /// 
    FDO_API FdoFunctionClassType GetFunctionClassType();

    /// \brief
    ///  Constructs an instance of an FdoFunctionDefinition using the specified arguments.
    /// 
    /// \param name 
    /// Input the name of the function.
    /// \param description 
    /// Input a brief description.
    /// \param returnType 
    /// Input the function return type
    /// \param arguments 
    /// Input the argument definition list
    /// \param functionClassType 
    /// Input the function class type the function belongs to. If not specified the function is classified as unspecified. Valid
    /// values for this parameter are defined in the enumeration FdoFunctionClassType.
    /// 
    /// \return
    /// Returns FdoFunctionDefinition
    /// 
    FDO_API static FdoFunctionDefinition *Create (FdoString                       *name,
                                                  FdoString                       *description,
                                                  FdoDataType                     returnType,
                                                  FdoArgumentDefinitionCollection *arguments,
                                                  FdoFunctionClassType            functionClassType = FdoFunctionClassType_Unspecified);

    /// \brief
    ///  Constructs an instance of an FdoFunctionDefinition using the specified arguments.
    /// 
    /// \param name 
    /// Input the name of the function.
    /// \param description 
    /// Input a brief description.
    /// \param returnPropertyType 
    /// Input the function return property type
    /// \param returnType 
    /// Input the function return data type (ignore it property type is not data)
    /// \param arguments 
    /// Input the argument definition list
    /// \param functionClassType 
    /// Input the function class type the function belongs to. If not specified the function is classified as unspecified. Valid
    /// values for this parameter are defined in the enumeration FdoFunctionClassType.
    /// 
    /// \return
    /// Returns FdoFunctionDefinition
    /// 
    FDO_API static FdoFunctionDefinition *Create (FdoString                       *name,
                                                  FdoString                       *description,
                                                  FdoPropertyType                 returnPropertyType,
                                                  FdoDataType                     returnType,
                                                  FdoArgumentDefinitionCollection *arguments,
                                                  FdoFunctionClassType            functionClassType = FdoFunctionClassType_Unspecified);

    /// \brief
    ///  Constructs an instance of an FdoFunctionDefinition using the specified arguments.
    /// 
    /// \param name 
    /// Input the name of the function.
    /// \param description 
    /// Input a brief description.
    /// \param isAggregate 
    /// Input a flag indicating whether or not this is an aggregate function.
    /// \param signatures 
    /// Input the list of possible function signatures
    /// \param functionClassType 
    /// Input the function class type the function belongs to. If not specified the function is classified as unspecified. Valid
    /// values for this parameter are defined in the enumeration FdoFunctionClassType.
    /// 
    /// \return
    /// Returns FdoFunctionDefinition
    /// 
    FDO_API static FdoFunctionDefinition *Create (FdoString                        *name,
                                                  FdoString                        *description,
                                                  bool                             isAggregate,
                                                  FdoSignatureDefinitionCollection *signatures,
                                                  FdoFunctionClassType             functionClassType = FdoFunctionClassType_Unspecified);
...

protected:
...
    FdoFunctionClassType m_functionClassType;
...

}

Managed Code

Like the modifications in the unmanaged code base, the changes in the managed code include the addition of a new enumeration and changes to the class FunctionDefinition. The following figure shows the new enumeration.

public __value enum FunctionClassType {

                 FunctionClassType_Aggregate   = FdoFunctionClassType_Aggregate,
                 FunctionClassType_Conversion  = FdoFunctionClassType_Conversion,
                 FunctionClassType_Custom      = FdoFunctionClassType_Custom,
                 FunctionClassType_Date        = FdoFunctionClassType_Date,
                 FunctionClassType_Geometry    = FdoFunctionClassType_Geometry,
                 FunctionClassType_Math        = FdoFunctionClassType_Math,
                 FunctionClassType_Numeric     = FdoFunctionClassType_Numeric,
                 FunctionClassType_String      = FdoFunctionClassType_String,
                 FunctionClassType_Unspecified = FdoFunctionClassType_Unspecified 

}  //  enum FunctionClassType

The newly added enumeration will live in the namespace OSGEO_FDO_CONNECTIONS_CAPABILITIES.

The change required to the class FunctionDefinition is the addition of a couple of new class constructors and property-related functions to reflect the change in the unmanaged code. The following figure outlines this. Note that the listing only shows the modified or added specifications.

public __gc class FunctionDefinition : public NAMESPACE_OSGEO_RUNTIME::Disposable
{
public:
    /// \brief
    ///  Constructs an instance of a FunctionDefinition using the specified arguments.
    /// 
    /// \param name 
    /// Input the name of the function.
    /// \param description 
    /// Input a brief description.
    /// \param returnType 
    /// Input the function return type
    /// \param arguments 
    /// Input the argument definition list
    /// \param functionClassType 
    /// Input the function class type the function belongs to. Valid values for this parameter are defined
    /// in the enumeration FunctionClassType.
    /// 
    /// \return
    /// Returns FunctionDefinition
    /// 
    FunctionDefinition (System::String *name,
                        System::String *description,
                        NAMESPACE_OSGEO_FDO_SCHEMA::DataType returnType,
                        NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::ArgumentDefinitionCollection *arguments,
                        NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::FunctionClassType functionClassType);

    /// \brief
    ///  Constructs an instance of a FunctionDefinition using the specified arguments.
    /// 
    /// \param name 
    /// Input the name of the function.
    /// \param description 
    /// Input a brief description.
    /// \param isAggregate 
    /// Input the flag indicating whether or not this is an aggregate function
    /// \param signatures 
    /// Input the list of possible function signatures
    /// \param functionClassType 
    /// Input the function class type the function belongs to. Valid values for this parameter are defined
    /// in the enumeration FunctionClassType.
    /// 
    /// \return
    /// Returns FunctionDefinition
    /// 
    FunctionDefinition (System::String *name,
                        System::String *description,
                        System::Boolean isAggregate,
                        NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::SignatureDefinitionCollection *signatures,
                        NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::FunctionClassType functionClassType);

...

    /// \brief
    ///  Gets the function class type of the function.
    /// 
    /// \return
    /// Returns the function class type
    /// 
	__property NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::FunctionClassType get_FunctionClassType();

...

}

Example

The following shows an example on how this property may be used. In this example, the function definition for the functions CONCAT and MAX are defined. Please note, that the example lists only a subset of the signatures the functions may support and does not externalize public names and descriptions as the purpose of the example is to show the usage of the new property.

    // Create the necessary argument definitions.

    FdoPtr<FdoArgumentDefinition> maxArg =
                 FdoArgumentDefinition::Create(L"Numeric", L”Argument to be processed”, FdoDataType_Double);
    FdoPtr<FdoArgumentDefinition> concatArg1 =
                 FdoArgumentDefinition::Create(L"String", L”First string to be concatenated”, FdoDataType_String);
    FdoPtr<FdoArgumentDefinition> concatArg2 =
                 FdoArgumentDefinition::Create(L"String", L”Second string to be concatenated”, FdoDataType_String);

    // Create the required argument definition collections.

    FdoPtr<FdoArgumentDefinitionCollection>maxArguments = FdoArgumentDefinitionCollection::Create();
    FdoPtr<FdoArgumentDefinitionCollection>concatArguments = FdoArgumentDefinitionCollection::Create();

    //  Fill the argument definition collections with the according argument definitions.

    maxArguments->Add(maxArg);
    concatArguments->Add(concatArg1);
    concatArguments->Add(concatArg2);

    // Create the signatures for the functions.

    FdoPtr<FdoSignatureDefinition> maxSignature;
    FdoPtr<FdoSignatureDefinition> concatSignature;
    FdoPtr<FdoSignatureDefinitionCollection> maxSignatures = FdoSignatureDefinitionCollection::Create();
    FdoPtr<FdoSignatureDefinitionCollection> concatSignatures = FdoSignatureDefinitionCollection::Create();

    maxSignature = FdoSignatureDefinition::Create(FdoDataType_Double, maxArguments);
    maxSignatures->Add(maxSignature);

    concatSignature = FdoSignatureDefinition::Create(FdoDataType_String, concatArguments);
    concatSignatures->Add(concatSignature);

    // Create the function definitions for the functions CONCAT and MAX

    FdoPtr<FdoFunctionDefinition> maxFunc =
                  FdoFunctionDefinition::Create(L”MAX”,
                                                L”Determines the maximum value of an expression”,
                                                true,
                                                maxSignatures,
                                                FdoFunctionClassType_Aggregate);

    FdoPtr<FdoFunctionDefinition> concatFunc =
                  FdoFunctionDefinition::Create(L”CONCAT”,
                                                L”Concatenates the provided strings”,
                                                false,
                                                concatSignatures,
                                                FdoFunctionClassType_String);

Implications

This change will not cause any side-effects, nor any compatibility problems. No existing provider needs to change unless the provider wants to use the new feature.

Test Plan

Existing unit tests will be expanded to test those changes.

Funding/Resources

Autodesk to provide resources / funding to update FDO core.