Changes between Version 12 and Version 13 of FDORfc5

Timestamp:

07/31/07 10:53:57 (18 years ago)

Author:

thomasknoell

Comment:

--

FDORfc5

@@ -26 +26 @@
 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::
+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::
+CONVERSION:
 ''!ToDate'', ''!ToDouble'', ''!ToFloat'', ''!ToInt32'', ''!ToInt64''
 
-DATE::
+DATE:
 ''!AddMonths'', ''!CurrentDate'', ''!ToString''
 
-MATH::
+MATH:
 ''Asin'', ''Atan'', ''Cos'', ''Exp'', ''Ln'', ''Log'', ''Sqrt''
 
-NUMERIC::
+NUMERIC:
 ''Ceil'', ''Floor'', ''Round'', ''Sign''
 
-STRING::
+STRING:
 ''Concat'', ''Instr'', ''Lower'', ''Lpad'', ''Ltrim'', ''Upper''
 
-INTRINSIC::
+GEOMETRY:
 ''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.
+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 ==
 
-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. 
+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. 
 
 {{{
@@ -85 +93 @@
                            FdoDataType                     returnType,
                            FdoArgumentDefinitionCollection *arguments,
-                           FdoFunctionClass                functionClass);
+                           FdoFunctionClassType            functionClassType);
 
     FdoFunctionDefinition (FdoString                       *name,
@@ -92 +100 @@
                            FdoDataType                     returnType,
                            FdoArgumentDefinitionCollection *arguments,
-                           FdoFunctionClass                functionClass);
+                           FdoFunctionClassType            functionClassType);
 
     FdoFunctionDefinition (FdoString                        *name,
@@ -98 +106 @@
                            bool                             isAggregate,
                            FdoSignatureDefinitionCollection *signatures,
-                           FdoFunctionClass                 functionClass);
+                           FdoFunctionClassType             functionClassType);
 ...
 
@@ -107 +115 @@
     /// 
     /// \return
-    /// Returns FdoFunctionClass
-    /// 
-    FDO_API FdoFunctionClass GetFunctionClass();
-
-    /// Various public Constructors
-
+    /// 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,
-                                                  FdoFunctionClass                functionClass = FdoFunctionClass_Unspecified);
-
+                                                  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,
@@ -124 +168 @@
                                                   FdoDataType                     returnType,
                                                   FdoArgumentDefinitionCollection *arguments,
-                                                  FdoFunctionClass                functionClass = FdoFunctionClass_Unspecified);
-
+                                                  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,
-                                                  FdoFunctionClass                 functionClass = FdoFunctionClass_Unspecified);
+                                                  FdoFunctionClassType             functionClassType = FdoFunctionClassType_Unspecified);
 ...
 
 protected:
 ...
-    FdoFunctionClass m_functionClass;
+    FdoFunctionClassType m_functionClassType;
 ...
 
@@ -141 +203 @@
 }}}
 
+=== 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 ==