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	(pending, under development, completed)
Proposed Milestone	(e.g. 1.1, 1.3)
Assigned PSC guide(s)	(when determined)
Voting History	(vote date)
+1	Bob, Mateusz
+0	Frank
-0	Orest
-1	Greg (troublemaker)

Overview

In the current design of the OSGeo OGC FDO WMS Provider(s), no mechanism exists to allow a client to retrieve all supported CS’s for a specific WMS layer, neither for image format and style information. 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 server.

Motivation

This is the most important part of the RFC. It describes the problem domain in detail. Focusing on this will allow reviewers to fully understand why the proposed change is being made, and potentially suggest different/better ways of accomplishing the desired results. The more time we spend on understanding the problem, the better our solution will be.

Proposed Solution

In order not to impact the standard FDO command interface, we plan just adding those 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_GetLayerStyles,
    WmsCommandType_GetLayerCRSNames
};

3 new commands will be added to the FDO WMS Providers, individually for getting image formats, style and CS. 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 the entire supported image formats list form WMS server 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 server.
    /// 
    /// \return
    /// Returns the image format collection supported by WMS server
     /// 
    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 ();

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

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

};

The following is an example of how WMS GetLayerStyles command would be used to get the entire supported image formats list form WMS server after connection.

FdoPtr< FDOIGetLayerStyles > cmd = static_cast< FDOIGetLayerStyles *> (conn->CreateCommand (WmsCommandType_GetLayerStyles));
cmd->SetLayerName(L”ABC”);
FdoPtr<FdoStringCollection> result = cmd->Execute ();

class FdoIGetLayerStyles : public FdoICommand
{
    friend class FdoIConnection;

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

    /// \brief
    /// Sets the name of the layer to get all supported styles.
    /// This function is mandatory; if not specified, 
    /// execution of the command will throw exception. 
    ///
    /// \param value 
    /// Input the layer name
    /// 
    /// \return
    /// Returns nothing
    /// 
    FDO_API virtual void SetLayerName(FdoString* value) = 0;

    /// \brief
    /// Executes the GetLayerStyles command and returns a 
    /// FdoStringCollection, which contains all styles supported by specific layer.
    /// 
    /// \return
    /// Returns the styles collection supported by server
    /// 
    FDO_API virtual FdoStringCollection * Execute() = 0;
};

class FdoWmsGetLayerStylesCommand : public FdoWmsCommand< FDOIGetLayerStyles >
{
    friend class FdoWmsConnection;

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

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

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

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

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

    /// <summary> Gets the name of the layer to get all supported styles. </summary>
    /// <returns>Returns the layer name</returns> 
    virtual FdoString* GetLayerName ();

    /// <summary> Sets the name of the layer 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 layer name</param> 
    /// <returns>Returns nothing</returns> 
    virtual void SetLayerName (FdoString* value);

    /// <summary> 
    /// Executes the GetLayerStyles command and returns a 
    /// FdoStringCollection, which contains entire styles supported by layer.
    /// <returns> Returns the style collection supported by layer.
    ///</returns> 
    virtual FdoStringCollection* Execute ();

private:
    FdoStringP mLayerName;
};

The following is an example of how WMS GetLayerCRSNames command would be used to get the entire supported image formats list form WMS server after connection.

FdoPtr<FdoIGetLayerCRSNames> cmd = static_cast<FdoIGetLayerCRSNames*> (conn->CreateCommand (FdoCommandType_GetLayerSupportedCRSNames));
cmd->SetLayerName(L“ABC”);
FdoPtr<FdoStringCollection> result = cmd->Execute ();

class FdoIGetLayerCRSNames: public FdoICommand
{
    friend class FdoIConnection;

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

    /// \brief
    /// Sets the name of the layer to get all supported styles.
    /// This function is mandatory; if not specified, 
    /// execution of the command will throw exception. 
    ///
    /// \param value 
    /// Input the layer name
    /// 
    /// \return
    /// Returns nothing
    /// 
    FDO_API virtual void SetLayerName(FdoString* value) = 0;

    /// \brief
    /// Executes the GetCRSNames command and returns a 
    /// FdoStringCollection, which contains entire CRS names supported by server.
    /// 
    /// \return
    /// Returns the CRS name collection supported by server
    /// 
    FDO_API virtual FdoStringCollection * Execute() = 0;
};

class FdoWmsGetLayerCRSNamesCommand: public FdoWmsCommand< FdoIGetLayerCRSNames >
{
    friend class FdoWmsConnection;

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

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

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

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

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

    /// <summary> Gets the name of the layer to get all supported CRS names. </summary>
    /// <returns>Returns the layer name</returns> 
    virtual FdoString* GetLayerName ();

    /// <summary> Sets the name of the layer 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 layer name</param> 
    /// <returns>Returns nothing</returns> 
    virtual void SetLayerName (FdoString* value);

    /// <summary> 
    /// Executes the GetLayerCRSNames command and returns a 
    /// FdoStringCollection, which contains entire CRS names supported by layer.
    /// <returns> Returns the CRS names collection supported by layer.
    ///</returns> 
    virtual FdoStringCollection* Execute ();

private:
    FdoStringP mLayerName;
};

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.