= 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||Frozen for Vote|| ||Implementation Status ||Under Development|| ||Proposed Milestone||3.3.0.0|| ||Assigned PSC guide(s)||Greg Boone|| ||'''Voting History'''|| August 2, 2007 || ||+1||Bob, Greg, Orest, Harris|| ||+0||Frank, Jason|| ||-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 maxArg = FdoArgumentDefinition::Create(L"Numeric", L”Argument to be processed”, FdoDataType_Double); FdoPtr concatArg1 = FdoArgumentDefinition::Create(L"String", L”First string to be concatenated”, FdoDataType_String); FdoPtr concatArg2 = FdoArgumentDefinition::Create(L"String", L”Second string to be concatenated”, FdoDataType_String); // Create the required argument definition collections. FdoPtrmaxArguments = FdoArgumentDefinitionCollection::Create(); FdoPtrconcatArguments = 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 maxSignature; FdoPtr concatSignature; FdoPtr maxSignatures = FdoSignatureDefinitionCollection::Create(); FdoPtr 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 maxFunc = FdoFunctionDefinition::Create(L”MAX”, L”Determines the maximum value of an expression”, true, maxSignatures, FdoFunctionCategoryType_Aggregate); FdoPtr 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.