Changes between Initial Version and Version 1 of MapGuideRfc175

Timestamp:

07/13/19 05:49:04 (5 years ago)

Author:

jng

Comment:

--

MapGuideRfc175

@@ +1 @@
+= !MapGuide RFC 175 - WFS GetFeature support for hit count =
+
+This page contains a change request (RFC) for the !MapGuide Open Source project.
+More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page.
+
+== Status ==
+
+||RFC Template Version||(1.0)||
+||Submission Date||13 Jul 2019||
+||Last Modified||13 Jul 2019||
+||Author||Jackie Ng||
+||RFC Status||draft||
+||Implementation Status||pending||
+||Proposed Milestone||4.0||
+||Assigned PSC guide(s)||(when determined)||
+||'''Voting History'''||(vote date)||
+||+1||||
+||+0||||
+||-0||||
+||-1||||
+||no vote|| ||
+
+== Overview ==
+
+This RFC proposes to add support for `resultType=hits` in WFS 1.1.0 `GetFeature` requests
+
+== Motivation ==
+
+With WFS 1.1.0 onwards, a WFS client may pass an optional `resultType=hits` parameter to request a raw 
+total of matching features instead of the full set of feature data in the requested format.
+
+This parameter is an optional part of the WFS 1.1.0 spec that MapGuide currently does not support. As a
+result, a WFS client currently has no way to request a feature total from a MapGuide WFS service without
+requesting the full feature data, which is an extremely inefficient way to count features.
+
+== Proposed Solution ==
+
+Add support for `resultType=hits` for WFS 1.1.0 `GetFeature` requests.
+
+To support this we'll add a new internal `GetWfsFeatureTotal` method which does the same feature query as
+the original `GetFeature` request, but raw spins the resulting feature reader on the server-side to obtain
+the feature total.
+
+{{{
+class MG_PLATFORMBASE_API MgFeatureService : public MgService
+{
+...
+INTERNAL_API:
+    ////////////////////////////////////////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Retrieves the total feature count for the given WFS query
+    ///
+    /// \note1
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual int GetWfsFeatureTotal(MgResourceIdentifier featureSourceId, string featureClass, string filter, int maxFeatures);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual int GetWfsFeatureTotal(MgResourceIdentifier featureSourceId, string featureClass, string filter, int maxFeatures);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual int GetWfsFeatureTotal(MgResourceIdentifier featureSourceId, string featureClass, string filter, int maxFeatures);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param featureSourceId (MgResourceIdentifier)
+    /// The resource identifier defining the
+    /// location of the feature source in
+    /// the repository.
+    /// \param featureClass (String/string)
+    /// The feature class containing the features to retrieve.
+    /// \param filter (String/string)
+    /// An XML string containing the definition for an OGC filter
+    /// \param maxFeatures (int)
+    /// If greater than 0 and less than the real computed total, this will be the value returned
+    ///
+    /// \remarks
+    /// This method is primarily used to service the WFS GetFeatures operation in resultType=hits mode
+    /// where a total is desired over requesting the whole set of feature data
+    ///
+    /// \return
+    /// Returns an MgByteReader containing the requested feature information.
+    ///
+    /// \exception MgInvalidArgumentException
+    ///
+    /// \since 4.0
+    virtual INT32 GetWfsFeatureTotal(MgResourceIdentifier* featureSourceId,
+        CREFSTRING featureClass,
+        CREFSTRING filter,
+        INT32 maxFeatures) = 0;
+};
+}}}
+
+A question one may ask is why raw spin a feature reader to obtain the feature total instead of something 
+more efficient like a SelectAggregates with `COUNT()`? The problem lies in the `maxFeatures` parameter that
+can be specified in any WFS `GetFeatures` request. If this parameter is present when requesting a hit count,
+*it needs to be respected* and none of the optimal counting methods we have allow us to specify an upper limit. As 
+a result, raw spinning a feature reader is the only practical solution.
+
+A sample `GetFeature` response with `resultType=hits` would look like this:
+
+{{{
+<?xml version="1.0" encoding="utf-8" ?>
+<wfs:FeatureCollection xmlns:gml="http://www.opengis.net/gml" xmlns:wfs="http://www.opengis.net/wfs" xmlns:ns55197509="http://fdo.osgeo.org/schemas/feature/ns55197509" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opengis.net/gml http://schemas.opengis.net/gml/3.1.1/base/feature.xsd http://www.opengis.net/wfs http://schemas.opengis.net/wfs/1.1.0/wfs.xsd" numberOfFeatures="11" />
+}}}
+
+If JSON format is requested, the response would look like this:
+
+{{{
+{
+    "numberOfFeatures": 11
+}
+}}}
+
+This implementation exists in the [https://trac.osgeo.org/mapguide/browser/sandbox/jng/wfs_hits wfs_hits sandbox]. Upon adoption of this RFC, will be merged into trunk.
+
+== Implications ==
+
+This parmameter is only available for WFS 1.1.0. For WFS 1.0.0, this parameter has no effect.
+
+Another important note is that the feature total will only be included *if and only if* `resultType=hits` is 
+included. It is not included in regular `GetFeature` responses as it would require 2 queries (1 to count, 1 for the
+original query) and for the sake of simplicity in implementation that it was carried out in this way.
+
+== Test Plan ==
+
+Verify `resultType=hits` returns hit count only for WFS 1.1.0 requests
+
+== Funding / Resources ==
+
+Community