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

Authors: Even Rouault

Contact: even dot rouault at spatialys.com

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 behavior 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 behavior 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 (Spatialys), and sponsored by 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