Cayenne entity ID part represented by a DB column to be prefixed with "db:"

[andrus]

Background - ID representation in Agrest

Entities can have single-value and multi-value IDs. Single-value id is represented in JSON as "id":val. Multi-value - as "id":{"p1":v1, "p2":v2}. This representation is used for both request bodies (POST, PUT), and responses (GET, POST, PUT).

Problem

This task is concerned with a specific case - multi-value ID representation with Cayenne backend, when one or more values in the ID map are not present as object properties. In this case Cayenne uses names of DB columns as keys in the ID map: "id":{"col1":v1, "col2":v2}.

This is both confusing, and can potentially (though unlikely) cause naming conflicts between Java properties and DB column names in the same id map. Additionally, since 5.0 (per #520) attributes and "id part" attributes no longer maintain "path expression" property separate from the attribute/id part name. So the name itself should contain sufficient information for the backend to make sense of it.

Solution

While we can keep building workarounds in the Cayenne backend, I think we should change the encoding of the column-based id parts to be in a form of Cayenne DB expression, i.e. prefixed with "db:" - "id":{"db:col1":v1, "db:col2":v2}. This will add both visual clarity and disambiguate the ID structure for the framework.

Upgrade Notes

This change only affects Cayenne entities that have a multi-column ID, and only a subset of id properties that are not mapped as object properties. Property names that are column names will now be prefixed with "db:". E.g.: "id":{"db:col1":v1, "db:col2":v2, "prop":v3}.

On the client this affects the following requests:

• Those that submit updates for entities with such ids
• Those that parse responses with such ids for individual id values (instead of treating the ID as opaque)

On the server this affects the following user-facing APIs:

• SelectBuilder.byId(Map)
• SelectBuilder.parent(Class,Map,String)
• UpdateBuilder.parent(Class,Map,String)
• DeleteBuilder.parent(Class,Map,String)