You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 46 Next »

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:

  1. Should follow ONAP or wider best practice
  2. Documented on ONAP Wiki
  3. Discussed and agreed within CPS Team
  4. Discussed and agreed with wider community


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

  1. Models (add, list)
  2. Data (CRUD)
  3. 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

1Should 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)
2Input 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:

  1. Using IDs would have some performance advantage
  2. Using the ID seems natural in some cases
  3. Using IDs would allow for 'renaming' where possible

Cons:

  1. Using ID would mean client has to get/cache ID's all the time.
  2. Supporting both names and ID will lead to 'duplicate' methods in Java API and REST API
  3. Using a meaningless ID for Module instead for namespace & revision could lead to issues when debugging (only logs with IDs available)

Other considerations:

  1. The Java API follow the REST API. If the rest API is using names then the java API should also use names.
  2. Create methods should return the (id of the) objects created. If the module already exists, an exception should be thrown.
  3. 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. 
  4. OSS RC does NOT use IDs for models
  5. OSS RC Does DB Generated ID for objects (fragments)
  6. Need separate decision for
    1. Dataspace
    2. Module Set
    3. Module
    4. Anchor
    5. Fragment  

04/11/12 Team meeting notes - Niamh, Toine, Rishi, Tony

We should not expose internal DB ID for dataspace, module set, module, anchor or fragment. 

DB ids should be fully encapsulated. Exposure of DB ids to clients limits freedom in the future.

We do not want to expose them for the following reasons:

  • Database Migration

Database technology uplift/swap out will not guarantee that ids will be immutable. Any client that uses DB ids would be broken.

I can see this being quite important for ONAP trails going to commercially supported ONAP deployments.

  • Database Optimization

We would like to reserve the right to change database ID's. You eliminate the option that will shuffle the ID's without impacting the client.

  • ID Persistence 

If there is a fragment that has restricted properties that can only be set at creation. This fragment will be identified by an xpath and internally by a DB id. An update of this (restricted) attribute will require a delete/create – this will change the DB id, but not the xpath.

If a client had cached (or otherwise stored) the DB id, then their use case would be broken

  1. Dataspace - Name will be provided by user
  2. Module Set -Name will be provided by user
  3. Module - Name will be provided by user
  4. 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.
  5. Fragment  - XPath is the correct unique identifier and will be added automatically




4Should a user be able to delete a dataspace, module ( (of the same revision), module set?
  1. Maybe only allow if no associated data exist e.g. all fragments using a module should be deleted before a module can be deleted.
  2. If the associated data still exists, an exception could be thrown (from REST API)

04/11/12 Team meeting notes - Niamh, Toine, Rishi, Tony

  • 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)
5Should a user be able to update/override (create again) dataspace, module (of the same revision), module set?
  1. 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'.

04/11/12 Team meeting notes - Niamh, Toine, Rishi, Tony

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!)

6Should we have one method with any type of xpath to handle both direct gets with a fully qualified xpaths (pointing to one unique node) and any type of more advanced xpath expression/querys (pointing to multiple nodes)? Theoretically this is possible but if might be confusing for the end user

alternative we could have more specialized metods like

getByXpath(String qualifiedXPath)

QueryByXPath(String xpathExpression)

And we could still consider an xpath builder pattern (like a query builder)

XPathBuilder.withChildOfType()

XapthBuilder.withAttributeValue()


7How should we specify which attributes we want when querying with xpaths?It often might be necessary to limit the number of attributes returned by queries.
8

Will we have separate methods to validate our modules or data?

Alternatively validate on submitting of data/modules (and throw validation exception if needed)



9

The parser has detailed exception classes instead of one exception with different messages, we need to ask ourselves if we want to have a similar pattern

See section on error handling.

Error Handling

Our options are: 

  1. Throw up parser exceptions as they are (to the client)
  2. Wrap them in a limited number of CPSValidation Exception (maybe even just one)
  3. Have our own detailed validation list of validation exception classes

If we throw up exceptions, these are the kind of exceptions thrown by the system currently.


#ClassDefinition Source
1

YangValidationException

Unchecked exception thrown if yang definition is not valid according to {YangModelBasicValidationListener}

ODL Yang Parser (Yang Model)
2

YangParseException

Unchecked exception thrown if unable to parse yang

ODL Yang Parser (Yang Model)
3

YangSyntaxErrorException

Exception thrown if yang syntax is invalid

ODL Yang Parser (Yang Model)
4

DataValidationException

Exception thrown when a the specified data is invalid

ODL Yang Parser (Yang Data)
5

LeafRefDataValidationFailedException


ODL Yang Parser (Yang Data)
6LeafRefPathSyntaxErrorException
ODL Yang Parser (Yang Data)
7

ModifiedNodeDoesNotExistException

Exception thrown when a proposed change fails validation before being applied into the Data Tree because tree node which child nodes are modified or written did not exist when transaction started and still does not exists when transaction is processed. Note if node existed in first place and was removed by other transaction, thrown exception should be ConflictingModificationAppliedException.

ODL Yang Parser (Yang Data)
8

ConflictingModificationAppliedException

Exception thrown when a proposed change fails validation before being applied into the Data Tree because the Data Tree has been modified in way that a conflicting node is present.

ODL Yang Parser (Yang Data)
9

MissingSchemaSourceException

Exception thrown when a the specified schema source is not available.

ODL Yang Parser (Yang Model)
10

SchemaResolutionException

Exception thrown when a Schema Source fails to resolve.

ODL Yang Parser (Yang Model)
11

SchemaValidationFailedException


ODL Yang Parser (Yang Model)
12

OperationFailedException

A general base exception for an operation failure.

?
13IOException
File handling
14AlreadyExistsException
Database duplicates


CPS provides the following interfaces:

Interface Name

Interface Definition

 Interface Capabilities

Model InterfaceBehavior interface that represents cps modules.
  1. Create a module set
  2. Add modules to a module set
  3. Read all modules
  4. Validate modules
  5. Upgrade a module set (individual module upgrade)
  6. Create a module set and validate it against a module reference (using a separate SPI)
Data Interface

Behavior interface that represents CPS data.

  1. Create a node under an anchor.
  2. Delete a dataspace
  3. Create a dataspace
  4. Create an anchor
  5. Read an anchor of a particular node
  6. Read an anchor in a namespace and dataspace
  7. Read all anchors for one dataspace
  8. Delete an anchor for a namespace in a dataspace
  9. Associate an anchor to a module set
  10. Associate an dataspace to a anchor
  11. Read all dataspaces
  12. Create a node under another node.
  13. Associate an a node to a anchor
Query InterfaceProvides the capability to query CPS data using XPaths.
  1. Read the parent of a node that matches an xpath expression
  2. Read all nodes under an anchor point
  3. Read the anchor of a node
  4. Read all nodes that match a schema node identifier
Query Builder InterfaceProvides the capability to query CPS data using restrictions from a query builder (see open issue 1).


  • No labels