From 98c078768b2ee6c8ce1a910f42ce46845eacc2c1 Mon Sep 17 00:00:00 2001 From: ToineSiebelink Date: Tue, 20 Apr 2021 17:33:09 +0100 Subject: [PATCH] Document legacy CPS Path functionality Issue-ID: CPS-334 Signed-off-by: ToineSiebelink Change-Id: Ib5266c7b30097661d97f8a499eaddc738dda0539 --- .../spi/impl/CpsDataPersistenceServiceSpec.groovy | 7 +- docs/cps-path.rst | 93 ++++++++++++++++++++++ docs/design.rst | 6 ++ docs/index.rst | 4 +- docs/modeling.rst | 4 + 5 files changed, 108 insertions(+), 6 deletions(-) create mode 100644 docs/cps-path.rst diff --git a/cps-ri/src/test/groovy/org/onap/cps/spi/impl/CpsDataPersistenceServiceSpec.groovy b/cps-ri/src/test/groovy/org/onap/cps/spi/impl/CpsDataPersistenceServiceSpec.groovy index a2c7a0947..24aa3d41f 100644 --- a/cps-ri/src/test/groovy/org/onap/cps/spi/impl/CpsDataPersistenceServiceSpec.groovy +++ b/cps-ri/src/test/groovy/org/onap/cps/spi/impl/CpsDataPersistenceServiceSpec.groovy @@ -382,8 +382,9 @@ class CpsDataPersistenceServiceSpec extends CpsPersistenceSpecBase { and: result.stream().findFirst().get().xpath == expectedXPath where: 'the following data is used' - scenario | cpsPath || expectedXPath - 'fully unique descendant name' | '//grand-child-202' || '/parent-200/child-202/grand-child-202' - 'descendant name match end of other node' | '//child-202' || '/parent-200/child-202' + scenario | cpsPath || expectedXPath + 'fully unique descendant name' | '//grand-child-202' || '/parent-200/child-202/grand-child-202' + 'descendant name and parent' | '//child-202/grand-child-202' || '/parent-200/child-202/grand-child-202' + 'descendant name match end of other node' | '//child-202' || '/parent-200/child-202' } } diff --git a/docs/cps-path.rst b/docs/cps-path.rst new file mode 100644 index 000000000..451c24f39 --- /dev/null +++ b/docs/cps-path.rst @@ -0,0 +1,93 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +.. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING +.. _design: + + +CPS Path +######## + +.. toctree:: + :maxdepth: 1 + +Introduction +============ + +Several CPS APIs use the cps-path (or cpsPath in Java API) parameter. +The CPS Path parameter is used for querying xpaths. CPS Path is insprired by the `XML Path Language (XPath) 3.1. `_ + +This section describes the functionality currently supported by CPS Path. + +Sample Data +=========== + +The xml below describes some basic data to be used to illustrate the CPS Path functionality. + +.. code-block:: xml + + + + Chapters + + + + + + + + + + + + + + +**Note.** 'categories' is a Yang List and 'code' is its key leaf. All other data nodes are Yang Containers + +General Notes +============= + +- String values must be wrapped in quotation marks (U+0022) or apostrophes (U+0027). +- String comparisons are case sensitive. + +Supported Functions +=================== + +Get List Elements by Any Attribute Value +---------------------------------------- + +**Syntax**: ``//[@=]`` + - ``xpath``: The xpath to the parent of the target node including all ancestors. + - ``target-node``: The name of the (list) node which elements will queried. + - ``leaf-name``: The name of the leaf which value needs to be compared. + - ``leaf-value``: The required value of the leaf. + +**Examples** + - ``/shops/bookstore/categories[@numberOfBooks=1]`` + - ``/shops/bookstore/categories[@name="Kids"]`` + - ``/shops/bookstore/categories[@name='Kids']`` + +**Limitations** + - Only one list (last descendant) can be queried for a non-key value. Any ancestor list will have to be referenced by its key name-value pair(s). + - Only one attribute can be queried. + - Only string and integer values are supported (boolean and float values are not supported). + +**Notes** + - For performance reasons it does not make sense to query the list key leaf. If the key value is known it is beter to execute a get request with the complete xpath. + +Get Any Descendant +------------------ + +**Syntax**: ``//`` + - ``direct-ancestors``: Optional path to direct ancestors of the target node. This can contain zero to many ancestor nodes separated by a /. + - ``target-node``: The name of the (list) node from which element will be selected. If the target node is a Yang List he element needs to be specified using the key as normal e.g. ``categories[@code=1]``. + +**Examples** + - ``//book`` + - ``//books/book`` + - ``//categories[@code=1]`` + - ``//categories[@code=1]/books`` + +**Limitations** + - List elements can only be addressed using the list key leaf. diff --git a/docs/design.rst b/docs/design.rst index 4f1bf1ee1..c7691ae35 100755 --- a/docs/design.rst +++ b/docs/design.rst @@ -29,3 +29,9 @@ Specification can be accessed using following URI: .. code-block:: bash “http://:/v3/api-docs?group=cps-docket” + +CPS Path +======== + +Several CPS APIs use the cps-path (or cpsPath in Java API) parameter. +The CPS Path is described in detail in :doc:`cps-path`. diff --git a/docs/index.rst b/docs/index.rst index f389a6768..57ab3b9b0 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,7 +17,5 @@ CPS Documentation for the Honolulu-R8 Release architecture.rst design.rst modeling.rst - deployment.rst - user-guide.rst + cps-path.rst release-notes.rst - diff --git a/docs/modeling.rst b/docs/modeling.rst index 74ee8ec86..6b15abcfa 100644 --- a/docs/modeling.rst +++ b/docs/modeling.rst @@ -45,3 +45,7 @@ Data The data node position within a tree is uniquely identified by the node's unique **xpath** which can be used for partial data query. + +Querying + +- **CPS Path** is used to query data nodes. The CPS Path is described in detail in :doc:`cps-path`. -- 2.16.6