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	Frozen for Vote
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 category a given function belongs to. The valid categories will be defined in an enumeration and initially contain values to indicate aggregate, conversion, date, mathematical, numeric, string, geometry and custom function categories. The enumeration will also include a value to indicate an upspecified function category. This function category represents the default value.

The enhancement will allow a consumer of the list of supported expression functions to sort them according to their category. 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 category:

AGGREGATE: Avg, Max, Min, Sum

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

DATE: AddMonths, CurrentDate, Extract

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 classified as custom functions instead.

The function category will be set via the currently available interfaces (create method). To allow this the interfaces will be enhanced with an optional function category 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 FdoFunctionCategoryType {

                 FdoFunctionCategoryType_Aggregate,
                 FdoFunctionCategoryType_Conversion,
                 FdoFunctionCategoryType_Custom,
                 FdoFunctionCategoryType_Date,
                 FdoFunctionCategoryType_Geometry,
                 FdoFunctionCategoryType_Math,
                 FdoFunctionCategoryType_Numeric,
                 FdoFunctionCategoryType_String,
                 FdoFunctionCategoryType_Unspecified 

}  //  enum FdoFunctionCategoryType

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,
                           FdoFunctionCategoryType         functionCategoryType);

    FdoFunctionDefinition (FdoString                       *name,
                           FdoString                       *description,
                           FdoPropertyType                 returnPropertyType,
                           FdoDataType                     returnType,
                           FdoArgumentDefinitionCollection *arguments,
                           FdoFunctionCategoryType         functionCategoryType);

    FdoFunctionDefinition (FdoString                        *name,
                           FdoString                        *description,
                           bool                             isAggregate,
                           FdoSignatureDefinitionCollection *signatures,
                           FdoFunctionCategoryType          functionCategoryType);
...

public:
...
    /// \brief
    /// Returns the category for the function described in the current function definition.
    /// 
    /// \return
    /// Returns FdoFunctionCategoryType
    /// 
    FDO_API FdoFunctionCategoryType GetFunctionCategoryType();

    /// \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 functionCategoryType 
    /// Input the category the function belongs to. If not specified the function is classified as unspecified. Valid
    /// values for this parameter are defined in the enumeration FdoFunctionCategoryType.
    /// 
    /// \return
    /// Returns FdoFunctionDefinition
    /// 
    FDO_API static FdoFunctionDefinition *Create (FdoString                       *name,
                                                  FdoString                       *description,
                                                  FdoDataType                     returnType,
                                                  FdoArgumentDefinitionCollection *arguments,
                                                  FdoFunctionCategoryType         functionCategoryType = FdoFunctionCategoryType_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 functionCategoryType 
    /// Input the category the function belongs to. If not specified the function is classified as unspecified. Valid
    /// values for this parameter are defined in the enumeration FdoFunctionCategoryType.
    /// 
    /// \return
    /// Returns FdoFunctionDefinition
    /// 
    FDO_API static FdoFunctionDefinition *Create (FdoString                       *name,
                                                  FdoString                       *description,
                                                  FdoPropertyType                 returnPropertyType,
                                                  FdoDataType                     returnType,
                                                  FdoArgumentDefinitionCollection *arguments,
                                                  FdoFunctionCategoryType         functionCategoryType = FdoFunctionCategoryType_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 functionCategoryType 
    /// Input the category the function belongs to. If not specified the function is classified as unspecified. Valid
    /// values for this parameter are defined in the enumeration FdoFunctionCategoryType.
    /// 
    /// \return
    /// Returns FdoFunctionDefinition
    /// 
    FDO_API static FdoFunctionDefinition *Create (FdoString                        *name,
                                                  FdoString                        *description,
                                                  bool                             isAggregate,
                                                  FdoSignatureDefinitionCollection *signatures,
                                                  FdoFunctionCategoryType          functionCategoryType = FdoFunctionCategoryType_Unspecified);
...

protected:
...
    FdoFunctionCategoryType m_functionCategoryType;
...

}

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 FunctionCategoryType {

                 FunctionCategoryType_Aggregate   = FdoFunctionCategoryType_Aggregate,
                 FunctionCategoryType_Conversion  = FdoFunctionCategoryType_Conversion,
                 FunctionCategoryType_Custom      = FdoFunctionCategoryType_Custom,
                 FunctionCategoryType_Date        = FdoFunctionCategoryType_Date,
                 FunctionCategoryType_Geometry    = FdoFunctionCategoryType_Geometry,
                 FunctionCategoryType_Math        = FdoFunctionCategoryType_Math,
                 FunctionCategoryType_Numeric     = FdoFunctionCategoryType_Numeric,
                 FunctionCategoryType_String      = FdoFunctionCategoryType_String,
                 FunctionCategoryType_Unspecified = FdoFunctionCategoryType_Unspecified 

}  //  enum FunctionCategoryType

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 returnPropertyType 
    /// Input the function return property type
    /// \param returnType 
    /// Input the function return type
    /// \param arguments 
    /// Input the argument definition list
    /// 
    /// \return
    /// Returns FunctionDefinition
    /// 
    FunctionDefinition (System::String *name,
                        System::String *description,
                        NAMESPACE_OSGEO_FDO_SCHEMA::PropertyType returnPropertyType,
                        NAMESPACE_OSGEO_FDO_SCHEMA::DataType returnType,
                        NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::ArgumentDefinitionCollection *arguments);

    /// \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 functionCategoryType 
    /// Input the category the function belongs to. Valid values for this parameter are defined
    /// in the enumeration FunctionCategoryType.
    /// 
    /// \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::FunctionCategoryType functionCategoryType);

    /// \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 functionCategoryType 
    /// Input the category the function belongs to. Valid values for this parameter are defined
    /// in the enumeration FunctionCategoryType.
    /// 
    /// \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::FunctionCategoryType functionCategoryType);

    /// \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 returnPropertyType 
    /// Input the function return property type
    /// \param returnType 
    /// Input the function return type
    /// \param arguments 
    /// Input the argument definition list
    /// \param functionCategoryType 
    /// Input the category the function belongs to. Valid values for this parameter are defined
    /// in the enumeration FunctionCategoryType.
    /// 
    /// \return
    /// Returns FunctionDefinition
    /// 
    FunctionDefinition (System::String *name,
                        System::String *description,
                        NAMESPACE_OSGEO_FDO_SCHEMA::PropertyType returnPropertyType,
                        NAMESPACE_OSGEO_FDO_SCHEMA::DataType returnType,
                        NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::ArgumentDefinitionCollection *arguments,
                        NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::FunctionCategoryType functionCategoryType);

...

    /// \brief
    ///  Gets the category the function belongs to.
    /// 
    /// \return
    /// Returns the function category
    /// 
	__property NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::FunctionCategoryType get_FunctionCategoryType();

...

}

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,
                                                FdoFunctionCategoryType_Aggregate);

    FdoPtr<FdoFunctionDefinition> concatFunc =
                  FdoFunctionDefinition::Create(L”CONCAT”,
                                                L”Concatenates the provided strings”,
                                                false,
                                                concatSignatures,
                                                FdoFunctionCategoryType_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.