CCSDK-2871 DP: Long-term Java API(s) - DRAFT

Introduction

Although the PoC will only implement a few of the possible Java API methods it is important to have a good detailed view of the structure and naming of this interface going forward and document it.

Acceptance Criteria for Proposed Java Interface:

Should follow ONAP or wider best practice
Documented on ONAP Wiki
Discussed and agreed within CPS Team
Discussed and agreed with wider community

Currently we are considering 3 'separated' Java APIs or 'groups' of methods:

Models (add, list)
Data (CRUD)
Queries

Jira Ticket:

CCSDK-2871 - Getting issue details... STATUS

Jira Backlog:

https://jira.onap.org/secure/RapidBoard.jspa?rapidView=223&view=planning.nodetail&selectedIssue=CCSDK-2912&issueLimit=100

Gerrit Review

https://gerrit.nordix.org/#/c/onap/ccsdk/features/+/6477/

External Resources

https://wiki.onap.org/display/DW/Data+Representation

https://wiki.onap.org/display/DW/Interface+style

Open Issues/Decisions

#	Description	Details	Decisions
1	Should the java interface take in one (JSON) objects (like REST interface) or a few individual fields in a signature?	for Node attributes (Fragments) in our DB we will use a 'glorified' Map to store these and pass them on through the layers as a single object For API methods that require 2-4 parameters there is no need to create separate objects	Payload will be glorified map For non payload parameters, if there is more than 3/4 they might get encapsulated in an object. (to be decided on a case by case basis)
2	Input streams and/or files to take in large amounts of data like yang models?	Input streams are more generic Overloading of API to support both leads bloated interface	03/11/12 Team meeting Niamh, Toine, Rishi, Aditya, Bruno, Phillipe We have decided to use (buffered) input streams.
3	API uses (generated) ID's or customer provided names? If names are used should we return IDs at all?	03/11/12 Team meeting notes - Niamh, Toine, Rishi, Aditya, Bruno, Phillipe Pros: Using IDs would have some performance advantage Using the ID seems natural in some cases Using IDs would allow for 'renaming' where possible Cons: Using ID would mean client has to get/cache ID's all the time. Supporting both names and ID will lead to 'duplicate' methods in Java API and REST API Using a meaningless ID for Module instead for namespace & revision could lead to issues when debugging (only logs with IDs available) Other considerations: The Java API follow the REST API. If the rest API is using names then the java API should also use names. Create methods should return the (id of the) objects created. If the module already exists, an exception should be thrown. All ID's generated should be in the response. If we return the ID we also need methods to use the ID. If we update the java API to use ID, we should also update the REST API. OSS RC does NOT use IDs for models OSS RC Does DB Generated ID for objects (fragments) Need separate decision for Dataspace Module Set Module Anchor Fragment	We should not expose internal DB ID for dataspace, module set, module, anchor or fragment. We do not want to expose them for the following reasons: Migration Database Optimization We would like to reserve the right to change database ID's. You eliminate the option that will shuffle the ID's. ID Persistence If you delete something and then re create it, if its a fragment inside a network function, it will not have the same ID. Dataspace - Name will be provided by user Module Set -Name will be provided by user Module - Name will be provided by user Anchor - can have multiple ID's (will be mapped to entities outside of CPS). We will return URI for an anchor. We will use a generic key value pair map. We will do a check to make sure it is unique and return URI for anchor. Fragment - XPath is the correct unique identifier and will be added automatically
4	Should a user be able to delete a dataspace, module ( (of the same revision), module set?	Maybe only allow if no associated data exist e.g. all fragments using a module should be deleted before a module can be deleted. If the associated data still exists, an exception could be thrown (from REST API)	We want to able to delete an anchor We should be able to delete a dataspace - un deploying use case We need to be able to delete the module and module sets associated with the dataspace. Rest API (or any other possible user interface) will have safety checks before deletion: Dataspace - do not delete if any module(set)s are still associated Module Set - do not deleted if any modules (or possible anchors) associated Module - do not delete if any any anchor associated with it Anchor - delete allowed from REST (will delete everything underneath) Fragment - delete allowed from REST (will delete everything underneath)
5	Should a user be able to update/override (create again) dataspace, module (of the same revision), module set?	Can add business logic to check on create if it already exists. If it exists (and is the same) we do not create it (silently ignore, this is called 'idempotent'.	For now we are not going to be idempotent but we may consider it in the future. Need to be document clearly as part of Java API proposal (i.e in this wiki!)

CPS provides the following interfaces:

Interface Name	Interface Definition	Interface Capabilities	Consumed Models
Model Interface	Behavior interface that represents cps modules.	Create a module set Add modules to a module set Read all modules Validate modules Upgrade a module set (individual module upgrade) Create a module set and validate it against a module reference (using a separate SPI)	Yang models that are broken into fragments.
Data Interface	Behavior interface that represents CPS data.	Create a node under an anchor. Delete a dataspace Create a dataspace Create an anchor Read an anchor of a particular node Read an anchor in a namespace and dataspace Read all anchors for one dataspace Delete an anchor for a namespace in a dataspace Associate an anchor to a module set Associate an dataspace to a anchor Read all dataspaces Create a node under another node. Associate an a node to a anchor
Query Interface	Provides the capability to query CPS data using XPaths.	Read the parent of a node that matches an xpath expression Read all nodes under an anchor point Read the anchor of a node Read all nodes that match a schema node identifier
Query Builder Interface	Provides the capability to query CPS data using restrictions from a query builder (see open issue 1).