Table of Contents |
---|
CPS Delta feature Exceptions
Where ever possible the Delta Feature will throw the same exceptions as defined in CPS core. If any new exception for the delta feature are required the following will be updated here.
Issues & Decisions
# | Issue | Notes | Decision |
---|---|---|---|
1 | Add or Delete leaves (optional leaves) handle as UPDATE or ADD/DELETE ? | The delta report proposed follows the Json Patch format of representing the differences between 2 json. Going by the general convention, referring RFC-6902:
| Add/Delete as per notes on the left |
2 | How to handle multiple changes at different levels? | Example:
There could be Many more complex scenarios.... Replied below | |
3 | More scenarios need to be explored and documented in detail. Such as handling arrays within a json, handling child/grandchild changes. |
HTTP response codes for Delta API
The proposed API will be part of the CPS Data Interface. The following response codes will be returned by the API:
# | Sub Interface | Method | Scenario | HTTP Response codes to be implemented | Notes |
---|---|---|---|---|---|
1 | Data | Proposed API: GET- /v1v2/dataspacedataspaces/{dataspace-name}/delta?anchor1=anchors/{anchor-name}/delta?anchor2={anchor-name}?xpath={xpath}&descendants={descendants} Proposed method name: <decision pending> getDeltaByDataspaceAndAnchors() | Generate a delta report between 2 anchors in a given dataspace. |
| AnchorNotFoundException should provide the name of missing anchor from the given two anchor names. |
Request parameters:
Parameter name | In | Required | Description |
---|---|---|---|
dataspace-name | Path | Yes | Dataspace name |
anchor1 | Query | Yes | First Anchor Name/Reference Anchor |
anchor2 | Query | Yes | Second Anchor Name |
xpath | Query | Yes | xpath of the node |
descendants | Query | No | Level of descendants for delta comparison. |
Response Body/Delta Report Format
Code Block | ||||
---|---|---|---|---|
| ||||
[ { "action": "ADD", "xpath": "/bookstore/categories/[@code=3]", "payload": { "code": 3, "name": "kidz" } }, { "action": "DELETE", "xpath": "/bookstore/categories/[@code=1]", "payload": { "code": 1, "name": "Fiction" } }, { "action": "UPDATE", "xpath": "/bookstore/categories/[@code=2]", "payload": { "name": "Comic" } } ] |
Mechanism for Delta generation
Gliffy Diagram | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
Anchor | ||||
---|---|---|---|---|
|
Format/Conventions to be used for Delta Report (not finalized)
There are several ways of representing the differences between JSON but here we discuss the JSON Patch format of representing these differences because the proposed Delta report closely represents JSON patch with a few differences. This approach focuses in producing another JSON document that represents the differences between the two JSON's that have been compared.
JSON Patch
JSON Patch defines a JSON document structure for expressing a sequence of operations to apply to a JavaScript Object Notation(JSON) document; it is suitable for use with the HTTP PATCH method. The "application/json-patch+json" media type is used to identify such patch documents.
...
Code Block | ||||
---|---|---|---|---|
| ||||
[ { "op": "test", "path": "/a/b/c", "value": "foo" }, { "op": "remove", "path": "/a/b/c" }, { "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] }, { "op": "replace", "path": "/a/b/c", "value": 42 }, { "op": "move", "from": "/a/b/c", "path": "/a/b/d" }, { "op": "copy", "from": "/a/b/d", "path": "/a/b/e" } ] |
Anchor | ||||
---|---|---|---|---|
|
Let's assume we have a data node having some leaf data, and this particular node happens to have multiple child nodes as well.
...
- Add/Delete/Update of leaves
- Add/Delete/Update of child nodes
Add/Delete/Update of leaves
if the leaves of a particular data node, having a unique xpath, are added/deleted/updated then it will be considered as an Update of the particular Data Node.
Add/Delete/Update of child/grandchild nodes
Now in this scenario we assume that a child/grandchild data node, having its unique xpath, has been added/deleted/updated. Then this operation should be considered as an addition/deletion/update of the particular child/grandchild data node at its particular level, rather than an update of parent node,
The reason for this being that the particular child/grandchild is in itself a unique data node and can be queried with its own xpath and hence any operation on the particular child/grandchild should be treated as an operation on the particular node rather than an operation on its parent.
Proposed Algorithm
The JSON data stored in CPS can be retrieved as Maps, And using this we can find the delta between two anchors retrieved as two separate Maps. The result can be stored in an JSON array with appropriate notations for action, xpath and payload. The following algorithm can be used to find the difference between the two maps and also recursively finds the difference between the child data nodes. The response is in form of a JSON Array which closely represents the JSON Patch format as described above.
Algorithm:
- Create an empty JSON Array, to store the result
- The JSON array will contain the following: action, xpath, payload as individual JSON objects each object representing a singular operation.
- Fetch the data from two anchors and store in two separate Maps
- Iterate over the entries of first map
- For each entry of first map, check if the key is present in second map.
- If the key is not found in second map, it means that the key-value pair has been removed from the second map. Create a JSON Object with DELETE action, the xpath to deleted node and payload. Add the Object to the JSON Array.
- If the key is present in the second map, compare the values associated with the keys in both maps.
- If the values are instance of Map, recursively call the comparision algorithm to compare all nested maps. Add all the necessary fields into a JSON object and put the object into the JSON Array
- If the values are not equal, it means the key-value pair was updated. Create a JSON Object with UPDATE action, the xpath to updated nodes and payload. Add the Object to the JSON Array.
- Iterate over the keys of second map and find the keys not present in first map. These keys were added as new entries. Create a JSON Object with ADD action, the xpath to added node and payload. Add the Object to the JSON Array.
- Return the JSON Array and the updates to Kafka events