= FDO RFC 6 - Enhance WMS Command API =

This page contains a request for comments document (RFC) for the FDO Open Source project.  
More FDO RFCs can be found on the [wiki:FDORfcs RFCs] page.

== Status == 
 
||RFC Template Version||1.0|| 
||Submission Date||Jul 20, 2007 ||
||Last Modified||Greg Boone [[Timestamp]]||
||Author||Maggie Yang||
||RFC Status||Draft||
||Implementation Status||Under Development ||
||Proposed Milestone||3.3.0.0||
||Assigned PSC guide(s)||Greg Boone||
||'''Voting History'''||TBD||
||+1|| ||
||+0|| ||
||-0|| ||
||-1|| ||
 
== Overview ==

In the current design of the OSGeo FDO WMS Provider, no mechanism exists to allow a client to retrieve the supported CRS and Style names supported by specific WMS layer. In addition, no mechanism exists to allow an application to retrieve all the image format types supported by a WMS service.

In order to resolve this oversight, the OSGeo WMS provider will be enhanced to provide an application with the ability to use the FDO command invocation system to retrieve the supported image formats, styles and CRS information from the WMS service.

== Proposed Solution ==

In order not to impact the existing FDO command interface, the three new command interface will be designated as WMS specific and be implemented only by the WMS provider. In order to facilitate the implemntation, a new enum type, !FdoWmsCommandType, will be defined for the OSGeo WMS provider.

The following section defines the WMS command enumerations.
{{{
// This number is defined so our custom command would not clash with other
// custom provider commands.
#define WMS_FIRST_PROVIDER_COMMAND 1800

/// \brief
/// The FdoWmsCommandType enumeration defines the list of WMS Provider specific commands.
enum FdoWmsCommandType{

    /// Represents the GetImageFormats command.
    FdoWmsCommandType_GetImageFormats =  FdoCommandType_FirstProviderCommand + WMS_FIRST_PROVIDER_COMMAND,
    FdoWmsCommandType_GetFeatureClassStyles,
    FdoWmsCommandType_GetFeatureClassCRSNames
};
}}}

3 new commands will be added to the FDO WMS Provider specification, allowing an application to request image format, style and CRS name information. These commands willonly be able to be invoked once a connection has successfully been made to the WMS provider and in turn to the specified WMS service.

=== Get Image Formats Command ===

{{{
class FdoWmsIGetImageFormats: public FdoICommand
{
public:
    /// \brief
    /// Executes the GetImageFormats command and returns a FdoStringCollection
    /// which contains all the image formats supported by the current WMS service.
    /// 
    /// \return
    /// Returns the image format collection supported by WMS service
    /// 
    FDO_API virtual FdoStringCollection * Execute() = 0;
};

}}}

=== Get Styles Command ===

''NOTE: A !FeatureClass is an FDO concept. One feature class corresponds to one layer name in the originating WMS service. We use feature class, instead of layer here, in order to remain consistant with the feature concepts defined in the FDO API.''

{{{
class FdoWmsIGetFeatureClassStyles : public FdoICommand
{
public:
    /// \brief
    /// Gets the name of the feature class from which to retrieve all supported styles. 
    /// 
    /// \return
    /// Returns the feature class name
    /// 
    FDO_API virtual FdoString* GetFeatureClassName() = 0;

    /// \brief
    /// Sets the name of the feature class from which to retrieve all supported styles.
    /// Invocation of this function is mandatory; if not specified, execution of the 
    /// command will throw an exception. 
    ///
    /// \param value 
    /// Input the feature class name
    /// 
    /// \return
    /// Returns nothing
    /// 
    FDO_API virtual void SetFeatureClassName(FdoString* value) = 0;

    /// \brief
    /// Executes the GetFeatureClassStyles command and returns a FdoStringCollection
    /// which contains all styles supported by specified feature class
    /// and all styles supported by its ancestors. WMS services support Style 
    /// declarations inherited by child Layers. 
    /// 
    /// \return
    /// Returns the styles collection supported by specific feature class
    /// 
    FDO_API virtual FdoStringCollection * Execute() = 0;
};

}}}

=== Get CRS Names Command ===

''NOTE: A !FeatureClass is an FDO concept. One feature class corresponds to one layer name in the originating WMS service. We use feature class, instead of layer here, in order to remain consistant with the feature concepts defined in the FDO API.''

{{{
class FdoWmsIGetFeatureClassCRSNames: public FdoICommand
{
public:
    /// \brief
    /// Gets the name of the FeatureClass to get all supported CRS names. 
    /// 
    /// \return
    /// Returns the FeatureClass name
    /// 
    FDO_API virtual FdoString* GetFeatureClassName() = 0;

    /// \brief
    /// Sets the name of the FeatureClass for which to retrived all supported CRS names.
    /// Invocation of this function is mandatory; if not specified, execution of the 
    /// command will throw an exception. 
    ///
    /// \param value 
    /// Input the FeatureClass name
    /// 
    /// \return
    /// Returns nothing
    /// 
    FDO_API virtual void SetFeatureClassName(FdoString* value) = 0;

    /// \brief
    /// Executes the GetCRSNames command and returns an FdoStringCollection
    /// which contains all the CRS names supported by specified feature class.
    /// and all CRS names supported by its ancestors. WMS services supports CRS
    /// declarations inherited by child Layers. 
    /// 
    /// \return
    /// Returns the CRS name collection supported by the specific feature class.
    /// 
    FDO_API virtual FdoStringCollection * Execute() = 0;
};

}}}

== Implications ==

This change will not cause any side-effects, nor any compatibility problems.

== Test Plan ==

Existing unit tests will be expanded to test the proposed enhancements defined above. 

== Funding/Resources ==

Autodesk to provide resources / funding to update the WMS provider.