Public Group API prepared for soon-to-arrive Group::remove_table() [BREAKS PUBLIC API]

[kspangsege]

The public Group API has been heavily upgraded to fix old issues, and to properly support the soon-to-be-added Group::remove_table().

The most important change is that Group::get_table() no longer creates tables that are not already in the group. Group::get_table() will now return null if there is no table in the group with the specified name.

New tables are added with one of the new functions Group::add_table() or Group::get_or_add_table().

These changes will require a careful examination and update of all our language bindings, and it is not likely that the compiler is going to help find the places where changes are needed.

A simpleminded approach to updating a language binding would be to find every occurrence of a call to Group::get_table() and replace it with a call to Group::get_or_add_table(). This will very likely work, because Group::get_or_add_table() has virtually the same meaning as Group::get_table() had before.

Here is a detailed account of the publicly visible changes:

• Group::has_table<T>() removed, because it had awkward and incongruous semantics, and could not be efficiently implemented.
• Group::find_table() added as a way of mapping a table name to the index of table in the group.
• Group::get_table(index) and Group::get_table_name() now throw InvalidArgument if the index is invalid.
• Group::get_table(name) no longer creates a table when none exist with the specified name. Its semantics has also changed in several other ways.
• Group::add_table() and Group::get_or_add_table() added.
• Renaming LangBindHelper::bind_table_ref() to LangBindHelper::bind_table_ptr(), and LangBindHelper::unbind_table_ref() to LangBindHelper::unbind_table_ptr().
• There is now two versions of LangBindHelper::get_table(), one whose argument is a table name, and one whose argument is the group-level index. Neither one is exactly like that original version of LangBindHelper::get_table().
• LangBindHelper::add_table() and LangBindHelper::get_or_add_table() added.
• WriteTransaction::add_table() and WriteTransaction::get_or_add_table() added.
• Exception type ResourceAllocError eliminated, as there was no good reason for keeping it (it had no clear role).

@finnschiermer @astigsen @rrrlasse

[kspangsege]

Please review

[bmunkholm]

Before merging we need to discuss the integration of this in bindings.

I really don't like to change the semantics of existing methods without getting some compiler assistance to detect it. I'm not aware if this has been discussed in advance of all these changes? Never the less, I've always argued for this more clear meaning of get_table and get_or_add_table..

[kspangsege]

I understand your concern with respect to the lack of compiler assistance. On the other hand, using grep -rnw get_table, and being just a little systematic/careful, will suffice for a reliable update. I strongly recommend that we go ahead with this, as it is a significant improvement of the group API, and even more so when considering coming additions to the group API.

If you want my help, I can general a "high fidelity" list of places where Group::get_table() is called, for Cocoa and Java, then you can consider in each case whether the right new function to call is get_table(), add_table(), or get_or_add_table().

And remember that it is always safe to substitute get_or_add_table(), because it has the same function as Group::get_table() had before, but it is not always the optimal choice, given the new possibilities.

[bmunkholm]

Let's consider if we need to make a "binding conversion note"

[kspangsege]

I have prepared a PR to upgrade the Cocoa binding: realm/realm-swift#785

[kspangsege]

I have prepared a PR to upgrade the Java binding: realm/realm-java#324

[kspangsege]

I have prepared a PR to upgrade the Python binding: Tightdb/tightdb_python#196

[kspangsege]

Please review

[kspangsege]

Please review