support OWS updateSequence attribute

[tomkralidis]

(I've tagged this under SOS as the intial calling implementation, but this will apply and be available to all OWS support.)

This is in OWS Common 1.0.0 (​http://portal.opengeospatial.org/files/?artifact_id=8798), subclause 7.3.4.

From a MapServer OWS point of view, this would have two changes:

1./

Default Capabilities XML output:

Say, for an SOS Server, when responding to a GetCapabilities request, the SOS would include @updateSequence in the root element of the XML document.

Since updateSequence can be anything, we could implement an msOWSGetUpdateSequence(), which returns an integer based on the mtime of the mapfile. However, this may not be as indicative, i.e.:

• what if the underlying data is updated, and a change occurs to the bbox of the layer, but the mtime of the mapfile is the same
• what if the mapfile is using INCLUDE'd mapfiles which are modified (but this is not evident in the calling mapfile's mtime

As a result, we can support MAP/WEB/METADATA/???_updatesequence. If this is set, then this overrides the mapfile's mtime.

2./

Handling updatesequence from client requests. See psuedocode:

// in Capabilities handler
if (pszUpdateSequence) {
  if (pszUpdateSequence > msOWSGetUpdateSequence(map)) {
    // return exception
  }

  if (pszUpdateSequence == msOWSGetUpdateSequence(map)) {
    // return an XML document with JUST the version and updateSequence, like:
    // <sos:Capabilities xmlns:sos="http://www.opengis.net/sos/1.0" version="1.0.0" updateSequence="x"/>
    // hence there is no need to send the ENTIRE document back, nor for the client to process it
  }

  else {
    // proceed as normal
  }
}

This would benefit catalogs and harvesting mechanisms in managing caches of Capabilities, and reduce client/server communications on such use cases.

[tomkralidis]

Excerpt from 7.3.4:

The optional updateSequence parameter can be used for maintaining the consistency of a client cache of the contents of a service metadata document. The parameter value can be an integer, a timestamp in [ISO 8601:2000] format, or any other number or string.

A server may include an updateSequence value in its service metadata document. If supported, the updateSequence value shall be increased by the server when any changes are made to the complete service metadata document (for example, when new coverages are added to the WCS service). The server is the sole judge of lexical ordering sequence. A client may include this parameter in its GetCapabilities request. The response of the server based on the presence and relative value of updateSequence in the client request and the server metadata shall be as specified in Table 4.

Table 4 Use of updateSequence parameter

Operation request updateSequence value	Service metadata updateSequence value	Server response
None	Any	most recent service metadata document
Any	None	most recent service metadata document
Equal	Equal	service metadata document with only “version” and “updateSequence” parameters
Lower	Higher	most recent service metadata document
Higher	Lower	exception report with exceptionCode = InvalidUpdateSequence

[tomkralidis]

I am beginning to think it is more practical to just fetch from a metadata value. If it exists, then use it. If not, don't. Are we better off supporting updateSequence if WEB/METADATA/ows_updatesequence is set? I would prefer to go this way. Frank (irc convo) seems to agree.

Any thoughts or objections?

[tomkralidis]

• implemented output of updateSequence in r7344
• updated msautotest in r7345
• updated documentation for WMS Server, WFS Server, SOS Server.

Note that I did not update WCS Server, as it does not follow the pattern of the other WxS documentation, and does not include common OWS metadata (will open separate ticket calling for review of WCS Server documentation).

Now on to handling of updateSequence if passed by the client.

[dmorissette]

FWIW, I agree that supporting updatesequence only if the ows_updatesequence metadata is set is fine.

[tomkralidis]

Implemented and committed.

• mapstring.c now has msStringIsInteger() (r7360). This function tests whether a string is an integer or not and is called by msOWSNegotiateUpdateSequence()
• r7361 implements this enhancement. mapows.c now has msOWSNegotiateUpdateSequence(). Strings, integers and ISO timestamps are supported. The calling OWS code handles the return value and acts accordingly (exception or continue)
• test cases added to msautotest/wxs in r7362

I will keep this one open for a bit. Reviews, comments, and tests welcome.

[tamas]

The windows builders were getting broken that might be related to these changes.

mapwcs11.obj : error LNK2019: unresolved external symbol _msWCSException11 referenced in function _msWCSGetCoverageBands11 libmap.dll : fatal error LNK1120: 1 unresolved externals

See the buildbot results for more details ​http://buildbot.osgeo.org:8504/waterfall

[tomkralidis]

I declared this function in mapwcs.h now in r7365. Does this fix the issue?

[tomkralidis]

There were issues with intermingling 1.0 and 1.1 code (as 1.1 requires libxml2).

Thanks for FrankW and irc convo, r7366 seems to fix this issue (the windows builders build fine now).

[tomkralidis]

Closing. Looks like the WCS and SOS CITE tests have no problem with this.