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