Table of Contents |
---|
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.
...
- Models (add, list)
- Data (CRUD)
- Queries
Jira Ticket:
Jira | ||||||||
---|---|---|---|---|---|---|---|---|
|
Jira Backlog:
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? |
|
| |||||||||||||||
2 | Input streams and/or files to take in large amounts of data like yang models? |
| 03/11/12 20 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 20 Team meeting notes - Niamh, Toine, Rishi, Aditya, Bruno, Phillipe
Cons:
Other considerations:
| 04/11/12 Team 20 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 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.
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.
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
| |||||||||||||||
4 | Should a user be able to delete a dataspace, module ( (of the same revision), module set? |
| 04/11/12 Team 20Team meeting notes - Niamh, Toine, Rishi, Tony
| |||||||||||||||
5 | Should a user be able to update/override (create again) dataspace, module (of the same revision), module set? |
| 04/11/12 Team 20 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!) | |||||||||||||||
6 | How should we specify attributes? | 1) can it be done by xpaths 2) additional parameters 3) part of query builder? | 11/11/20 Team meeting notes - Niamh, Toine, Aditya, Tony, Ruslan, Claudio We will use an optional parameter (suggested name outputSpecification) to specify the leaf(s) (attributes). All queries will return DataNode(s). If you do not specify leaf(s), all leaves will be returned. | |||||||||||||||
7 | Should we have one method with any type of | xpathpaths to handle both direct gets with a fully qualified | xpathspaths(pointing to one unique | nodeDataNode) and any type of more advanced | xpathpaths expression/querys (pointing to multiple | nodesDataNodes)? Theoretically this is possible but if might be confusing for the end user | alternative we could have more specialized | metods methods like | getByXpathgetDataNode(String | qualifiedXPathcpsPath) | QueryByXPathqueryDataNodes(String | xpathExpressioncpsPathQuery) And we could still consider an | xpath path builder pattern (like a query builder) | XPathBuilderPathBuilder.withChildOfType() | XapthBuilderPathBuilder.withAttributeValue() | 7 | How 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.11/11/20 Team meeting notes - Niamh, Toine, Aditya, Tony, Ruslan, Claudio We decided to use key instead of ID. We have decided to split the behavior into different methods e.g getDataNode(String cpsPath) queryDataNodes(String cpsPathQuery) We do intend to use a query builder too and it will be extended in step with any progress on the xpath query supported functionality |
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) | 11/11/20 Team meeting notes - Niamh, Toine, Aditya, Tony, Ruslan, Claudio We intend to publish validation in a separate java library. We will do validation on write to ensure whatever is being stored in the database is valid and will give the user a fast failure. We will not have separate validation methods on the main Java API. | ||||||||||||||||
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:
...
11/11/20 Team meeting notes - Niamh, Toine, Aditya, Tony, Ruslan, Claudio We intend to have our |
...
own detailed validation list of validation exception classes |
...
. We will have an exception class hierarchy like below:
| |||
10 | Order of parameters | When applicable the following order should be applied
| |
11 | Responsibility of module sets will be clarified in a meeting | Options are:
|
|
Error Handling
Exception Class Hierarchy:
- CPSValidationException
- ModelValidationException
- SpecificException1
- SpecificException2
- DataValidationException
- SpecificException3
- SpecificException4
- PathValidationException
- SpecificException5
- ModelValidationException
Expand | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
...
|
...
|
...
|
Interface Proposal
can be found at : Interface Proposal for CPS
Proposed grouping of interface methods:
Interface NameInterface Definition | Interface Capabilities | |
---|---|---|
Model Interface | Behavior interface that represents cps modules. |
|
Data Interface | Behavior interface that represents CPS data. |
|
Query Interface | Provides the capability to query CPS data using XPaths. |
| Query Builder Interface | Provides the capability to query CPS data using restrictions from a query builder (see open issue 1).
ModuleStoreService |
| |
CpsAdminService |
| |
DataService |
| |
|
|
Java Doc
View file | ||||
---|---|---|---|---|
|