1.. _rfc-55: 2 3======================================================================================= 4RFC 55: Refined SetFeature() and DeleteFeature() semantics 5======================================================================================= 6 7Authors: Even Rouault 8 9Contact: even dot rouault at spatialys.com 10 11Status: Adopted, implemented in GDAL 2.0 12 13Summary 14------- 15 16This RFC refines the semantics of SetFeature() and DeleteFeature() so as 17to be able to distinguish nominal case, attempts of updating/deleting 18non-existing features, from failures to update/delete existing features. 19 20Rationale 21--------- 22 23Currently, depending on the drivers, calling SetFeature() or 24DeleteFeature() on a non-existing feature may succeed, or fail. It is 25generally not desirable that those functions return the OGRERR_NONE 26code, as in most situations, it might be a sign of invalid input. 27Therefore the OGRERR_NON_EXISTING_FEATURE return code is introduced so 28that drivers can inform the calling code that it has attempted to update 29or delete a non-existing feature. 30 31Changes 32------- 33 34#define OGRERR_NON_EXISTING_FEATURE 9 is added to ogr_core.h 35 36Updated drivers 37~~~~~~~~~~~~~~~ 38 39The following drivers are updated to implement the new semantics: 40PostgreSQL, CartoDB, SQLite, GPKG, MySQL, OCI, FileGDB, Shape, MITAB 41 42Note: MSSQL could also likely be updated 43 44Caveats 45~~~~~~~ 46 47The behavior of the shapefile driver is a bit particular, in that, its 48SetFeature() implementation accepts to recreate a feature that had been 49deleted (and its CreateFeature() implementation ignores any set FID on 50the passed feature to append a new feature). So 51OGRERR_NON_EXISTING_FEATURE will effictively been returned only if the 52FID is negative or greater or equal to the maximum feature count. 53 54SWIG bindings (Python / Java / C# / Perl) changes 55------------------------------------------------- 56 57OGRERR_NON_EXISTING_FEATURE is added. All OGRERR_xxxx constants are 58exposed to the Python bindings 59 60Utilities 61--------- 62 63No impact 64 65Documentation 66------------- 67 68Documentation of SetFeature() and DeleteFeature() mentions the new error 69code. MIGRATION_GUIDE.TXT updated with mention to below compatibility 70issues. 71 72Test Suite 73---------- 74 75The test suite is extended to test the modified drivers. test_ogrsf also 76tests the behavior of drivers updating/deleting non-existing features. 77 78Compatibility Issues 79-------------------- 80 81Code that expected update or deleting of non-existing features to 82succeed will have to be updated. 83 84Implementation 85-------------- 86 87Implementation will be done by Even Rouault 88(`Spatialys <http://spatialys.com>`__), and sponsored by `LINZ (Land 89Information New Zealand) <http://www.linz.govt.nz/>`__. 90 91The proposed implementation lies in the 92"rfc55_refined_setfeature_deletefeature_semantics" branch of the 93`https://github.com/rouault/gdal2/tree/rfc55_refined_setfeature_deletefeature_semantics <https://github.com/rouault/gdal2/tree/rfc55_refined_setfeature_deletefeature_semantics>`__ 94repository. 95 96The list of changes: 97`https://github.com/rouault/gdal2/compare/rfc55_refined_setfeature_deletefeature_semantics <https://github.com/rouault/gdal2/compare/rfc55_refined_setfeature_deletefeature_semantics>`__ 98 99Voting history 100-------------- 101 102+1 from from DanielM, HowardB, JukkaR and EvenR 103