Document legacy CPS Path functionality

Issue-ID: CPS-334

Signed-off-by: ToineSiebelink <toine.siebelink@est.tech>
Change-Id: Ib5266c7b30097661d97f8a499eaddc738dda0539

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 a2c7a09..24aa3d4 100644 (file)
--- 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 (file)
index 0000000..451c24f
--- /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. <https://www.w3.org/TR/2017/REC-xpath-31-20170321/>`_
+
+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
+
+    <shops>
+       <bookstore name="Chapters">
+         <bookstore-name>Chapters</bookstore-name>
+         <categories code="1" name="SciFi" numberOfBooks="2">
+           <books>
+             <book name="Space Odyssee"/>
+             <book name="Dune"/>
+           </books>
+        </categories>
+        <categories code="2" name="Kids" numberOfBooks="1">
+           <books>
+             <book name="Matilda"/>
+           </books>
+        </categories>
+       </bookstore>
+    </shops>
+
+**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>/<target-node>/[@<leaf-name>=<leaf-value>]``
+  - ``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><target-node>``
+  - ``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 4f1bf1e..c7691ae 100755 (executable)
--- a/docs/design.rst
+++ b/docs/design.rst
@@ -29,3 +29,9 @@ Specification can be accessed using following URI:
 .. code-block:: bash
 
   “http://<hostname>:<port>/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 f389a67..57ab3b9 100755 (executable)
--- 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 74ee8ec..6b15abc 100644 (file)
--- 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`.