Data Representation

Decision

Decision: Option A. Data will be represented as documents (REST) and or generic objects (glorified maps in Java)

Details

The data that is read from and written to the CPS must comply with a known format. This is relevant to both Java and REST interfaces. The choices here are to provide generic objects/documents, or highly typed (using model info).

What we discuss here is the CPSDataObject structure (see Interface style). The payload or object that is passed around and encapsulates request and response data.

This structure must provide:

context required for CPS to uniquely identify the data (node/object/row/table) to be accessed (CRUD);
the ability to read and write data (attributes/fields) locally – that may then be used in subsequent calls to the CPS
information about links and relationships that can be used in subsequent calls to the DPS (navigation and queries)

The CPS will be model driven. It will use the YANG language do drive how it stores information, and YANG models to validate and constrain data in line with design intent.

This question relates to the level to which the YANG model is visible in the payload.

I.e.: Will the CPSDataObject be be:

a hierarchy generated by the types found in the YANG models,
a generic structure based solely on the YANG language capabilities supported by the CPS

Option A

Generic objects/documents

The CPSDataObject will be a 'glorified' map -- not a basic map, but one level more concrete (in terms of abstractions). I.e. at the language level
Sample methods:

public class CPSDataObject extends Map {...}

CPSDataObject tree = cps.getTree(obj, level, filter)
List<CPSDataObject> refs = cps.getRefs(obj)
CPSDataObject parent = cps.getParent(obj)
List<CPSDataObject> children = cps.getChildren(obj)

filter: An XPath expression

YANG <-> Java type mapping: Mostly simple; UINT64 and IdentityRef (which has two strings) will require direction

Option B

Given an example of a object in YANG (from https://tools.ietf.org/id/draft-vassilev-netmod-network-bridge-01.html)

container bridge {
    container ports {
      list port {
        key "name";
        unique "index";
        leaf name {
          type string;
        }
        leaf index {
          type uint64;
        }
      }
    }
  }

Highly typed (using information in models). There is so much more to add to these classes, for example how to relate the class instance to the database record is deliberately not shown. The intention of the example is solely to illustrate the option for payload representation.

public class bridge extends Map {
	private List<port> ports;
	public List<port> get_ports() {...};
	public void set_ports() {...}
}
public class port extends Map {
	private String name;
	private long index;
	...
}

Discussion

For typed languages (such as Java) Option B requires code generation and class loading. Class loading leads to issues with deployment complexity.

Option A lends itself to a low cost transformation to and from a REST interface with simple JSON payload (with generic JSON schema).

Discussed Fri 17/June: Broad agreement with Option A. Discussion taken with Interface style Decision will be approved unless major objection Fri 24/June.