FDO RFC 20 - Enhanced Capabilities Support

This page contains an change request (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	April 30, 2008
Last Modified	Jack Lee Timestamp
Author	Greg Boone
RFC Status	Draft
Implementation Status	Pending
Proposed Milestone	3.4.0.0
Assigned PSC guide(s)	Greg Boone
Voting History	(vote date)
+1
+0
-0
-1

Motivation

The objective of this RFC is to propose enhancements to the capability interfaces of the FDO API in order that applications are able to eliminate all special case handling of FDO provider capabilities. It will be necessary to gather feedback from applications such as OSGeo MapGuide OpenSource and Autodesk Map 3D to determine that we have a complete set of capabilities implemented in the FDO API and that all special casing can be eliminated with the proposed changes outlined in this RFC.

It is also necessary to introduce a previously discussed concept of DataStore level capabilities. DataStore capabilities are a necessity in the FDO API due to the fact that certain providers can only communicate certain capabilities that are DataStore specific after a fully formed connection to the provider has been established. There are cases where a provider may support a certain capability, e.g. write or long transactions, whereas a particular DataStore for the current connection has limitations. E.g. it may be read only, or it may not support long transactions. Currently, there is no way for a client application to determine these DataStore specific restrictions except for a few specific cases around class level capabilities.

Finally to simplify capability handling as the FDO API evolves, we will evaluate the possibilities of introducing an API change that would see the FDO API use constants to identify capabilities supported by its providers. This will make it easier to add new capabilities without changing the API every time a need arises to add a new capability.

Scenarios

Here are some areas where the current level of DataStore agnostic capabilities are insufficient.

• The ODBC provider can connect to different sources from Excel files to Access databases to various RDBMS’. However, the capabilities of each source are somewhat different.
• The Oracle provider can connect to different Oracle versions. With the introduction of Oracle XE there is the case of an Oracle datastore that does not support long transaction versioning or persistent locking.
• Some providers restrict the type of geometry in a geometry property to a specific type rather than category of types. SHP is a good example of this. The provider may advertise that the geometry can be linear, which implies polyline, multi-polyline, etc. However, when the user enters a multi-polyline geometry, an exception is thrown that it cannot be written. A more fine grained specification of allowed geometry types will avoid these situations.

DataStore Capability Support

Unmanaged

The change to support both provider and datastore level capabilities is done by adding an overloaded function to each of the top-level FdoIConnection capability functions. The overloaded function will have a datastoreLevel parameter to specify whether the capabilities are for the provider or for the currently connected datastore. Since the existing function will not be removed, there will be two ways to retrieve the provider capabilites.

This could be an enum rather than a boolean, although I can’t think of any options that we could add to the enum in the future past these two.

Managed

The existing managed API to retrieve the capabilities is defined as a property. The change to support both provider and datastore level capabilities is done by adding a new function to each of the top-level IConnection capability functions. The new functions will have a datastoreLevel parameter to specify whether the capabilities are for the provider or for the currently connected datastore. Since the existing property will not be removed, there will be two ways to retrieve the provider capabilites.

The table below specifies the changes to the above functions.

New FdoIConnection/IConnection Functions

Unmanaged

virtual FdoICommandCapabilities * 	GetCommandCapabilities (bool datastoreLevel) = 0
virtual FdoIConnectionCapabilities * 	GetConnectionCapabilities (bool datastoreLevel) = 0
virtual FdoIExpressionCapabilities * 	GetExpressionCapabilities (bool datastoreLevel) = 0
virtual FdoIFilterCapabilities * 	GetFilterCapabilities (bool datastoreLevel) = 0
virtual FdoIGeometryCapabilities * 	GetGeometryCapabilities (bool datastoreLevel) = 0
virtual FdoIRasterCapabilities * 	GetRasterCapabilities (bool datastoreLevel) = 0
virtual FdoISchemaCapabilities * 	GetSchemaCapabilities (bool datastoreLevel) = 0
virtual FdoITopologyCapabilities *      GetTopologyCapabilities (bool datastoreLevel) = 0

Managed

__property NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::ICommandCapabilities* GetCommandCapabilities(System::Boolean datastoreLevel);
__property NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::IConnectionCapabilities* GetConnectionCapabilities(System::Boolean datastoreLevel);
__property NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::IExpressionCapabilities* GetExpressionCapabilities(System::Boolean datastoreLevel);
__property NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::IFilterCapabilities* GetFilterCapabilities(System::Boolean datastoreLevel);
__property NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::IGeometryCapabilities* GetGeometryCapabilities(System::Boolean datastoreLevel);
__property NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::IRasterCapabilities* GetRasterCapabilities(System::Boolean datastoreLevel);
__property NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::ISchemaCapabilities* GetSchemaCapabilities(System::Boolean datastoreLevel);
__property NAMESPACE_OSGEO_FDO_CONNECTIONS_CAPABILITIES::ITopologyCapabilities* GetTopologyCapabilities(System::Boolean datastoreLevel);

If datastore level capabilities are chosen, then the results will reflect any limitations that the datastore has around those capabilities. Command capabilities will return a smaller list of supported commands for example if the datastore is read-only. In this case, commands such as Update will not be returned.

Datastore level capabilities would only be available after connecting to a datastore. Requesting datastore level capabilities before a successful connection will result in an exception.

Some capabilities such as thread capability would not be different between provider level and datastore level.

Impact of DataStore Level Capabilities on the Above Capability Sets

Command Capabilities

• The set of supported commands for a datastore could be less than for the general provider. A provider may support long transaction commands, but a particular datastore may not support them.

Connection Capabilities

• Of the connection capabilities, locking and long transactions are ones that typically could be different.

Expression Capabilities

• The expression types supported typically would not change, although the list of supported functions could be different, e.g. ODBC sources could have different sets of supported functions.

Filter Capabilities

• As with expressions, these typically would not change, although there could be cases where spatial filters could be more limited.

Geometry Capabilities

• At this time, this capability would not change for a datastore. However, in the future, different ODBC source could have different capabilities here (currently only point geometry is supported for all ODBC sources), or more advanced geometries may be available with future versions of the Oracle server where the Oracle provider can connect to different Oracle versions.

Raster Capabilities

• Different sources could support different data models.

Schema Capabilities

• At the datastore level, different sources could have different limitations, e.g. different versions of Oracle server or SQL Server, or different ODBC sources.

Issues

How much datastore specific limitations can the ODBC provider determine through the ODBC API? Is it capable enough to support the additional schema capabilities specified in this document? Not all odbc providers support all the ODBC capabilities to determine schema information.

Test Plan

Existing unit tests will be enhanced to test all changes.

Funding/Resources

Autodesk to provide resource / funding to implement the feature for the affected providers.