Proposal 3.0: OGDI Versioning

Author: Frank Warmerdam, 3i, warmerdam@pobox.com
Proposed: 2000/11/20
Last Edited: 2001/01/03
Status: Widthdrawn

Summary

A methdology to keep track of OGDI specification version supported, and extensions supported is introduced via the UpdateDictionary() calls.

Objective

To establish a standard mechanism for OGDI clients to identify the version of the OGDI specification supported by a server (driver), and to identify standard, and non-standard extensions supported by the server.

Approach

The cln_UpdateDictionary() call will be used to fetch one of two documents, one describing the version of the server, and one containing a list of extensions. The documents are returned as flat text with a defined format.

Version

The version is a textual representation of a numerical version number.

Each legal version number will be defined by the 3i, with an associated specification document indicating the requirements for claiming to support that version.

Version numbers will be decimal values (such as "3.0", "3.1"), where a higher version number always implies that all capabilities of previous versions are supported. (This may be violated when the major version changes, for instance a switch from 3.x to 4.x). The version numbers will always be numerically comparable, so 3.10 is really just 3.1. If we want to have minor versions after 3.9 we might number them 3.91 rather than 3.10.

The version is fetched by passing the string "ogdi_version" to the cln_UpdateDictionary() call.

If the returned document does not match the regular expression "[0-9]+.[0-9]+" then the returned value should not be treated as a version. This is to ensure that pre 3.0 servers which return something from cln_UpdateDictionary() regardless of the argument are still handled properly.

Extensions

The extensions supported by a server are returned as a textual document. The document contains a list of extension identifiers separated by a single space. The presence of the extension identifier indicates that this server (at least for the current datastore) supports the indicated extensions.

The extension identifiers will conform to the following restrictions:

Identifiers only contain the characters a-z, 0-9, '_', '-', '.'. Note only lower case to avoid case sensitivity issues.
Identifiers may only have the prefix "ogdi_" if issued by the 3i as standard predefined extensions.
Other vendors may create their own extension identifiers. To guarantee no collisions, vendors may prefix the extension with a DNS domain they control in reversed order. For instance "com.cubewerx.". Vendors will avoid using a prefix that is currently, or could ever be, a valid DNS domain. -

A possible example return result might be:

"ogdi_unique_object_id com.globalgeo.resync"

The extensions will be fetched via the cln_UpdateDictionary() call with an argument of "ogdi_extensions".

Alternate Approach

Essentially the same information is returned, still via cln_UpdateDictionary() but the version and extensions information are merged into one document, and the document is in XML format. If this approach is desired I can prepare a simple DTD and examples descibing the format. A potential example might be:

API Extensions While not strictly necessary, I would also suggest the OGDI reference API be extended for the convenience of application programmers. It would:

Cache version and extension information in the ecs_Client structure.
Provide a cln_GetVersion() function to return the version as a double.
Provide a cln_CheckExtension(const char *) call to return TRUE or FALSE indicating if a given extension is supported.

Compatibility Issues

Servers not returning a valid version to a cln_UpdateDictionary("ogdi_version") request should be presumed to be pre-versioning servers, and thus would also not generally support the cln_UpdateDictionary("ogdi_extensions") call.

We need to define what our initial version number is. I would suggest we call the old core people have been using for a couple of years 3.0, and define the "ogdi_version", and "ogdi_extensions" protocol as part of a "3.1" specification.

Because we use cln_UpdateDictionary() to transport the information, we aren't requiring any changes to the GLTP protocol, nor necessary changes to the OGDI API. This should mean that drivers, and clients can be easily upgraded with minor changes, and not requiring incorporation of any actual source code from 3i.

Final Thoughts

Even if we choose to use the CubeWerx "GetCapabilities" approach, and want to incorporate version and extension information in that returned document, I would suggest that we still try to utilize similar semantics to those in this proposal.

In general, I also feel that we should use the cln_UpdateDictionary() call as a mechanism to transport assorted metadata back from servers, with special argument values having assorted semantics. Furthermore, I suggest that values prefixed with "ogdi_" be reserved for standardization by the 3i.