= RFC 55: Refined SetFeature() and DeleteFeature() semantics =

Authors: Even Rouault [[BR]]
Contact: even dot rouault at spatialys.com [[BR]]
Status: Adopted, implemented in GDAL 2.0

== Summary ==

This RFC refines the semantics of SetFeature() and DeleteFeature() so as
to be able to distinguish nominal case, attempts of updating/deleting
non-existing features, from failures to update/delete existing features.

== Rationale ==

Currently, depending on the drivers, calling SetFeature() or DeleteFeature()
on a non-existing feature may succeed, or fail. It is generally not desirable
that those functions return the OGRERR_NONE code, as in most situations, it
might be a sign of invalid input. Therefore the OGRERR_NON_EXISTING_FEATURE
return code is introduced so that drivers can inform the calling code that it
has attempted to update or delete a non-existing feature.

== Changes ==

#define OGRERR_NON_EXISTING_FEATURE 9 is added to ogr_core.h

=== Updated drivers ===

The following drivers are updated to implement the new semantics:
PostgreSQL, CartoDB, SQLite, GPKG, MySQL, OCI, FileGDB, Shape, MITAB

Note: MSSQL could also likely be updated

=== Caveats ===

The behaviour of the shapefile driver is a bit particular, in that, its
SetFeature() implementation accepts to recreate a feature that had been
deleted (and its CreateFeature() implementation ignores any set FID on the
passed feature to append a new feature). So OGRERR_NON_EXISTING_FEATURE will
effictively been returned only if the FID is negative or greater or equal
to the maximum feature count.

== SWIG bindings (Python / Java / C# / Perl) changes ==

OGRERR_NON_EXISTING_FEATURE is added. All OGRERR_xxxx constants
are exposed to the Python bindings

== Utilities ==

No impact

== Documentation ==

Documentation of SetFeature() and DeleteFeature() mentions the new error code.
MIGRATION_GUIDE.TXT updated with mention to below compatibility issues.

== Test Suite ==

The test suite is extended to test the modified drivers. test_ogrsf also
tests the behaviour of drivers updating/deleting non-existing features.

== Compatibility Issues ==

Code that expected update or deleting of non-existing features to succeed will
have to be updated.

== Implementation ==

Implementation will be done by Even Rouault ([http://spatialys.com Spatialys]),
and sponsored by [http://www.linz.govt.nz/ LINZ (Land Information New Zealand)].

The proposed implementation lies in the "rfc55_refined_setfeature_deletefeature_semantics" branch of the
https://github.com/rouault/gdal2/tree/rfc55_refined_setfeature_deletefeature_semantics repository.

The list of changes: https://github.com/rouault/gdal2/compare/rfc55_refined_setfeature_deletefeature_semantics

== Voting history ==

+1 from from DanielM, HowardB, JukkaR and EvenR