= FDO RFC 57 - Implement the !GetFeatureInfo command for WMS provider  =

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.1)||  
||Submission Date||March 23, 2011|| 
||Last Modified||Cheney Sun, March 23, 2011|| 
||Author||Cheney Sun|| 
||RFC Status||proposed|| 
||Implementation Status||completed|| 
||Proposed Milestone||3.7.0.0 || 
||Assigned PSC guide(s)||Orest Halustchak, Greg Boone|| 
||'''Voting History'''||(vote date)|| 
||+1|||| 
||+0|||| 
||-0|||| 
||-1|||| 
 
== Overview ==

The RFC is to implement the !GetFeatureInfo command for WMS provider. 

== Motivation ==

!GetFeatureInfo is an optional operation of WMS server. It is only supported for those Layers for which the attribute queryable="1" (true) has been defined or inherited. The !GetFeatureInfo operation is designed to provide clients of a WMS with more information about features in the pictures of maps that were returned by Get Map requests. The canonical use case for !GetFeatureInfo is that a user sees the response of a Map request and chooses a point on that map for which to obtain more information.

Here is the table of the parameters of a !GetFeatureInfo Request based on the 1.3.0 version:

||'''Request parameter'''	||'''Mandatory/optional'''	||'''Description'''||
||VERSION=1.3.0 	||M	||Request version||
||REQUEST=!GetFeatureInfo 	||M	||Request name||
||map request part||	M	||Partial copy of the Map request parameters that generated the map for which information is desired.||
||QUERY_LAYERS=layer_list ||	M	||Comma-separated list of one or more layers to be queried||
||INFO_FORMAT=output_format 	||M	||Return format of feature information (MIME type).||
||FEATURE_COUNT=number	||O	||Number of features about which to return information (default=1).||
||I=pixel_column	||M	||i coordinate in pixels of feature in Map CS||
||J=pixel_row	||M	||j coordinate in pixels of feature in Map CS||
||EXCEPTIONS=exception_format	||O	||The format in which exceptions are to be reported by the WMS (default= XML)||

Basically, the goal is that users must be able to not only connect to WMS services and add features to maps from those services; they should also be able to click on map features to get more information.[[BR]]
As to the 1.1.0 version, the standard employs the x = pixel_column and y = pixel_row to replace I = pixel_column and J = pixel_row.[[BR]]

More details regarding the WMS !GetFeatureInfo request can be found in the WMS standards http://www.opengeospatial.org/standards/wms.

== Proposed Solution ==

The shortest WMS !GetFeatureInfo implementation path would involve implementing !GetFeatureInfo request within the current FDO WMS provider. The design solution would provide a custom command to users to retrieve the feature information: !FdoWmsCommandType_GetFeatureInfo.[[BR]]

'''•	Input of the !GetFeatureInfo request'''[[BR]]

From the required parameters table above, we can see !GetFeatureInfo requires almost all the parameters required by !GetMap request and plus more, the custom command would also require the same input for Select command and extra parameters (i, j coordinate in pixels of feature in Map CS). [[BR]]

'''•	Output of the !GetFeatureInfo request'''[[BR]]

The format of responded message from the !GetFeatureInfo request is defined by the WMS server. For example:[[BR]]

  <Format>text/plain</Format> [[BR]]
  <Format>text/html</Format>[[BR]]

Currently, the WMS implementation specification doesn’t define a standard format for it. So, the solution is to return a !FdoString* type pointer by this command. If user set the FEATURE_COUNT greater than 1, the information for multiple candidate features will be returned. However, we don’t parse the returned information since no standard regarding the format and client should take the responsibility to parse it.  For example the following text is returned from one server to response the !GetFeatureInfo request.[[BR]]

     Layer 'IBA'[[BR]]
     Feature 6:[[BR]]
     SITEID = 'NU009'[[BR]]
     NAME = 'Queen Maud Lowlands' [[BR]]
     LINK = 'http://www.bsc-eoc.org/iba/site.jsp?siteID=NU009' [[BR]]

     Feature 66:[[BR]]
     SITEID = 'NU089'[[BR]]
     NAME = 'Middle Back River'[[BR]]
     LINK = 'http://www.bsc-eoc.org/iba/site.jsp?siteID=NU089' [[BR]]

However, the following XML formatted message will return if issue the command to a !MapGuide server. [[BR]]

{{{
<?xml version=”1.0”, encoding=”UTF-18”?>
   <FeatureInfoCollection>
     <FeatureInfo layer = “Sample/Layers/Districts”>
       <Property name=”name” value = “Voting District Three”/>
       <Property name =”Url” value=””/>
       <Property name=Key value=3/>
       <Property name=”Autogenerated_SDF_ID” value=6/>
     </FeatureInfo>
   </FeatureInfoCollection>
}}}

Note: we can parse the response value and return a class if WMS spec defines a standard format in the future.

'''•	!GetFeatureInfo custom command interface'''[[BR]]

{{{
/// \brief
/// The FdoWmsIGetFeatureInfo interface defines the 
/// FdoWmsIGetFeatureInfo command, which retrieves more information
/// about features in the maps. The Execute operation 
/// returns a FdoString* type pointer pointing to the feature information.
class FdoWmsIGetFeatureInfo : public FdoICommand
{
    friend class FdoIConnection;
public:
    /// \brief
    /// Execute the FdoWmsIGetFeatureInfo command and returns a 
    /// FdoString* pointer, which points to the feature information returned 
    /// by the WMS server.
    /// 
    /// \return
    /// Returns string contains feature information from the WMS server
    /// 
    FDO_API virtual FdoString * Execute() = 0;

    /// \brief
    /// Set the feature class name for which feature information
    /// will be retrieved. This function is mandatory; if not specified or the feature class 
    /// name can’t be found in the schema, execution of the command will throw an
    /// exception. 
    /// 
    /// \param value 
    /// Input the feature class name.
    /// 
    /// \return
    /// Returns nothing 
    /// 
    FDO_API virtual void SetFeatureClassName(FdoIdentifier* values) = 0;

    /// \brief
    /// Get the name of the feature class for which feature information 
    /// will be retrieved.
    /// 
    /// \return
    /// Input the query feature class name.
    /// 
    FDO_API virtural FdoIdentifier * GetFeatureClassName() = 0;

    /// \brief
    /// Set the position (X, Y) which indicates a point of interest on the map that was
    /// produced by the embedded !GetMap request.The point (X, Y) is a
    /// point in the (i, j) space defined by the Map CS.
    /// This function is mandatory; if not specified, 
    /// execution of the command will throw an exception. 
    /// 
    /// \param pos 
    /// Input the point's coordinate value (X, Y)
    ///
    /// \return
    /// Return nothing
    /// 
    FDO_API virtual void SetPosition(FdoIDirectPosition* pos) = 0;

    /// \brief
    /// Get the position (X, Y) which indicates a point of interest on the map that was
    /// produced by the embedded !GetMap request. The point (X, Y) is a
    /// point in the (i, j) space defined by the Map CS.
    ///
    /// \return
    /// Return the interesting position.
    /// 
    FDO_API virtual FdoIDirectPosition* GetPosition() = 0;

    /// \brief
    /// Set the number of features about which to return information (default=1).
    /// 
    /// \param featureCount
    /// The number of the features to query.
    ///
    /// \return
    /// Returns nothing
    /// 
    FDO_API virtual void SetFeatureCount(FdoInt32 featureCount = 1) = 0;

    /// \brief
    /// Get the number of features about which to return information.
    /// 
    /// \return
    /// Returns candidate feature number.
    /// 
    FDO_API virtual FdoInt32 GetFeatureCount () = 0;
};
}}}

In this class, both methods !GetFeatureClassName and !SetFeatureClassName are used to get/set a feature class which would be mapped to WMS layer in order to query the relevant feature information. [[BR]]

'''•	Example''' [[BR]]

The !GetFeatureInfo custom command will be used like below:

{{{
FdoPtr<FdoWmsIGetFeatureInfo> cmdGFI = static_cast<FdoWmsIGetFeatureInfo*> (connection->CreateCommand(FdoWmsCommandType_!GetFeatureInfo));
FdoPtr<FdoIdentifier> id = FdoIdentifier::Create(L”Park”);
cmdGFI->SetFeatureClassName(id); 
FdoPtr<FdoFgfGeometryFactory> gf = FdoFgfGeometryFactory::GetInstance();
FdoPtr<FdoIDirectPosition> pt = gf->CreatePositionXY(-1000, 1000);
cmdGFI->SetPosition(pt);
FdoStringP featureInfo = cmdGFI->Execute ();
}}}

Since there are lots of same parameters required as !GetMap request, the Execute function of this custom command will be similar with the select command. The difference is to pass the extra i, j values and fire the !GetFeatureInfo request to WMS server. What’s more, share the same codes between select command and !GetFeatureInfo custom command should be considered seriously.[[BR]]

Similar to the !GetMap request, the parameters regarding the !GetMap parts should be obtained from the override configuration. If it’s not customized, the default parameters will be gotten from capabilities documents (returned from !GetCapabilities).  One note is that the command should generally be called after the !GetMap request; otherwise, the returned result is probably unexpected if the parameters are wrongly specified.

== Implications ==

•	A new command !FdoWmsCommandType_GetFeatureInfo is added for WMS provider.

== Test Plan ==

Add unit tests into WMS provider to test the new command.

== !Funding/Resources ==

Autodesk to provide resources / funding