= !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||17 Jul 2019||
||Author||Jackie Ng||
||RFC Status||implemented||
||Implementation Status||implemented||
||Proposed Milestone||4.0||
||Assigned PSC guide(s)||(when determined)||
||'''Voting History'''||(vote date)||
||+1||Jackie,Gordon,Martin||
||+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