.. _versioning_implementation_samplecalls: Versioning WFS - Sample calls ============================== The sample versioning configuration contains a set of sample calls that can be performed against the versioning datastore to try out its functionality. Here are the calls with some narrative explaining them. Assess initial situation ------------------------ All of the calls hit the topp:archsites feature type. This call extract two of the three feature we're going to modify with the transaction. .. code-block:: xml This is a standard WFS GetFeature, but you may have noticed that the service hit is "WFSV". Also, if you run the request you'll notice archsites.25 is not there, because we're going to create it with the next request. Transaction ----------- This is a standard WFS transaction, versioning is totally transparent (that is, this transaction call is exactly the same you would perform on a standard WFS, the difference is that the backend will record the change instead of just applying it to the data). .. code-block:: xml 2 Alien crash site 604000,4930000 str1 Signature Rock, updated The result is: .. code-block:: xml Grabbing the versioning log --------------------------- The following call retrieves the change log for the topp:archsites feature type: .. code-block:: xml resulting in a single entry (the entries from 1 to 6 report the operations needed to version enable the tables). Note how the transaction handle was used as the commit message, and also the fact the user is unknown, because in this demo the http basic authentication was not used. +----------+--------------+--------------+-------------------------------+ | Revision | Author | Date | Message | +==========+==============+==============+===============================+ |7 | anonymous |10/10/07 9.47 | Updating Signature rock label | +----------+--------------+--------------+-------------------------------+ Alternatively, the GetLog result can be encoded in GML. GetFeature with version support Let's do a before and after comparison. This first GetFeature tries to retrieve the value of the features at revision 1. .. code-block:: xml This one retrieves the results at revision 1, that is, before the transaction occurred. We can see features archsites.1 and archsites.2, whilst archsites.26 is not there (it has been created at revision 7). .. code-block:: xml 591950,4914730 593493,4923000 1 Signature Rock 593493,4914730 2 No Name 591950,4923000 Querying for revision 7 offers a different result: .. code-block:: xml .. code-block:: xml 593493,4914730 604000,4930000 2 Alien crash site 604000,4930000 1 Signature Rock, updated 593493,4914730 Here we can see archsites.2 has been removed (deleted during the transaction) and archsites.26 appears. GetDiff ------- Diff returns the difference between two revisions, eventually it's possible to specify a filter to gather the diff concerning a specific feature set. Also notice that the output format is HTML, but if you don't specify it, you'll get the log encoded as a WFS Transaction (the transaction that applied to the initial revision bring you to the specified destination revision). .. code-block:: xml The output, in human readable HTML format, is:: Feature type 'archsites', diff from version 1 to version CURRENT Feature archsites.26, inserted, feature content: * cat: 2 * str1: Alien crash site * the_geom: POINT (604000 4930000) Feature archsites.2, deleted, old feature content: * cat: 2 * str1: No Name * the_geom: POINT (591950 4923000) Feature archsites.1, updated, modified attributes: +-----------+------------------+------------------------+ | Attribute | Value at 1 | Value at CURRENT | +===========+==================+========================+ | str1 | Signature Rock |Signature Rock, updated | +-----------+------------------+------------------------+ If no output format is specified, the GetDiff will return a WFS transaction, that is, the actions needed to turn the features from version 1 to version CURRENT. The GetDiff can also work backwards, that is, one could specify toFeatureVersion < fromFeatureVersion, this would return a reverse diff, which seen as a transaction, is the set of command needed to rollback the changes. Yet, it's advisable to use the specific Rollback element for actually performing rollbacks, because it guarantees deleted features are restored with the original feature id (perfoming the transaction returned by a backwards diff would create a new feature id instead). Rollback -------- Versioning WFS introduces a new transaction element, Rollback, that can be used to undo changes performed between two revisions, eventually limiting the rollback to features touched by a specific user, or satisfying a specific filter. .. code-block:: xml handle="Rolling back previous changes"> and the result would be: .. code-block:: xml Versioning aware clients and transactions ----------------------------------------- Versioning aware clients should try to handle updates keeping the possibily of conflicts in mind. A conflict occurrs if the same feature is modified by two users in the same time frame. Suppose the first one managed to commit its changes. The second one should try to avoid overwriting the first user changes, and instead be notified that it does not have the latest revision. In that case, the client should first update (by getting a diff), handle the eventual conflict locally, and then try to commit again. The following example shows a transaction that should fail, because the client declares of being at a revision number that's no more the latest revision: .. code-block:: xml handle="Trying an update with wrong version"> str1 You won't see me updated