Addresses:  CPS-338 - Getting issue details... STATUS

Goal

The following operations are expected to be supported by CPS core

• Create a list node (add multiple children) under existing parent node;
  adding a list with a single value is already supported
• Delete a list node – removing all the data nodes which belong to specified list node;
  current implementation allows only removal one entry per request; full xpath to node is required
• Replace a list node – the operation which is a combination of delete then create operations
  described above

It's an assumption the list node cannot be a root level element, so the parent data node is always expected.

Single node vs multiple nodes

Data parsing context

On data conversion from String to DataNode object there is an intermediate stage of data being represented as 
a NormalizedNode instance which is a Yang Tools library artifact. The JSON String to NormalizedNode conversion
then followed by NormalizedNode to DataNode conversion.

These data structures are different.

While list node element is a single node within a NormalizedNode structure, on transformation to DataNode
the original list node wrapper is omitted (as containing no actual data) and list elements became a nodes belonging
to upper level parent node.

In a context of a data fragment the single root level node became a collection of nodes after transformation,
so all the subsequent operations require to be performed using a collection of nodes, not the single one.

In current implementation the CPS conversion to DataNode always returns single node result even if multiple
data nodes were built. In order to support operations with list node elements (as single entity) the functionality
require to be updated (fixed).

Related:  CPS-358 - Getting issue details... STATUS

Same API/SPI usage context

In current implementation all the non-read operations are taking as input single data node.

In order to support multiple data nodes as input it requires either  an existing methods signature update
or new methods which will serve list data node.

Below is an example of SPI method signatures update in order to support backward compatibility

// before
void replaceDataNodeTree(@NonNull String dataspaceName, @NonNull String anchorName, @NonNull DataNode dataNode);	

// after
void replaceDataNodeTree(@NonNull String dataspaceName, @NonNull String anchorName, @NonNull DataNode ... dataNode);

cons: despite usage of same methods the actual logic for processing single node significantly differs from the one 
which is required to process multiple data nodes, as result 

• the logic split will be required within a method itself, adding complexity to both the implementation
  and the testing
• the invocation logic requires to be updated as well, causing extra complexity to caller logic as well

While benefit of this approach is negligible the suggestion is to provide separate API/SPI methods for operations with list-node elements.

Same REST API usage context

Using same REST API also seems not reasonable.

As example there is a replace (PUT) operation for a data fragment with following inputs (excluding dataspace and anchor):

• parent node xpath
• data fragment as JSON 

// xpath=/test-tree
// request body:
{
	"branch": {[
        "name": "Branch",
        "nest": {
             "name": "Nest"
        } 
	]}
}

The case became uncertain because it's unclear what the action is expected exactly:

• replace an existing data node with xpath /test-tree/branch[@name='Branch']
  or throw an exception if record with such xpath does not exist
• replace the list node content (assumes all prior entries removal) with provided data

so there should be additional parameter to clarify which exact behavior is requested.

Any additional parameter (even optional one) leads to API/SPI for service level to be modified
in order to handle this extra parameter. It also leads to logic complication as described above.

From client perspective the additional parameter is same impact/effort as new entry point.

Suggested new entry points to be used for list-nodes only like below

/dataspaces/{dataspaceName}/anchor/{anchorName}/list-node

Implementation Proposal

Create list-node with one or more elements

Implement the functionality to support multiple nodes addition using data fragment with list-node as a root element.

REST layer (incl openapi update)

• uri:
  • (CPS) POST /dataspaces/{dataspaceName}/anchor/{anchorName}/list-node
  •  (NCMP) POST /cm-handle/{cmHandle}/list-node
• parameters:
  • xpath - parent node xpath (mandatory)
  • JSON data fragment via request body
• response 201 on success

Service layer

• parse JSON string into collection of DataNode objects

Persistence layer

• find parent node by parent node xpath (throw not found exception if absent)
• add all provided elements to parent node
• persist (throw already exists exception on unique constraint violation)

Delete list-node content (all existing elements)

Implement the functionality to support multiple nodes removal using list-node xpath.

REST layer (incl openapi update)

• uri:
  • (CPS) DELETE /dataspaces/{dataspaceName}/anchor/{anchorName}/list-node
  •  (NCMP) DELETE /cm-handle/{cmHandle}/list-node
• parameters:
  • xpath - list node xpath (same as list-node element but with no key attribute definition)
    i.e. /root/parent/list-node
• response 204 on success

Service layer

• validate xpath referenced list-node element (?)

Persistence layer

• delete all by dataspace and anchor and xpath starts with provided xpath to list-node (this includes all children as well)

Replace list-node content

Implement the functionality to support multiple nodes replacement using data fragment with list-node as a root element.

REST layer (incl openapi update)

• uri:
  • (CPS) PATCH /dataspaces/{dataspaceName}/anchor/{anchorName}/list-node
  •  (NCMP) PATCH /cm-handle/{cmHandle}/list-node
• parameters:
  
  • xpath - parent node xpath (mandatory)
  • JSON data fragment via request body
• response 204 on success

Service layer

• parse JSON string into collection of DataNode objects

Persistence layer

• extract list-node xpath identifier from data nodes provided
• find parent node by parent node xpath (throw not found exception if absent)
• remove all children matching (starting with) list-node xpath identifier
• add all provided elements to parent node
• persist

Proposal