FDO Enhanced Version Support

Introduction

This document contains a design for some software and file version handling strategies for FDO. The versions dealt by this document are:

• Version of FDO software
  
• FDO provider versions
  
• XML configuration file versions
  

In FDO 3.0, a number of issues arose regarding the handling of these versions. There were a number of concerns as to how these versions should be handled going forward. The main purpose of this design is to resolve these issues so that customers and client applications can easily upgrade to new FDO software releases as they become available.

Requirements

FDO and Provider Versions

The main requirement is to ensure that, when a client asks FDO to load a particular provider, the version that is loaded is compatible with the current FDO.

When client stores connection information, it typically includes the provider name. This name is tied to a particular provider version. However, this is problematic if the next major revision of the client software loads the provider for a particular connection, using the provider name stored in the client specific file.

The above would attempt to retrieve the 3.0 version of the provider, which is likely binary incompatible with the next major revision of the client, which would be compatible with FDO 4.0. This can be worked around, by changing the version part of the provider name from 3.0 to 4.0, before requesting to load it. However, it would be good to streamline this so that FDO clients do not have to keep track of what all the current provider versions are.

In FDO 3.1, work was done to address this by allowing clients to omit the version parts of the provider name when requesting to load it. In this case, the latest registered version of the provider is retrieved. However, there is no guarantee that this version of the provider is binary-compatible with the current version of FDO.

FDO consists of a number of core libraries (e.g. Fdo.dll, FdoCommon.dll, etc ) plus a number of providers. Each provider handles a different type of data. The list of providers is extensible (customers can write their own). Each provider must be registered in the provider registry, in order for the FDO core to be able to find it. The provider registry can contain multiple versions of the same provider.

Clients load providers via the FDO Feature Access Manager (FAM). The client supplies the provider name and the FAM finds the provider in the registry. The provider name can contain the name parts plus optional version number (e.g. "OSGeo.SDF" (no version), "OSGeo.SDF.3" (name plus major version), "OSGeo.SDF.3.1" (name plus major and minor version)).

Currently, the FAM retrieves the latest registered version of the requested provider. For example, if the registry contains the following providers:

OSGeo.SDF.3.0
OSGeo.SDF.3.1
OSGeo.SDF.3.2
OSGeo.SDF.4.0
OSGeo.SDF.5.0

the following table shows which provider is returned by the FAM, depending on the requested name.

Client requested -------- FAM returns

OSGeo.SDF ------------- OSGeo.SDF.5.0
OSGeo.SDF.3 ----------- OSGeo.SDF.3.2
OSGeo.SDF.4 ----------- OSGeo.SDF.4.0
OSGeo.SDF.3.1 --------- OSGeo.SDF.3.1

The client decides how precise the search is by how many version parts are included in the requested provider name.

In the above example, "OSGeo.SDF.5.0" is returned when "OSGeo.SDF" is requested. However, suppose that this provider is compatible with FDO version 5.0 and the version of FDO, used by the client, is 4.0. When there is a major version number difference then there is a good chance that the provider is binary incompatible with FDO, meaning that a crash or exception will occur when the provider is loaded.

Config File Versions

FDO provides the ability to serialize datastore contents to the FDO XML format. This includes feature schemas, spatial contexts, logical/physical mappings (Schema Overrides) and the features themselves. FDO XML format data can be stored in a file. The FDO XML format can change between major FDO revisions so there are versioning issues surrounding these files. These are mainly compatibility issues that arise when a file is written by one version of FDO and read by another.

In order for a particular version of FDO to determine if it can read a file, it needs to know what version of FDO created the file. Therefore, the file must contain this version information. The following sections discuss the versioning requirements for each type of serializable object.

Feature Schemas

Feature Schemas are currently written to XML without FDO version information. This version information needs to be added, going forward, in case the XML format for Feature Schemas changes in future. When a particular version of FDO reads a feature schema from a config file, it may need to know this version in order to read it properly.

Spatial Contexts

Similarly, Spatial Contexts are written to XML without FDO version information. This version information need to be added, going forward.

Schema Overrides

Schema Overrides are written to XML with FDO versioning information. The overrides include the name, major version and minor version of the provider that wrote them.

The main requirement is to make sure that, when Schema Overrides are read from XML, they are parsed into objects that are binary compatible with the current FDO.

When FDO reads a Schema Override Set from XML, it delegates the reading to the provider that wrote the overrides. Schema Overrides are provider-specific, so only the provider knows how to read or write them. Currently, FDO chooses the earliest version of the provider that is equal to or greater than the version of the Schema Override set. However, it is possible for the chosen provider to be binary-incompatible with the current FDO. This means that the provider may either fail to be instantiated or it may parse the Schema Overrides into objects not compatible with the current FDO.

Features

Features are written to XML without FDO version information. This version information needs to be added, going forward.

Feature Specification

The following describes the client-visible changes proposed by this design.

FDO API

FdoFeatureAccessManager::GetFeatureDataObjectsVersion

When this function is called it will return the version of the feature data objects specification that the currently loaded Feature Access Manager supports. The version number string has the form [VersionMajor].[VersionMinor].[BuildMajor].[BuildMinor].

The function signature shall be:

    FDO_API static FdoString* GetFeatureDataObjectsVersion();

FdoConnectionManager::CreateConnection()

When this function is passed a provider name without version part (e.g. "OSGeo.SDF" ), it returns a connection object from the latest registered version of that provider.

With this proposal, the provider chosen will be the provider with the latest binary-compatible FeatureDataObjects version.

The connection object will be instantiated from the chosen provider. If there is no compatible registered provider then CreateConnection will return NULL.

For the above provider searches, the provider's FeatureDataObjects version will be used instead of the provider version itself. The reason for this is that the FeatureDataObjects version is the one that corresponds to the version of the FDO core.

The provider search behaviour is unchanged when the requested provider name contains version parts. In this case, the latest provider matching these version parts is chosen. However, in these cases, the client assumes the risk that the returned connection object may be incompatible with the current FDO.

It is expected that most clients will pass in a provider name without version parts, since they would usually be interested in retrieving a binary-compatible version of the requested provider.

A provider is considered to be binary-compatible with the current FDO if the specified parts of the provider's FeatureDataObjectsVersion match those of the current version of FDO. For example, if the FeatureDataObjectsVersion has 2 parts, then these must match the 1st 2 parts of the current FDO's version. The following table provides some concrete examples:

Provider FeatureDataObjectsVersion

3

Compatible versions of FDO core

3.0.0.0
3.1.0.0
3.2.0.1

Incompatible FDO versions

2.0.0.0
4.0.0.0
4.1.0.0

Provider FeatureDataObjectsVersion

3.0

Compatible versions of FDO core

3.0.0.0
3.0.1.0

Incompatible FDO versions

2.0.0.0
3.1.0.0
3.2.0.0

Provider FeatureDataObjectsVersion

3.2

Compatible versions of FDO core

3.2.0.0
3.2.1.0

Incompatible FDO versions

3.1.0.0
3.1.1.0
3.3.0.0

Provider FeatureDataObjectsVersion

3.1.0.1

Compatible versions of FDO core

3.1.0.1

Incompatible FDO versions

3.1.0.0
3.1.0.2
3.1.2

The 4th example is for illustration and would not likely happen in the real world. It is unlikely that versions as similar as 3.1.0.1 and 3.1.0.2 would be incompatible.

FdoProviderNameTokens

This class will be modified to support the removing of version parts from a provider name.

ToString (new)

This function converts this tokenize provider name back to a string:

GisStringP FdoProviderNameTokens::ToString( bool includeVersion = true )

When includeVersion is true, the full provider name is returned. When includeVersion is false, the version parts are omitted from the returned name.

For Example, the following removes the version parts from a provider name:

FdoStringP srcName = L"OSGeo.SDF.3.1";
FdoStringP destName;
FdoProviderNameTokensP tokens = FdoProviderNameTokens::Create( srcName );
destName = tokens->ToString( false );
assert ( destName == L"OSGeo.SDF" );