Changes between Version 7 and Version 8 of FDORfc57

Timestamp:

03/31/11 23:45:18 (14 years ago)

Author:

sunch

Comment:

--

FDORfc57

@@ -6 +6 @@
 == Status == 
  
-||RFC Template Version||(1.1)||  
+||RFC Template Version||1.1||  
 ||Submission Date||March 23, 2011|| 
 ||Last Modified||Cheney Sun, March 23, 2011|| 
@@ -48 +48 @@
 == 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]]
+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, !FdoWmsCommandType_GetFeatureInfo, for users to retrieve the feature information.[[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]]
+From the required parameters table above, we can see !GetFeatureInfo requires a copy of parameters required by !GetMap request and plus its own parameter. So the custom command would also require the same input for Select command and extra parameters ( QUERY_LAYERS, INFO_FORMAT, FEATURE_COUNT, I and J ). To simplify the implementation and usage of the command, the relevant !GetMap request will be cached in the connection class and this command would pick up it as the part of the !GetMap parameters. This presumes that the command shoud be invoked after the relevant select command. If no cached !GetMap request available, execution of the command would throw an exception.[[BR]]
+
+Although, it's possible that the command would employ a different bounding box and resolution with those used in the cached !GetMap request, The command also exposes another entries to let user specify the expected bounding box, height and width.[[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]]
+The format of responded message from the !GetFeatureInfo request is defined by the WMS server. According to the WMS standard, the retrieved feature information is a MIME type. For example, it could be the following format.[[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]]
-
+  <Format>text/html</Format> [[BR]]
+  <Format>text/xml</Format> [[BR]]
+  <Format>image/png</Format> [[BR]]
+  <Format>video/mpeg</Format> [[BR]]
+  .......[[BR]]
+
+Currently, the WMS specification doesn’t define a standard format for each of the subtype. So, the solution is to return a !FdoIoStream* type pointer by this command. Users take the responsibilities to parse the returned data stream. If user set the FEATURE_COUNT greater than 1, the information for multiple candidate features will be returned. [[BR]] For example, if the "text/plain" is specified as the output format and set the FEATURE_COUNT as 2, the string stream below would be obtained.[[BR]]
      Layer 'IBA'[[BR]]
      Feature 6:[[BR]]
@@ -74 +79 @@
      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]]
+However, the following XML formatted message stream will return if issue the command to a !MapGuide server and specifying the output format as "text/xml". [[BR]]
 
 {{{
@@ -88 +93 @@
 }}}
 
-Note: we can parse the response value and return a class if WMS spec defines a standard format in the future.
+Similarly, if specifying the output format as "image/png", an image stream would be returned; specifying it as "video/mpeg" would get a video stream. Users have the freedom to choose a way of comsuming those data.[[BR]]
 
 '''•    !GetFeatureInfo custom command interface'''[[BR]]
@@ -96 +101 @@
 /// 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.
+/// about features in the maps. The Execute operation returns a 
+/// FdoIoStream* type pointer pointing to the feature information
+/// data stream.
 class FdoWmsIGetFeatureInfo : public FdoICommand
 {
@@ -104 +110 @@
     /// \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;
+    /// FdoIoStream* pointer. It could be a text, image, video and any 
+    /// binary data stream, ect. The result depends on the specified output
+    /// format.
+    /// 
+    /// \return
+    /// Return a FdoIoStream representing the feature information.
+    /// 
+    FDO_API virtual FdoIoStream* Execute() = 0;
 
     /// \brief
@@ -134 +141 @@
     /// 
     FDO_API virtural FdoIdentifier * GetFeatureClassName() = 0;
+
+    /// \brief
+    /// Set the format of output feature information. The supported values are MIME type
+    /// strings and should be listed in one or more <Format> elements inside the 
+    /// <Request><FeatureInfo> element of the Capabilities XML.
+    /// An exception would be thrown if the value isn't in the supported list when
+    /// executing the command. The default value is the first one specified in the 
+    /// Capabilities document.
+    /// 
+    /// \para value
+    /// Input the output feature information format.
+    /// 
+    FDO_API virtual void SetOutputFormat(FdoString* value) = 0;
+
+    /// \brief
+    /// Get the specified format for the returning feature information.
+    /// 
+    /// \return
+    /// Return the output feature information format.
+    /// 
+    FDO_API virtual FdoString* GetOutputFormat() = 0;
+
+    /// \brief
+    /// Set the bounding box that would be used to replace the one in 
+    /// cached GetMap request. If it's not set or the bounding box is 
+    /// empty, directly use the one in cached GetMap request.
+    /// 
+    /// \param value
+    /// Input the interest bounding box.
+    /// 
+    FDO_API virtual void SetBoundingBox(FdoIEnvelope* value) = 0;
+
+    /// \brief
+    /// Get the bounding box that's specified to replace the one in 
+    /// cached GetMap request.
+    /// 
+    /// \return
+    /// Return the specified bounding box for GetMap request.
+    /// 
+    FDO_API virtual FdoIEnvelope* GetBoundingBox() = 0;
+
+    /// \brief
+    /// Set the height to replace the one used in the cached GetMap
+    /// request. Its default value is zero, if the specified value is 
+    /// greater than zero, the replacement would happen. Otherwise, 
+    /// directly use the one in the cached GetMap request.
+    /// 
+    /// \param value
+    /// Input the specified image height.
+    /// 
+    FDO_API virtual void SetHeight(FdoSize value) = 0;
+
+    /// \brief
+    /// Get the height that's specified to replace the one in cached 
+    /// GetMap request. Its default value is zero.
+    /// 
+    /// \return
+    /// Return specified image height.
+    /// 
+    FDO_API virtual FdoSize GetHeight() = 0;
+
+    /// \brief
+    /// Set the width to replace the one used in the cached GetMap
+    /// request. Its default value is zero, if the specified value is 
+    /// greater than zero, the replacement would happen. Otherwise, 
+    /// directly use the one in the cached GetMap request.
+    /// 
+    /// \param value
+    /// Input the specified image width.
+    ///
+    FDO_API virtual void SetWidth(FdoSize value) = 0;
+
+    /// \brief
+    /// Get the width that's specified to replace the one in cached 
+    /// GetMap request. Its default value is zero.
+    /// 
+    /// \return
+    /// Return specified image width.
+    ///
+    FDO_API virtual FdoSize GetWidth() = 0;
 
     /// \brief
@@ -185 +272 @@
 '''•    Example''' [[BR]]
 
-The !GetFeatureInfo custom command will be used like below:
-
+Generally, the !FdoWmsSelectCommand will be called before the !GetFeatureInfo custom command. The following select command can be called to bring map to the application.[[BR]]
 {{{
-FdoPtr<FdoWmsIGetFeatureInfo> cmdGFI = static_cast<FdoWmsIGetFeatureInfo*> (connection->CreateCommand(FdoWmsCommandType_!GetFeatureInfo));
-FdoPtr<FdoIdentifier> id = FdoIdentifier::Create(L”Park”);
-cmdGFI->SetFeatureClassName(id); 
+FdoPtr<FdoIConnection> conn = CreateConnection ();
+conn->SetConnectionString (L"FeatureServer=http://www.WMSSERVER.net/wms_service");
+FdoConnectionState_Open == conn->Open (); // Open the connection.
+FdoPtr<FdoISelect> cmd = static_cast<FdoISelect *> (conn->CreateCommand (FdoCommandType_Select));
+cmd->SetFeatureClassName (L"Borders_Poly");
+FdoPtr<FdoIdentifierCollection> selProps = cmd->GetPropertyNames ();
+FdoPtr<FdoIdentifier> prop = FdoIdentifier::Create (L"FeatId");
+selProps->Add (prop);
+FdoPtr<FdoIFeatureReader> featReader = cmd->Execute ();
+......
+}}}
+
+After viewing the generated WMS map, users could wonder the information at some point of the map. The custom !GetFeatureInfo command could be called as below.[[BR]]
+
+{{{
+FdoPtr<FdoWmsIGetFeatureInfo> cmdGFI = static_cast<FdoWmsIGetFeatureInfo*> ( conn->CreateCommand(FdoWmsCommandType_!GetFeatureInfo) );
+FdoPtr<FdoIdentifier> id = FdoIdentifier::Create(L"Borders_Poly");
+cmdGFI->SetFeatureClassName(id);
 FdoPtr<FdoFgfGeometryFactory> gf = FdoFgfGeometryFactory::GetInstance();
 FdoPtr<FdoIDirectPosition> pt = gf->CreatePositionXY(-1000, 1000);
 cmdGFI->SetPosition(pt);
-FdoStringP featureInfo = cmdGFI->Execute ();
+cmdGFI->SetOutputFormat(L"text/xml");
+FdoPtr<FdoIoStream> stream = 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.
+In the upper case, the cached bounding box and resolution are not changed. However, if the application employs the tile approach to improve the map loading performance, the bounding box and resolution in the cached !GetMap parameters couldn't meet the request. The methods !SetBoundingBox, !SetHeight and !SetWidth need be called to specify the expected ones, and the command would automatically replace the cached parameters before execution.[[BR]]
+
+Note: If the select command isn't called before executing the !FdoWmsCommandType_!GetFeatureInfo command, an exception would be thrown.[[BR]]
+
 
 == Implications ==