Changes between Version 12 and Version 13 of FDORfc5
- Timestamp:
- Jul 31, 2007, 10:53:57 AM (17 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
FDORfc5
v12 v13 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. 27 27 28 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 classwill represent the default value.29 30 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:31 32 AGGREGATE: :28 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. 29 30 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: 31 32 AGGREGATE: 33 33 ''Avg'', ''Max'', ''Min'', ''Sum'' 34 34 35 CONVERSION: :35 CONVERSION: 36 36 ''!ToDate'', ''!ToDouble'', ''!ToFloat'', ''!ToInt32'', ''!ToInt64'' 37 37 38 DATE: :38 DATE: 39 39 ''!AddMonths'', ''!CurrentDate'', ''!ToString'' 40 40 41 MATH: :41 MATH: 42 42 ''Asin'', ''Atan'', ''Cos'', ''Exp'', ''Ln'', ''Log'', ''Sqrt'' 43 43 44 NUMERIC: :44 NUMERIC: 45 45 ''Ceil'', ''Floor'', ''Round'', ''Sign'' 46 46 47 STRING: :47 STRING: 48 48 ''Concat'', ''Instr'', ''Lower'', ''Lpad'', ''Ltrim'', ''Upper'' 49 49 50 INTRINSIC::50 GEOMETRY: 51 51 ''Area'', ''Length'' 52 52 53 54 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. 53 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. 54 55 56 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. 55 57 56 58 57 59 == Proposed Solution == 58 60 59 The following shows the new enumeration. 60 61 {{{ 62 enum FdoFunctionClass { 63 FdoFunctionClass_Aggregate, 64 FdoFunctionClass_Conversion, 65 FdoFunctionClass_Custom, 66 FdoFunctionClass_Date, 67 FdoFunctionClass_Intrinsic, 68 FdoFunctionClass_Math, 69 FdoFunctionClass_Numeric, 70 FdoFunctionClass_String, 71 FdoFunctionClass_Unspecified 72 } // enum FdoFunctionClass 73 }}} 74 75 The following shows the required changes to the class ''!FdoFunctionDefinition''. Note that the listing only shows the modified or added specifications. 61 This section outlines the necessary code changes in the unmanaged and managed code. 62 63 === Unmanaged Code === 64 65 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. 66 67 {{{ 68 enum FdoFunctionClassType { 69 70 FdoFunctionClassType_Aggregate, 71 FdoFunctionClassType_Conversion, 72 FdoFunctionClassType_Custom, 73 FdoFunctionClassType_Date, 74 FdoFunctionClassType_Geometry, 75 FdoFunctionClassType_Math, 76 FdoFunctionClassType_Numeric, 77 FdoFunctionClassType_String, 78 FdoFunctionClassType_Unspecified 79 80 } // enum FdoFunctionClassType 81 }}} 82 83 The following figure shows the required changes to the class ''!FdoFunctionDefinition''. Note that the listing only shows the modified or added specifications. 76 84 77 85 {{{ … … 85 93 FdoDataType returnType, 86 94 FdoArgumentDefinitionCollection *arguments, 87 FdoFunctionClass functionClass);95 FdoFunctionClassType functionClassType); 88 96 89 97 FdoFunctionDefinition (FdoString *name, … … 92 100 FdoDataType returnType, 93 101 FdoArgumentDefinitionCollection *arguments, 94 FdoFunctionClass functionClass);102 FdoFunctionClassType functionClassType); 95 103 96 104 FdoFunctionDefinition (FdoString *name, … … 98 106 bool isAggregate, 99 107 FdoSignatureDefinitionCollection *signatures, 100 FdoFunctionClass functionClass);108 FdoFunctionClassType functionClassType); 101 109 ... 102 110 … … 107 115 /// 108 116 /// \return 109 /// Returns FdoFunctionClass 110 /// 111 FDO_API FdoFunctionClass GetFunctionClass(); 112 113 /// Various public Constructors 114 117 /// Returns FdoFunctionClassType 118 /// 119 FDO_API FdoFunctionClassType GetFunctionClassType(); 120 121 /// \brief 122 /// Constructs an instance of an FdoFunctionDefinition using the specified arguments. 123 /// 124 /// \param name 125 /// Input the name of the function. 126 /// \param description 127 /// Input a brief description. 128 /// \param returnType 129 /// Input the function return type 130 /// \param arguments 131 /// Input the argument definition list 132 /// \param functionClassType 133 /// Input the function class type the function belongs to. If not specified the function is classified as unspecified. Valid 134 /// values for this parameter are defined in the enumeration FdoFunctionClassType. 135 /// 136 /// \return 137 /// Returns FdoFunctionDefinition 138 /// 115 139 FDO_API static FdoFunctionDefinition *Create (FdoString *name, 116 140 FdoString *description, 117 141 FdoDataType returnType, 118 142 FdoArgumentDefinitionCollection *arguments, 119 FdoFunctionClass functionClass = FdoFunctionClass_Unspecified); 120 143 FdoFunctionClassType functionClassType = FdoFunctionClassType_Unspecified); 144 145 /// \brief 146 /// Constructs an instance of an FdoFunctionDefinition using the specified arguments. 147 /// 148 /// \param name 149 /// Input the name of the function. 150 /// \param description 151 /// Input a brief description. 152 /// \param returnPropertyType 153 /// Input the function return property type 154 /// \param returnType 155 /// Input the function return data type (ignore it property type is not data) 156 /// \param arguments 157 /// Input the argument definition list 158 /// \param functionClassType 159 /// Input the function class type the function belongs to. If not specified the function is classified as unspecified. Valid 160 /// values for this parameter are defined in the enumeration FdoFunctionClassType. 161 /// 162 /// \return 163 /// Returns FdoFunctionDefinition 164 /// 121 165 FDO_API static FdoFunctionDefinition *Create (FdoString *name, 122 166 FdoString *description, … … 124 168 FdoDataType returnType, 125 169 FdoArgumentDefinitionCollection *arguments, 126 FdoFunctionClass functionClass = FdoFunctionClass_Unspecified); 127 170 FdoFunctionClassType functionClassType = FdoFunctionClassType_Unspecified); 171 172 /// \brief 173 /// Constructs an instance of an FdoFunctionDefinition using the specified arguments. 174 /// 175 /// \param name 176 /// Input the name of the function. 177 /// \param description 178 /// Input a brief description. 179 /// \param isAggregate 180 /// Input a flag indicating whether or not this is an aggregate function. 181 /// \param signatures 182 /// Input the list of possible function signatures 183 /// \param functionClassType 184 /// Input the function class type the function belongs to. If not specified the function is classified as unspecified. Valid 185 /// values for this parameter are defined in the enumeration FdoFunctionClassType. 186 /// 187 /// \return 188 /// Returns FdoFunctionDefinition 189 /// 128 190 FDO_API static FdoFunctionDefinition *Create (FdoString *name, 129 191 FdoString *description, 130 192 bool isAggregate, 131 193 FdoSignatureDefinitionCollection *signatures, 132 FdoFunctionClass functionClass = FdoFunctionClass_Unspecified);194 FdoFunctionClassType functionClassType = FdoFunctionClassType_Unspecified); 133 195 ... 134 196 135 197 protected: 136 198 ... 137 FdoFunctionClass m_functionClass;199 FdoFunctionClassType m_functionClassType; 138 200 ... 139 201 … … 141 203 }}} 142 204 205 === Managed Code === 206 207 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. 208 209 {{{ 210 public __value enum FunctionClassType { 211 212 FunctionClassType_Aggregate = FdoFunctionClassType_Aggregate, 213 FunctionClassType_Conversion = FdoFunctionClassType_Conversion, 214 FunctionClassType_Custom = FdoFunctionClassType_Custom, 215 FunctionClassType_Date = FdoFunctionClassType_Date, 216 FunctionClassType_Geometry = FdoFunctionClassType_Geometry, 217 FunctionClassType_Math = FdoFunctionClassType_Math, 218 FunctionClassType_Numeric = FdoFunctionClassType_Numeric, 219 FunctionClassType_String = FdoFunctionClassType_String, 220 FunctionClassType_Unspecified = FdoFunctionClassType_Unspecified 221 222 } // enum FunctionClassType 223 }}} 224 225 The newly added enumeration will live in the namespace ''OSGEO_FDO_CONNECTIONS_CAPABILITIES''. 226 227 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. 228 229 {{{ 230 231 public __gc class FunctionDefinition : public NAMESPACE_OSGEO_RUNTIME::Disposable 232 { 233 public: 234 /// \brief 235 /// Constructs an instance of a FunctionDefinition using the specified arguments. 236 /// 237 /// \param name 238 /// Input the name of the function. 239 /// \param description 240 /// Input a brief description. 241 /// \param returnType 242 /// Input the function return type 243 /// \param arguments 244 /// Input the argument definition list 245 /// \param functionClassType 246 /// Input the function class type the function belongs to. Valid values for this parameter are defined 247 /// in the enumeration FunctionClassType. 248 /// 249 /// \return 250 /// Returns FunctionDefinition 251 /// 252 FunctionDefinition (System::String *name, 253 System::String *description, 254 NAMESPACE_OSGEO_FDO_SCHEMA::DataType returnType, 255 NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::ArgumentDefinitionCollection *arguments, 256 NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::FunctionClassType functionClassType); 257 258 /// \brief 259 /// Constructs an instance of a FunctionDefinition using the specified arguments. 260 /// 261 /// \param name 262 /// Input the name of the function. 263 /// \param description 264 /// Input a brief description. 265 /// \param isAggregate 266 /// Input the flag indicating whether or not this is an aggregate function 267 /// \param signatures 268 /// Input the list of possible function signatures 269 /// \param functionClassType 270 /// Input the function class type the function belongs to. Valid values for this parameter are defined 271 /// in the enumeration FunctionClassType. 272 /// 273 /// \return 274 /// Returns FunctionDefinition 275 /// 276 FunctionDefinition (System::String *name, 277 System::String *description, 278 System::Boolean isAggregate, 279 NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::SignatureDefinitionCollection *signatures, 280 NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::FunctionClassType functionClassType); 281 282 ... 283 284 /// \brief 285 /// Gets the function class type of the function. 286 /// 287 /// \return 288 /// Returns the function class type 289 /// 290 __property NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::FunctionClassType get_FunctionClassType(); 291 292 ... 293 294 } 295 }}} 296 297 == Example == 298 299 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. 300 301 {{{ 302 303 // Create the necessary argument definitions. 304 305 FdoPtr<FdoArgumentDefinition> maxArg = 306 FdoArgumentDefinition::Create(L"Numeric", L”Argument to be processed”, FdoDataType_Double); 307 FdoPtr<FdoArgumentDefinition> concatArg1 = 308 FdoArgumentDefinition::Create(L"String", L”First string to be concatenated”, FdoDataType_String); 309 FdoPtr<FdoArgumentDefinition> concatArg2 = 310 FdoArgumentDefinition::Create(L"String", L”Second string to be concatenated”, FdoDataType_String); 311 312 // Create the required argument definition collections. 313 314 FdoPtr<FdoArgumentDefinitionCollection>maxArguments = FdoArgumentDefinitionCollection::Create(); 315 FdoPtr<FdoArgumentDefinitionCollection>concatArguments = FdoArgumentDefinitionCollection::Create(); 316 317 // Fill the argument definition collections with the according argument definitions. 318 319 maxArguments->Add(maxArg); 320 concatArguments->Add(concatArg1); 321 concatArguments->Add(concatArg2); 322 323 // Create the signatures for the functions. 324 325 FdoPtr<FdoSignatureDefinition> maxSignature; 326 FdoPtr<FdoSignatureDefinition> concatSignature; 327 FdoPtr<FdoSignatureDefinitionCollection> maxSignatures = FdoSignatureDefinitionCollection::Create(); 328 FdoPtr<FdoSignatureDefinitionCollection> concatSignatures = FdoSignatureDefinitionCollection::Create(); 329 330 maxSignature = FdoSignatureDefinition::Create(FdoDataType_Double, maxArguments); 331 maxSignatures->Add(maxSignature); 332 333 concatSignature = FdoSignatureDefinition::Create(FdoDataType_String, concatArguments); 334 concatSignatures->Add(concatSignature); 335 336 // Create the function definitions for the functions CONCAT and MAX 337 338 FdoPtr<FdoFunctionDefinition> maxFunc = 339 FdoFunctionDefinition::Create(L”MAX”, 340 L”Determines the maximum value of an expression”, 341 true, 342 maxSignatures, 343 FdoFunctionClassType_Aggregate); 344 345 FdoPtr<FdoFunctionDefinition> concatFunc = 346 FdoFunctionDefinition::Create(L”CONCAT”, 347 L”Concatenates the provided strings”, 348 false, 349 concatSignatures, 350 FdoFunctionClassType_String); 351 352 }}} 353 143 354 144 355 == Implications ==
