Changes between Version 1 and Version 2 of FdoEnhancedVersionSupport

Timestamp:

10/18/07 09:14:40 (17 years ago)

Author:

gregboone

Comment:

--

FdoEnhancedVersionSupport

@@ -45 +45 @@
 OSGeo.SDF.3.1 --------- OSGeo.SDF.3.1[[br]]
 
+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[[br]]
+3.1.0.0[[br]] 
+3.2.0.1[[br]]
+
+''Incompatible FDO versions''
+
+2.0.0.0[[br]]
+4.0.0.0[[br]]
+4.1.0.0[[br]]
+
+'''Provider !FeatureDataObjectsVersion'''
+
+3.0
+
+''Compatible versions of FDO core'' 
+
+3.0.0.0[[br]]
+3.0.1.0[[br]] 
+
+''Incompatible FDO versions''
+
+2.0.0.0[[br]]
+3.1.0.0[[br]]
+3.2.0.0[[br]]
+
+'''Provider !FeatureDataObjectsVersion'''
+
+3.2 
+
+''Compatible versions of FDO core'' 
+
+3.2.0.0[[br]]
+3.2.1.0[[br]]
+
+''Incompatible FDO versions''
+
+3.1.0.0[[br]]
+3.1.1.0[[br]]
+3.3.0.0[[br]]
+
+'''Provider !FeatureDataObjectsVersion'''
+
+3.1.0.1 
+
+''Compatible versions of FDO core'' 
+
+3.1.0.1 
+
+''Incompatible FDO versions''
+
+3.1.0.0[[br]]
+3.1.0.2[[br]]
+3.1.2[[br]]
+
+