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 | Adopted |
| Implementation Status | Under Development |
| Proposed Milestone | 3.3.0.0 |
| Assigned PSC guide(s) | Greg Boone |
| Voting History | August 23, 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<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.
