= 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 [wiki:FDORfcs 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 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, intrinsic and custom functions. The enumeration will also include a value to indicate an upspecified function class. This function class 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. 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''

INTRINSIC::
''Area'', ''Length''


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 parameter which will be set to the default value.


== Proposed Solution ==

The following shows the new enumeration. 

{{{
enum FdoFunctionClass {
                 FdoFunctionClass_Aggregate,
                 FdoFunctionClass_Conversion,
                 FdoFunctionClass_Custom,
                 FdoFunctionClass_Date,
                 FdoFunctionClass_Intrinsic,
                 FdoFunctionClass_Math,
                 FdoFunctionClass_Numeric,
                 FdoFunctionClass_String,
                 FdoFunctionClass_Unspecified 
}  //  enum FdoFunctionClass
}}}

The following 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,
                           FdoFunctionClass                functionClass);

    FdoFunctionDefinition (FdoString                       *name,
                           FdoString                       *description,
                           FdoPropertyType                 returnPropertyType,
                           FdoDataType                     returnType,
                           FdoArgumentDefinitionCollection *arguments,
                           FdoFunctionClass                functionClass);

    FdoFunctionDefinition (FdoString                        *name,
                           FdoString                        *description,
                           bool                             isAggregate,
                           FdoSignatureDefinitionCollection *signatures,
                           FdoFunctionClass                 functionClass);
...

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

    /// Various public Constructors

    FDO_API static FdoFunctionDefinition *Create (FdoString                       *name,
                                                  FdoString                       *description,
                                                  FdoDataType                     returnType,
                                                  FdoArgumentDefinitionCollection *arguments,
                                                  FdoFunctionClass                functionClass = FdoFunctionClass_Unspecified);

    FDO_API static FdoFunctionDefinition *Create (FdoString                       *name,
                                                  FdoString                       *description,
                                                  FdoPropertyType                 returnPropertyType,
                                                  FdoDataType                     returnType,
                                                  FdoArgumentDefinitionCollection *arguments,
                                                  FdoFunctionClass                functionClass = FdoFunctionClass_Unspecified);

    FDO_API static FdoFunctionDefinition *Create (FdoString                        *name,
                                                  FdoString                        *description,
                                                  bool                             isAggregate,
                                                  FdoSignatureDefinitionCollection *signatures,
                                                  FdoFunctionClass                 functionClass = FdoFunctionClass_Unspecified);
...

protected:
...
    FdoFunctionClass m_functionClass;
...

}
}}}


== 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.