= 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||Maggie Yang [[Timestamp]]||
||Author||Maggie Yang||
||RFC Status|| Accepted ||
||Implementation Status||Under Development ||
||Proposed Milestone||3.3.0.0||
||Assigned PSC guide(s)||Greg Boone||
||'''Voting History'''||August 2, 2007||
||+1||Greg, Orest, Bob, Harris, Frank, Jason||
||+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 fromat 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 fromats, styles and CRS infromation 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.

Unmanaged API:
{{{
// 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 GetImagefromats command.
    FdoWmsCommandType_GetImagefromats =  FdoCommandType_FirstProviderCommand + WMS_FIRST_PROVIDER_COMMAND,
    /// Represents the GetFeatureClassStyles command.
    FdoWmsCommandType_GetFeatureClassStyles,
    /// Represents the GetFeatureClassCRSNames command.
    FdoWmsCommandType_GetFeatureClassCRSNames
};
}}}

Managed API
{{{
// This number is defined so our custom command would not clash with other
// custom provider commands.
#define WMS_FIRST_PROVIDER_COMMAND 1800

BEGIN_NAMESPACE_OSGEO_FDO_PROVIDERS_WMS

/// <summary>The WmsCommandType enumeration defines the list of WMS Provider specific commands.</summary>
/// <param name="WmsCommandType_GetImagefromats">Represents the GetImagefromats command.</param>  
/// <param name="WmsCommandType_GetFeatureClassStyles">Represents the GetFeatureClassStyles command.</param> 
/// <param name="WmsCommandType_GetFeatureClassCRSNames">Represents the GetFeatureClassCRSNames command.</param> 
public __value enum CommandType {

    WmsCommandType_GetImagefromats =  NAMESPACE_OSGEO_FDO_COMMANDS::CommandType::CommandType_FirstProviderCommand +  WMS_FIRST_PROVIDER_COMMAND,
    WmsCommandType_GetFeatureClassStyles,
    WmsCommandType_GetFeatureClassCRSNames
};

END_NAMESPACE_OSGEO_FDO_PROVIDERS_WMS
}}}

3 new commands will be added to the FDO WMS Provider specification, allowing an application to request image fromat, style and CRS name infromation. These commands will only 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 fromats Command ===
Unmanaged API:
{{{
class FdoWmsIGetImagefromats: public FdoICommand
{
public:
    /// \brief
    /// Executes the GetImagefromats command and returns a FdoStringCollection
    /// which contains all the image fromats supported by the current WMS service.
    /// 
    /// \return
    /// Returns the image fromat collection supported by WMS service
    /// 
    FDO_API virtual FdoStringCollection * Execute() = 0;
};

}}}

Managed API
{{{
BEGIN_NAMESPACE_OSGEO_FDO_PROVIDERS_WMS

///<summary>
/// This command get all supported image fromats from a specified WMS service
///</summary>
public __gc __interface IGetImagefromats : public NAMESPACE_OSGEO_FDO_COMMANDS::ICommand
{
public:
    ///<summary>
    /// Executes the command. 
    ///</summary>
    /// <returns>Returns image fromats collection supportted by WMS service.</returns>
    NAMESPACE_OSGEO_COMMON::StringCollection* Execute();
};

END_NAMESPACE_OSGEO_FDO_PROVIDERS_WMS
}}}

=== 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.''

Unmanaged 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;
};

}}}

Managed API
{{{
BEGIN_NAMESPACE_OSGEO_FDO_PROVIDERS_WMS

///<summary>
/// This command get the styles collection supportted by specific FeatureClass
/// from WMS service.
///</summary>
public __gc __interface IGetFeatureClassStyles : public NAMESPACE_OSGEO_FDO_COMMANDS::ICommand
{
public:
    /// <summary>Sets the name of the FeatureClass in WMS service.
    /// This function is mandatory; if not specified, 
    /// execution of the command will throw exception. 
    /// </summary>
    /// <param name="name">The FeatureClass name.</param>
    /// <returns>Returns nothing.</returns> 
    __property System::Void set_FeatureClassName(System::String* name);

    /// <summary>Gets the name of FeatureClass to retrieve all supported styles.
    /// </summary>
    /// <returns>Returns the name of the FeatureClass name.</returns> 
    __property System::String* get_FeatureClassName();

    /// <summary>
    /// Executes the command. An exception is thrown if the feature class is NULL.
    /// </summary>
    /// <returns>
    /// Return a StringCollection which contains all styles supported by specific feature class
    /// and all styles supported by its ancestors. WMS services support Style 
    /// declarations inherited by child Layers. 
    /// </returns>
    NAMESPACE_OSGEO_COMMON::StringCollection* Execute();
};

END_NAMESPACE_OSGEO_FDO_PROVIDERS_WMS
}}}

=== 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.''

Unmanaged API
{{{
class FdoWmsIGetFeatureClassCRSNames: public FdoICommand
{
public:
    /// \brief
    /// Gets the name of the FeatureClass to retrieve 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;
};

}}}

Managed API
{{{
BEGIN_NAMESPACE_OSGEO_FDO_PROVIDERS_WMS

///<summary>
/// This command get the CRS names collection supported by specified FeatureClass
/// from WMS service.
///</summary>
public __gc __interface IGetFeatureClassCRSNames : public NAMESPACE_OSGEO_FDO_COMMANDS::ICommand
{
public:
    /// <summary>Sets the name of the FeatureClass in WMS service.
    /// This function is mandatory; if not specified, 
    /// execution of the command will throw exception. 
    /// </summary>
    /// <param name="name">The FeatureClass name.</param>
    /// <returns>Returns nothing.</returns> 
    __property System::Void set_FeatureClassName(System::String* name);

    /// <summary>Gets the name of FeatureClass to retrieve all supported CRS names.
    /// </summary>
    /// <returns>Returns the name of the FeatureClass name.</returns> 
    __property System::String* get_FeatureClassName();

    /// <summary>
    /// Executes the command. An exception is thrown if the feature class is NULL.
    /// </summary>
    /// <returns>
    /// Returns an StringCollection which contains all the CRS names supported by specific feature class.
    /// and all CRS names supported by its ancestors. WMS services supports CRS
    /// declarations inherited by child Layers.
    /// </returns>
    NAMESPACE_OSGEO_COMMON::StringCollection* Execute();
};

END_NAMESPACE_OSGEO_FDO_PROVIDERS_WMS

}}}

== 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.