= FDO Client Utilities =

There has been some discussion recently about client-side utilities for FDO access. For instance, there was a discussion around the use of coordinate system transformation libraries, whether we should be included that in FDO itself or whether they should be included in a client-side utility package. This came out of an email discussion of handling of geometry length and area functions.

There also has been discussion around ways to level the capabilities of providers by making adding client-side additions that implement capabilities that are missing from providers that are being used. Haris expressed interest in this sort of direction.

This page is meant to let everyone add their thoughts around these topics. Some initial information is included to prime the pump. Please add your thoughts and ideas.

Where can added functionality be included? Here are three general approaches.

 1. Client-side library that callers of FDO can use for further processing. E.g. projection.

 2. Client-side wrapper around FDO that has client-side added functionality. E.g. caching, joined / extended classes, projection.

 3. Functions that can be used by provider writers. E.g. expression evaluation. Providers can incorporate added functionality by reusing common components.

 4. The !MapGuide Platform API

The three options are fairly different in terms of what typically would be supported by each, but there is some potential overlap. Projection support is one that could be added via any of these mechanisms.
  
[[BR]][[BR]]
== 1. Client-side library. ==

A separate library makes sense for utility tools that are not part of provider access themselves, but that are frequently used together with data access. This can include:

 * Coordinate projection.
 * Geometry and Raster tools.
 * Translation tools for external formats.

A client-side utility library can be used in a more distributed application where the actual FDO providers are in a different tier.

Pros:
 * Flexibility and generality in the functionality that can be provided.
 * Can be on a separate tier from the actual FDO access.
 * Independent of any providers.

Cons:
 * Separate functions that need to be called outside of FDO access. E.g. for projection support, would have to make separate function calls to project data rather than having them automatically projected in the correct direction if they were part of the FDO API.
  
[[BR]][[BR]]
== 2. Client-side FDO wrapper. ==

This is a wrapper around the FDO API that the user calls instead of calling the provider FDO interface. Is the API for this wrapper the FDO api itself or is it a different API? For instance, the current Feature Services API is a wrapper around FDO but is a different API.

Some functions may not make sense putting inside providers such as client-side caching. One category of functions in a wrapper would be to augment functionality that a particular provider does not support. E.g. a wrapper may perform a select aggregate operation for a provider that does not implement that command.

Another category is functionality that builds on information outside of a provider’s data such as client-side joins between data stores. (Should be part of a wrapper or part of a utility library?)

Pros:
 * Client applications don’t need to change very much to take advantage of this (if we use the FDO API for the wrapper).
 * Added functionality becomes almost transparent.

Cons:
 * Possible duplication what is available in the Platform Feature Services API.
 * Duplicating the whole FDO interface – it’s almost another provider.
 * Some things in a client-side utility library could not be added to an FDO wrapper without additions to the current set of FDO interfaces. An example of this is projection support.

An FDO wrapper layer could only be used in the same tier as the actual providers since that layer would be calling FDO directly. Why wouldn’t we just extend the existing platform Feature Services API instead of doing this? Possible reasons:

 * De-coupling from platform resource services requirements.
 * Deploy outside of MapGuide.
 * Adding capabilities not in the feature services interface, such as being able to control transactions (implies a stateful connection).
  
[[BR]][[BR]]
== 3. Functions that can be used by provider writers. ==

This is not quite the same as the first two options as it doesn't specifically add new capabilities outside what is available in providers, but helps provider writers add more capabilities to their providers.

A good example of this is an expression engine that a provider writer can call from within the provider that they write. The current SDF and SHP providers internally use an expression engine. Providers based on RDBMS servers don’t need to use this as the native server provides that functionality.

Pros:
 * Easier for provider writers. They can reuse code.
 * Consistent behavior between providers.

Cons:
 * Shared functions have to be written in a very generic way.

== 4. The !MapGuide Platform API ==

A combination of 1) and 2) already exists, in the form of the !MapGuide Platform API.

The !MapGuide Platform API already exposes most of what the FDO API has to offer, and provides the additional services/capabilities desired in a client layer:
 * Coordinate System Transformation (offered by !MgCoordinateSystem API)
 * Built-in support for joins (offered by !GwsQueryEngine)
 * Pluggable rendering/stylization

Pros:
 * Offers an already rich and solid foundation.
 * All the pros of 1) and 2)
 * !MapGuide Developers can already leverage such an API

Cons:
 * Currently bound to the !MapGuide Server/Web tiers. A [http://trac.osgeo.org/mapguide/wiki/Future/DesktopSdk desktop-based] implementation is required.