FCS result count semantics for "-1"

[Querela]

So, while testing, I found that the special semantics of setting the numberOfRecords to -1 as described in the SRUSearchResultSet of fcs-sru-server is not exactly specified in any specification. Client libraries (like fcs-sru-client) ignore this, too! So following the doc string will lead to invalid and unexpected behavior.

→ So either the doc string has to be adjusted and something should be added to the FCS specification as well as updates to fcs-sru-client.

Details

declaration > getTotalRecordCount

fcs-sru-server/src/main/java/eu/clarin/sru/server/SRUSearchResultSet.java

Lines 58 to 66 in 0091fca

	/**
	* The number of records matched by the query. If the query fails this must
	* be 0. If the search engine cannot determine the total number of matched
	* by a query, it must return -1.
	*
	* @return the total number of results or 0 if the query failed or -1 if the
	* search engine cannot determine the total number of results
	*/
	public abstract int getTotalRecordCount();

The number of records matched by the query. If the query fails this must be 0. If the search engine cannot determine the total number of matched by a query, it must return -1.

serialization > numberOfRecords

fcs-sru-server/src/main/java/eu/clarin/sru/server/SRUServer.java

Lines 422 to 426 in 0091fca

	// numberOfRecords
	out.writeStartElement(ns.getResponseNS(), "numberOfRecords");
	out.writeCharacters(
	Integer.toString(result.getTotalRecordCount()));
	out.writeEndElement(); // "numberOfRecords" element

The value is written as is.

handling of numberOfRecords in fcs-sru-client library (working according to specs)

https://github.com/clarin-eric/fcs-sru-client/blob/18f2bab01b342cf9095db8cfedb10e5b4e9d54da/src/main/java/eu/clarin/sru/client/SRUSimpleClient.java#L938-L940

The value is simply parsed from the XML, it defaults to -1 for invalid cases, e.g. if the surrounding element is not there or can't be parsed. This also should not happen since required=true is set, so rather than a default value, an exception will be thrown...

https://github.com/clarin-eric/fcs-sru-client/blob/18f2bab01b342cf9095db8cfedb10e5b4e9d54da/src/main/java/eu/clarin/sru/client/SRUSimpleClient.java#L955

This only checks for numberOfRecords > 0 and processes results normally. For -1 it does error analysis and in (default) strict mode throws an exception ...

Specs

FCS 2.0

• https://office.clarin.eu/v/CE-2017-1046-FCS-Specification-v89.pdf
  • §3.4 searchRetrieve ?
  • also not in FCS 1.0 spec

SRU 1.2

• http://docs.oasis-open.org/search-ws/searchRetrieve/v1.0/os/part2-sru1.2/searchRetrieve-v1.0-os-part2-sru1.2.pdf
  • L249 / §5.3 - <numberofRecords>; only zero if failure

SRU 2.0

• http://docs.oasis-open.org/search-ws/searchRetrieve/v1.0/os/part3-sru2.0/searchRetrieve-v1.0-os-part3-sru2.0.pdf
  • L314 / §7.2 - <numberOfRecords>; only zero if failure
  • L339 / §7.6 - <resultCountPrecision>; might describe unknown result count but nothing about any special value of the <numberOfRecords> or how to set it when the result count is unknown.

[benhur1999]

The missing check for -1 is an error in the implementation. It was planned to enable the search engine implemenation to provide more detail and allow the sru server to be more smart about "search failed" vs "no results" case, i.e. in case of 0 it could automatically set resultCountPrecision to unknown in the SRU 2.0 case