diff options
| -rw-r--r-- | cps-ri/src/test/groovy/org/onap/cps/spi/impl/CpsDataPersistenceServiceSpec.groovy | 7 | ||||
| -rw-r--r-- | docs/cps-path.rst | 93 | ||||
| -rwxr-xr-x | docs/design.rst | 6 | ||||
| -rwxr-xr-x | docs/index.rst | 4 | ||||
| -rw-r--r-- | docs/modeling.rst | 4 |
5 files changed, 108 insertions, 6 deletions
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 a2c7a09478..24aa3d41fa 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 0000000000..451c24f394 --- /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 4f1bf1ee13..c7691ae35c 100755 --- 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 f389a6768c..57ab3b9b05 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 74ee8ec86a..6b15abcfa3 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`. |