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 RFCs page.

Status

RFC Template Version	1.0
Submission Date	Jul 20, 2007
Last Modified	Maggie Yang Timestamp
Author	Maggie Yang
RFC Status	draft
Implementation Status	under development
Proposed Milestone	TBD
Assigned PSC guide(s)	TBD
Voting History	TBD
+1
+0
-0
-1

Overview

In the current design of the OSGeo OGC FDO WMS Provider(s), no mechanism exists to allow a client to retrieve all supported CRS/style names supported by specific WMS layer, neither for image format types supported by WMS service.

In order to resolve this issue, the WMS providers should be enhanced to add 3 new commands for retrieving all supported image format, style and CS information from WMS service individually.

Proposed Solution

In order not to impact the standard FDO command interface, we plan just adding those 3 commands interface for WMS only. Thus, we also declare a new enum type: WmsCommandType for WMS provider. The following shows the new enumeration.

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

/// \brief
/// The WmsCommandType enumeration defines the list of WMS+ commands.
enum WmsCommandType{

    /// Represents the GetImageFormats command.
    WmsCommandType_GetImageFormats =  FdoCommandType_FirstProviderCommand + WMS_FIRST_PROVIDER_COMMAND,
    WmsCommandType_GetFeatureClassStyles,
    WmsCommandType_GetFeatureClassCRSNames
};

3 new commands will be added to the FDO WMS Providers, individually for getting image formats, styles and CS names. The usage and the new classes and interfaces are listed as follows.

The following is an example of how WMS GetImageFormats command would be used to get all image formats supported by WMS service after connection.

FdoPtr<FdoIGetImageFormats > cmd = static_cast<FdoIGetImageFormats *> (conn->CreateCommand (WmsCommandType_GetImageFormats));
FdoPtr<FdoStringCollection> result = cmd->Execute ();

class FdoIGetImageFormats: public FdoICommand
{
    friend class FdoIConnection;

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

class FdoWmsGetImageFormatsCommand : public FdoWmsCommand<FdoIGetImageFormats>
{
    friend class FdoWmsConnection;

protected:
    //
    // Prevent the use of the copy constructor by definning it and not implemeting it.
    // DO NOT IMPLEMENT
    FdoWmsGetImageFormatsCommand (const FdoWmsGetImageFormatsCommand &right);

    /// <summary>Constructs an instance of a command for the given connection. </summary>
    /// <returns>Returns nothing</returns> 
    FdoWmsGetImageFormatsCommand (FdoIConnection* connection);

    /// <summary>Virtual Destructor.</summary>
    /// <returns>Returns nothing</returns> 
    virtual ~ FdoWmsGetImageFormatsCommand (void);

    /// <summary>Dispose this object.</summary>
    /// <returns>Returns nothing</returns> 
    virtual void Dispose ();

    // Prevent the use of the Assignment Operation by definning it and not implemeting it.
    // DO NOT IMPLEMENT
    FdoWmsGetImageFormatsCommand & operator= (const FdoWmsGetImageFormatsCommand &right);

public:
    //
    /// <summary> 
    /// Executes the GetFormats command and returns a 
    /// FdoStringCollection, which contains all image formats supported by WMS service.
    /// <returns> 
    /// Returns the image format collection supported by WMS service.
    /// </returns> 
    virtual FdoStringCollection* Execute ();

};

The following is an example of how WMS GetFeatureClassStyles command would be used to get all styles supported by specific layer on WMS service after connection.
Note: FeatureClass is a FDO conception, one feature class is correspond with one layer name in the WMS service. We use feature class, instead of layer here, in order to avoid the confusion of FDO user.

FdoPtr< FDOIGetFeatureStyles > cmd = static_cast< FDOIGetFeatureClassStyles *> (conn->CreateCommand (WmsCommandType_GetFeatureClassStyles));
cmd->SetFeatureClassName(L”ABC”);    
FdoPtr<FdoStringCollection> result = cmd->Execute ();

class FdoIGetFeatureClassStyles : public FdoICommand
{
    friend class FdoIConnection;

public:
    /// \brief
    /// Gets the name of the feature class to get all supported styles. 
    /// 
    /// \return
    /// Returns the featuer class name
    /// 
    FDO_API virtual FdoString* GetFeatureClassName() = 0;

    /// \brief
    /// Sets the name of the feature class to get all supported styles.
    /// This function is mandatory; if not specified, 
    /// execution of the command will throw 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 specific feature class
    /// and all styles supported by its ancestors, because WMS service supports Style 
    /// declarations are inherited by child Layers. 
    /// 
    /// \return
    /// Returns the styles collection supported by specific feature class
    /// 
    FDO_API virtual FdoStringCollection * Execute() = 0;
};

class FdoWmsGetFeatureClassStylesCommand : public FdoWmsCommand< FDOIGetFeatureClassStyles >
{
    friend class FdoWmsConnection;

protected:
    //
    // Prevent the use of the copy constructor by definning it and not implemeting it.
    // DO NOT IMPLEMENT
    FdoWmsGetFeatureClassStylesCommand  (const FdoWmsGetFeatureClassStylesCommand  &right);

    // <summary>Constructs an instance of a command for the given connection. </summary>
    // <returns>Returns nothing</returns> 
    FdoWmsGetFeatureClassStylesCommand  (FdoIConnection* connection);

    // <summary>Virtual Destructor.</summary>
    // <returns>Returns nothing</returns> 
    virtual ~ FdoWmsGetFeatureClassStylesCommand  (void);

    // <summary>Dispose this object.</summary>
    // <returns>Returns nothing</returns> 
    virtual void Dispose ();

    // Prevent the use of the Assignment Operation by definning it and not implemeting it.
    // DO NOT IMPLEMENT
    FdoWmsGetFeatureClassStylesCommand  & operator= (const FdoWmsGetFeatureClassStylesCommand  &right);

public:
    //
    /// <summary>Gets the name of the feature class to get all supported styles. </summary>
    /// <returns>Returns the feature class name</returns> 
    virtual FdoString* GetFeatureClassName ();

    /// <summary>Sets the name of the FeatureClass to get all supported styles 
    /// This function is mandatory; if not specified, 
    /// execution of the command will throw exception. 
    /// </summary>
    /// <param name="value">Input the FeatureClass name</param> 
    /// <returns>Returns nothing</returns> 
    virtual void SetFeatureClassName (FdoString* value);

    /// <summary> 
    /// Executes the GetFeatureClassStyles command and returns a 
    /// FdoStringCollection, which contains entire styles supported by feature class.
    /// and all styles supported by its ancestors, because WMS service supports Style 
    /// declarations are inherited by child Layers. 
    /// 
    /// </summary>
    /// <returns> Returns the style collection supported by FeatureClass. </returns> 
    virtual FdoStringCollection* Execute ();

private:
    FdoStringP mFeatureClassName;
};

The following is an example of how WMS GetFeatureClassCRSNames command would be used to get the all CRS names supported by specifc layer on WMS service after connection.
Note: FeatureClass is a FDO conception, one feature class is correspond with one layer name in the WMS service. We use feature class, instead of layer here, in order to avoid the confusion of FDO user.

FdoPtr<FdoIGetFeatureClassCRSNames> cmd = static_cast<FdoIGetFeatureClassCRSNames*> (conn->CreateCommand (FdoCommandType_GetFeatureClassSupportedCRSNames));
cmd->SetFeatureClassName(L“ABC”);
FdoPtr<FdoStringCollection> result = cmd->Execute ();

class FdoIGetFeatureClassCRSNames: public FdoICommand
{
    friend class FdoIConnection;

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 to get all supported CRS names.
    /// This function is mandatory; if not specified, 
    /// execution of the command will throw 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 a 
    /// FdoStringCollection, which contains entire CRS names supported by specific feature class.
    /// and all CRS names supported by its ancestors, because WMS service supports CRS
    /// declarations are inherited by child Layers. 
    /// 
    /// \return
    /// Returns the CRS name collection supported by the specific feature class.
    /// 
    FDO_API virtual FdoStringCollection * Execute() = 0;
};

class FdoWmsGetFeatureClassCRSNamesCommand: public FdoWmsCommand< FdoIGetFeatureClassCRSNames >
{
    friend class FdoWmsConnection;

protected:
    //
    // Prevent the use of the copy constructor by definning it and not implemeting it.
    // DO NOT IMPLEMENT
    FdoWmsGetFeatureClassCRSNamesCommand (const FdoWmsGetFeatureClassCRSNamesCommand &right);

    // <summary>Constructs an instance of a command for the given connection. </summary>
    // <returns>Returns nothing</returns> 
    FdoWmsGetFeatureClassCRSNamesCommand (FdoIConnection* connection);

    // <summary>Virtual Destructor.</summary>
    // <returns>Returns nothing</returns> 
    virtual ~ FdoWmsGetFeatureClassCRSNamesCommand (void);

    // <summary>Dispose this object.</summary>
    // <returns>Returns nothing</returns> 
    virtual void Dispose ();

    // Prevent the use of the Assignment Operation by defining it and not implementing it.
    // DO NOT IMPLEMENT
    FdoWmsGetFeatureClassCRSNamesCommand & operator= (const FdoWmsGetFeatureClassCRSNamesCommand &right);

public:
    //
    /// <summary> Gets the name of the FeatureClass to get all supported CRS names. </summary>
    /// <returns>Returns the FeatureClass name</returns> 
    virtual FdoString* GetFeatureClassName ();

    /// <summary> Sets the name of the FeatureClass to get all supported CRS names.
    /// This function is mandatory; if not specified, 
    /// execution of the command will throw exception. 
    /// </summary>
    /// <param name="value">Input the FeatureClass name</param> 
    /// <returns>Returns nothing</returns> 
    virtual void SetFeatureClassName (FdoString* value);

    /// <summary> 
    /// Executes the GetFeatureClassCRSNames command and returns a 
    /// FdoStringCollection, which contains entire CRS names supported by feature class.
    /// and all CRS names supported by its ancestors, because WMS service supports CRS
    /// declarations are inherited by child Layers. 
    /// </summary>
    /// <returns> Returns the CRS names collection supported by FeatureClass.</returns> 
    virtual FdoStringCollection* Execute ();

private:
    FdoStringP mFeatureClassName;
};

Implications

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

Test Plan

Existing unit tests will be expanded to test those changes.

Funding/Resources

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