58 | | The aim of this requirement is to address this issue. The idea is to have a simplified set of capability interfaces that allows retrieving different capability values where the capability for which the value is to be returned is indicated by an identifier. As a result, adding a new capability would not require the addition of a new interface. |
59 | | |
60 | | All capability functions can be categorized as outlined next: |
61 | | |
62 | | * Boolean: These functions return a flag indicating whether or not a capability is supported. The category includes routines such as !SupportsLocking(), !SupportsCompositeId() or !SupportsAutoIdGeneration(). |
63 | | * Enumerates: These functions return an identifier from an enumeration. The category includes routines such as !GetThreadCapability(). |
64 | | * Array of enumerated values: These functions return an array of values from an enumeration and the number of elements in that array. The category includes routines such as !GetSpatialContextTypes() or !GetLockTypes(). |
65 | | * Collection: These functions return a collection of complex objects. The category includes routines such as !GetFunctions(). |
66 | | * Bit-mask values: These functions return a bit-mask value of enumerated values. The category includes routines such as !GetDimensionality(). |
67 | | * Capability based numbers: These functions take a capability identifier and return the corresponding capability value. The category includes routines such as !GetMaximumDataValueLength() or !GetNameSizeLimit(). |
68 | | * Numbers: These functions return number values of different types. The category includes func-tions such as !GetMaximumDecimalPrecision() or !GetMaximumDecimalScale(). |
69 | | * Strings: These functions return strings. The category includes functions such as !GetReservedCharactersForName(). |
| 58 | The aim of this requirement is to address this issue. The idea is to have a set of simplified capability interfaces that allows the addition of a new capability without requiring to rebuild FDO, any provider that does not immediately support the new capability or any application if the capability is not used. Doing this would not only reduce the number of capability interfaces but also the number of capability classes in FDO. |
| 59 | |
| 60 | Obviously, the new interfaces must be able to replace the current ones. Looking at the existing capability interfaces, they can be categorized as outlined next: |
| 61 | |
| 62 | * Boolean: These functions return a flag indicating whether or not a capability is supported. The category includes routines such as ''!SupportsLocking()'', ''!SupportsCompositeId()'' or ''!SupportsAutoIdGeneration()''. |
| 63 | * Enumerates: These functions return an identifier from an enumeration. The category includes routines such as ''!GetThreadCapability()''. |
| 64 | * Array of enumerated values: These functions return an array of values from an enumeration and the number of elements in that array. The category includes routines such as ''!GetSpatialContextTypes()'' or ''!GetLockTypes()''. |
| 65 | * Collection: These functions return a collection of complex objects. The category includes routines such as ''!GetFunctions()''. |
| 66 | * Bit-mask values: These functions return a bit-mask value of enumerated values. The category includes routines such as ''!GetDimensionality()''. |
| 67 | * Capability based numbers: These functions take a capability identifier and return the corresponding capability value. The category includes routines such as ''!GetMaximumDataValueLength()'' or ''!GetNameSizeLimit()''. |
| 68 | * Numbers: These functions return number values of different types. The category includes func-tions such as ''!GetMaximumDecimalPrecision()'' or ''!GetMaximumDecimalScale()''. |
| 69 | * Strings: These functions return strings. The category includes functions such as ''!GetReservedCharactersForName()''. |
73 | | The simplification of the FDO capability interfaces focuses on those categories as it creates interfaces depending on the expected return type. The number of parameters for those functions is at least one which identifies the capability for which the value is requested. Depending on the category, there may be the need for additional parameters – for example, the function returning an array of enumerated values also has to return the number of entries in that array. |
74 | | |
75 | | The new capability interfaces will be defined in a new class - FdoICapability - that resides in the directory Fdo\Unmanaged\Inc\Fdo\Connections\Capabilities. The following outlines the class definition: |
| 73 | The simplification of the FDO capability interfaces focuses on those categories as it creates interfaces depending on the expected return type. As a result, a capability interface will be processing a number of capabilities that have the same return type and hence requires the caller to identify the capability for which the value should be returned. In addition, the functions must also be able to indicate to the caller if a provided capability identifier is unknown. Therefore, the signature definition of those new interfaces must have at least two parameters: |
| 74 | |
| 75 | * A parameter to indicate the capability for which the value is to be retrieved. |
| 76 | * A parameter with which the interface can indicate to the caller that the provided capability identifier is unknown. |
| 77 | |
| 78 | Depending on the category, there may be the need for additional parameters – for example, the function returning an array of enumerated values also has to return the number of entries in that array. |
| 79 | |
| 80 | The new capability interfaces will be defined in a new class - ''!FdoICapability'' - that resides in the directory Fdo\Unmanaged\Inc\Fdo\Connections\Capabilities. The following outlines the class definition: |
86 | | FDO_API virtual bool GetBooleanCapability (FdoInt32 capability, bool default ) = 0; |
87 | | FDO_API virtual FdoInt32 GetInt32Capability (FdoInt32 capability, FdoInt32 default ) = 0; |
88 | | FDO_API virtual FdoInt64 GetInt64Capability (FdoInt32 capability, FdoInt64 default ) = 0; |
89 | | FDO_API virtual FdoString *GetStringCapability (FdoInt32 capability, FdoString *default) = 0; |
90 | | FDO_API virtual FdoInt32 *GetArrayCapability (FdoInt32 capability, FdoInt32 &length ) = 0; |
91 | | FDO_API virtual OBJ *GetObjectCapability (FdoInt32 capability ) = 0; |
| 91 | FDO_API virtual bool GetBooleanCapability (FdoInt32 capability, bool &isUnknown) = 0; |
| 92 | FDO_API virtual FdoInt32 GetInt32Capability (FdoInt32 capability, bool &isUnknown) = 0; |
| 93 | FDO_API virtual FdoInt64 GetInt64Capability (FdoInt32 capability, bool &isUnknown) = 0; |
| 94 | FDO_API virtual FdoString *GetStringCapability (FdoInt32 capability, bool &isUnknown) = 0; |
| 95 | FDO_API virtual FdoInt32 *GetArrayCapability (FdoInt32 capability, FdoInt32 &length, bool &isUnknown) = 0; |
| 96 | FDO_API virtual void *GetObjectCapability (FdoInt32 capability, bool &isUnknown) = 0; |
97 | | With the introduction of the class ''FdoICapability'', all other capability classes – ''FdoICommand'', ''FdoIConnection'', ''FdoIExpression'', ''FdoIFilter'', ''FdoIGeometry'', ''FdoIRaster'', ''FdoISchema'', ''FdoITopology'' – become obsolete. This requires a change to the class FdoIConnection that provides access to the capabilities. That class needs a new interface to get the capabilities: |
| 102 | With the introduction of the class ''!FdoICapability'', all other capability classes – ''FdoICommand'', ''FdoIConnection'', ''FdoIExpression'', ''FdoIFilter'', ''FdoIGeometry'', ''FdoIRaster'', ''FdoISchema'', ''FdoITopology'' – including their interfaces become obsolete. There is no immediate plan to depricate those classes and functions but the intend is to do it eventually. Therefore, any application that uses the FDO capability interfaces should use the new interfaces once they become available to minimize later code changes. |
| 103 | |
| 104 | The addition of the class ''!FdoICapability'' as a replacement of all other FDO capability classes requires a change to the class ''!FdoIConnection'' that provides access to the capabilities. That class needs a new interface to get the capabilities: |
124 | | Although the new class ''FdoICapability'' will make the other FDO capability classes obsolete, there is no plan to depricate those classes at this point and applications may still use their interfaces although it is expected that the new FDO capability interfaces would be used instead. |
125 | | |
126 | | The class ''FdoICapability'' has generalized interfaces for all return type categories the current set of capability interfaces return. It is feasable to add capability interfaces for all data types that FDO supports in preparation for additional capabilities that may be added at a later stage using those data types. However, the ones currently listed should cover most, if not all of the cases and hence the addition of interfaces for different FDO types is not planned. |
127 | | |
128 | | The implementation of the new interfaces also requires some error handling in case an interface is called with a capability identifier that is invalid in this case (for example, call interface !GetObjectCapability and pass in a capability identifier that returns a boolean value). The initial concept called for the throwing of an exception but this may be difficult to handle for any application. Therefore, the proposed solution allows the caller to provide a default value that is returned in case the requested capability is not found within the function. The exception to this rule are the interfaces to return pointers which will return a NULL pointer if the request is invalid. |
129 | | |
130 | | The simplification of the capability interfaces also affects code using it. This is especially the case for the new interfaces that return an array of enumerated values or a collection. Because of the generalization, the interfaces have to return a neutral data rather than a specific type as it is the case with the original interfaces. This requires the caller to cast the returned object to the expected type. The following shows an example of the old and new style request for a capability that returns an array of enumerated values. |
| 131 | The class ''FdoICapability'' has generalized interfaces for all return type categories the current set of capability interfaces return. It is feasable to add capability interfaces for all data types that FDO supports in preparation |
| 132 | for additional capabilities that may be added at a later stage using those data types. However, the ones currently listed should cover most, if not all of the cases and hence the addition of interfaces for different FDO types is not |
| 133 | planned. |
| 134 | |
| 135 | The simplification of the capability interfaces also affects code using it. This is especially the case for the new interfaces that return an array of enumerated values or a collection. Because of the generalization, the interfaces |
| 136 | have to return a neutral rather than a specific data type as it is the case with the original interfaces. This requires the caller to cast the returned object to the expected type. The following shows an example of the old and new |
| 137 | style request for a capability that returns an array of enumerated values. |
164 | | System::Boolean GetBooleanCapability (System::Int32 capability, System::Boolean default); |
165 | | System::Int32 GetInt32Capability (System::Int32 capability, System::In32 default); |
166 | | System::Int64 GetInt64Capability (System::Int32 capability, System::Int64 default); |
167 | | System::String *GetStringCapability (System::Int32 capability, System::String *default); |
168 | | System::Int32[] GetArrayCapability (System::Int32 capability); |
169 | | System::Object GetObjectCapability (System::Int32 capability); |
| 174 | System::Boolean GetBooleanCapability (System::Int32 capability, System::Boolean *isUnknown); |
| 175 | System::Int32 GetInt32Capability (System::Int32 capability, System::Boolean *isUnknown); |
| 176 | System::Int64 GetInt64Capability (System::Int32 capability, System::Boolean *isUnknown); |
| 177 | System::String *GetStringCapability (System::Int32 capability, System::Boolean *isUnknown); |
| 178 | System::Int32[] GetArrayCapability (System::Int32 capability, System::Boolean *isUnknown); |
| 179 | System::Object GetObjectCapability (System::Int32 capability, System::Boolean *isUnknown); |
| 428 | ==== Issues ==== |
| 429 | |
| 430 | The introduction of the simplified FDO capability interfaces will result in some usability issues not present in the current implementation because it uses different functions for each of the supported capabilities. This means that the user does not have to know much about the capability he/she is about to use. Instead, the user gets hold of the capability class, finds the corresponding interface and executes it. By doing so, the user is also ensured that a valid value is returned that can be used for further processing in an application. |
| 431 | |
| 432 | With the simplified version of the FDO capability interfaces, this is no longer the case. Because a given interface now serves many capabilities, the user requires some knowledge about the capability before being able to get the value and faces additional challenges as result of a capability interface call: |
| 433 | |
| 434 | * The user has to identify the capability for which the value is to be returned. |
| 435 | * The user has to know the capability's return type in order to select the correct capability interface in the first place. |
| 436 | * The user has to deal with error scenarios previously unknown as for a capability interface the provided capability identifier may be unknown. |
| 437 | |
| 438 | Each of the issues are addressed in more detail next. |
| 439 | |
| 440 | '''''Capability Identification''''' |
| 441 | |
| 442 | To keep the interface generic and reach the objective outlined for this enhancement, the data type for the capability identifier has to be generic as well. Two options to achieve this were discussed in this context: |
| 443 | |
| 444 | * The first option would define the parameter as a string. To identify the capability the user would enter the capability name. |
| 445 | * The second option would define the parameter as a numeric type. To identify the capability the user would enter the numeric representation of the capability. |
| 446 | |
| 447 | Both options in common is the question how a user would know what to provide as the capability identifier. For the first option, the user would have to know a valid name, for the second the numeric representation. It would be possible to define the valid identifiers in FDO. However, because of the objective to be reached with this enhancement this definition would act merely as a kind of documentation than concrete help. For example, if a new capability is to be added, the list may not be updated as otherwise FDO would require a rebuild which would trigger additional rebuilds of providers and applications - something that is to be avoided. Therefore, the list would only represent a snapshot of available capabilities. The same would apply for the documentation of the capabilities in documents (like the User Guide) or help files. |
| 448 | |
| 449 | Despite this, the proposed solution adds an enumeration that contains all the capabilities FDO supports (including the ones proposed in the RFC). As indicated before it is a snapshot of the then available capability set only and by |
| 450 | no means should it be looked at as a complete list. It provides some rudamentary support to the users to identify a capability. |
| 451 | |
| 452 | '''''Interface Selection''''' |
| 453 | |
| 454 | To select the correct FDO capability interface to retrieve the value of a capability, the user has to know the capability's return type. Like with the capability identifier, this is information that requires to be documented somewhere where the user can easily access it. The current intent is to add this information to the description of the enumerations FdoCapabilityTYpe and CapabilityType. An alternative option would have been to split the current enumeration into different enumeration depending on the return value. However, given the usability of those enumerations (see previous section) it is not seen as a necessity to do so. |
| 455 | |
| 456 | '''''Error Handling''''' |
| 457 | |
| 458 | Unlike with the current FDO capability interfaces, with the simplified version, a capability interface may have to indicate to a caller that a provided capability identifier is unknown. A common scenario may be that a new capability is added and not all providers would support it immediately. If the corresponding FDO capability interface was to be invoked with the new capability identifier for a provider that does not yet support it, the interface must be able to indicate this to the caller. As defined in the proposed solution, this aspect has been addressed by using a function parameter (isUnknown) to inform the caller whether or not the provided capability is unknown. If so, the caller has to ignore any value the function may return. |
| 459 | |
| 460 | Alternative options for the error handling were also discussed in this context. Those include: |
| 461 | |
| 462 | * Exception: The function would throw an exception if the provided capability identifier is unknown. |
| 463 | * Predefined Default Value: Each FDO capability interface will have a predefined value being returned if the provided capability is unknown. |
| 464 | * Custom Default Value: In this case the caller supplies the value to be returned if a provided capability identifier is unknown. |
| 465 | |
| 466 | Those options were dismissed for various reasons. Whereas the first option was dismissed because of cost related issues, the two other options were dismissed because it appears impossible to define a value for each of the interfaces |
| 467 | that could be used to reliably indicate that a capability indentifier is unknown. For example, the interface handling capabilities returning a boolean value, can return either true or false, both of which indicate valid responses for a capability. Based on this, a caller receiving such a value cannot distinguish between whether this represents a valid capability value or that the capability is unknown. |
| 468 | |
| 469 | |
452 | | If data store level capabilities are chosen, then the results will reflect any limitations that the data store has around those capabilities. For example, the command capabilities will return a smaller list of supported commands if the datastore is read-only. In this case, commands such as Update will not be returned. Other capabilities, like the threat related capabilities, will remain unchanged from the provider level values. |
453 | | |
454 | | It is anticipated that the most impact of the data store level capabilities will be with the ODBC provider. At the same time, the ODBC provider also represents the biggest unknown as it is not yet known how much data store specific limitations the ODBC provider can determine through the ODBC API. |
| 508 | If data store level capabilities are chosen, then the results will reflect any limitations that the data store has related to the capability. For example, the command capability will return a smaller list of supported commands if the datastore is read-only. In this case, commands such as Update will not be returned. Other capabilities, like the threat related capabilities, will remain unchanged from the provider level values. |
| 509 | |
| 510 | It is anticipated that the most impact of the data store level capabilities will be with the ODBC provider. At the same time, the ODBC provider also represents the biggest risk as it is not yet known how much data store specific |
| 511 | limitations the ODBC provider can determine through the ODBC API. |
464 | | When checking in objects in Map, any arc segments that may be defined with the object’s geometry property will be tessellated if the target provider cannot store arc segments. In general, this decision is made by determining whether or not the arc geometry type is listed as a supported type in the geometry capabilities. |
465 | | |
466 | | The exception to this rule is the Oracle provider. By default, Oracle will support the storage of arc segments unless the current coordinate system is a Lat/Long system in which case arc segments need to be tessellated. The provider specific processing in Map can be eliminated if a capability indicating whether or not arc segments can be stored is added. Such a new capability will be added to the set of geometry capabilities. The function signature is outlined next: |
467 | | |
468 | | '''''bool !SupportsArcSegmentStorage (!FdoString *wktCoordinateSystemName);''''' |
| 522 | An application may tessellate arc segments if a provider cannot handle them. To determine whether or not this is the case, the application can use a geometric capability that returns the list of supported geometry shapes a provider can process. If this information does not include arcs, the tessellation must be executed. The exception to this rule is an Oracle data store. By default, Oracle supports storing arcs unless the current coordinate system is a Lat/Long system. In this case arcs are not supported. FDO does currently not provide any support to handle this case. Therefore, an application would have to implement provider specific processing for it. |
| 523 | |
| 524 | This case will be addressed by a new capability. It allows the user to provide a coordinate system name and returns a boolean flag indicating whether or not arc segments can be stored. In order to do this the new FDO capability interface to return a boolean value must be overwritten with a function that accepts an additional parameter (the coordinate system name). The following outlines the changes to the class ''!FdoICapability''. |
| 525 | |
| 526 | {{{ |
| 527 | |
| 528 | #include <Fdo/Connections/Capabilities/CapabilityType.h> |
| 529 | |
| 530 | class FdoICapability : public FdoIDisposable |
| 531 | { |
| 532 | |
| 533 | public: |
| 534 | |
| 535 | FDO_API virtual bool GetBooleanCapability (FdoInt32 capability, bool &isUnknown) = 0; |
| 536 | FDO_API virtual bool GetBooleanCapability (FdoInt32 capability, FdoString *value, bool &isUnknown) = 0; |
| 537 | |
| 538 | : |
| 539 | |
| 540 | |
| 541 | } // FdoICapability |
| 542 | |
| 543 | }}} |
| 544 | |
| 545 | The change to the class FdoICapability requires a change to the corresponding class ''!ICapability'' in the FDO managed code base: |
| 546 | |
| 547 | |
| 548 | {{{ |
| 549 | |
| 550 | public __gc __interface ICapability : public System::IDisposable |
| 551 | { |
| 552 | |
| 553 | public: |
| 554 | |
| 555 | System::Boolean GetBooleanCapability (System::Int32 capability, System::Boolean *isUnknown); |
| 556 | System::Boolean GetBooleanCapability (System::Int32 capability, System::String *value, System::Boolean *isUnknown); |
| 557 | |
| 558 | : |
| 559 | |
| 560 | } |
| 561 | |
| 562 | }}} |
| 563 | |
| 564 | In addition to those changes the capability identifier ''!FdoCapabilityTYpe_CSSupportsArcs'' will be added to the enumeration ''!FdoCapabilityType'' and the corresponding identifier ''!CapabilityTYpe_CSSupportsArcs'' to the enumeration ''!CapabilityType''. |
485 | | There are two parts to this item: |
486 | | |
487 | | * A new capability - ''!CapabilityType_SupportsMultipleGeometries'' - will be added with which a provider can indicate whether or not it allows the user to defined multiple geometry types for a geometry property. For example, SHP does not allow to store point and line shapes in the same data store; It can only either one of them. |
488 | | * Another change affects the Schema Editor in Autodesk Map 3D. The Schema Editor currently allows the user to pick geometric types in any combination to be assigned with the class geometry property. The geometric types are point, line and polygone and are not fine-grained enough to reflect the different shapes a provider can support. FDO already contains such a fine-grained definition of shape types - the geometry types. The geometry types include ''!FdoGeometryType_Point'', ''!FdoGeometryType_LineString'', ''!FdoGeometryType_Polygon'', ''!FdoGeometryType_MultiPoint'', ''!FdoGeometryType_MultiLineString'', ''!FdoGeometryType_MultiPolygon'', ''!FdoGeometryType_MultiGeometry'', ''!FdoGeometryType_CurveString'', ''!FdoGeometryType_CurvePolygon'', ''!FdoGeometryType_MultiCurveString'' and ''!FdoGeometryType_MultiCurvePolygon''. The Schema Editor will be modified to offer those types rather than the current geometric types for the user to pick from. In addition the Schema Editor will use the new capability introduced with this use case to control the selection process. |
| 579 | Some providers do not allow different shapes to be stored in the same geometry property. For example, if the geometry in a SHP file is set to store points, multi-point shapes are not allowed. Another example would be if the geometry type are lines, point data cannot be stored. |
| 580 | |
| 581 | Currently, a provider cannot indicate whether or not it can handle a combination of different geometry shapes. This issue will be addressed by a new capability. It will return TRUE if multiple geometry types are supported, FALSE otherwise. To address the capability, the identifier ''!FdoCapabilityType_SupportsMultipleGeometries'' will be added to the enumeration ''!FdoCapabilityType'' and ''!CapabilityType_SupportsMultipleGeometries''to the enumeration |
| 582 | ''!CapabilityType''. |