Support text() condition

- Added Antlr parsing of text() condition (as an optional additional to any query)
- Implemented text-condition combined with descendants
- Refactor descendants queries into using one more flexible Custom (native) Query builder
- Refactor ALL cpsPath queries to now use FragmentRepositoryCpsPathQuery (custom query builder)
- Refactor Antrl code to simply parsing of cpsPath and allow all combinations (no more query types, addresses CPS-436)
- Minor clean up of some minor convention issues in CpsAdminServiceImplSpec.groovy (found during groovy demo)
- Update .rst documentation of xPaths
- Fixed incorrect matching of additional list indexes using more precise SIMILAR-TO regex in postgreSQL
- Documented special chararter limitation (CPS-500)
- Checked for consistent use of term 'CPS path' in documentation and error message
- Included (updated) copyright in all .SQL test files

Issue-ID: CPS-452
Issue-ID: CPS-436
Issue-ID: CPS-500

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

1 files changed, 93 insertions, 60 deletions

diff --git a/docs/cps-path.rst b/docs/cps-path.rst
index aec87cd436..0271d07e1d 100644
--- a/docs/cps-path.rst
+++ b/docs/cps-path.rst
@@ -14,8 +14,8 @@ CPS Path
 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/>`_
+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 inspired 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.
 
@@ -28,104 +28,137 @@ The xml below describes some basic data to be used to illustrate the CPS Path fu
 
     <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-name>Chapters</bookstore-name>
+          <categories code="1" name="SciFi" numberOfBooks="2">
+             <books>
+                <book title="2001: A Space Odyssey" price="5">
+                   <label>sale</label>
+                   <label>classic</label>
+                   <edition>1968</edition>
+                   <edition>2018</edition>
+              </book>
+                <book title="Dune" price="5">
+                   <label>classic</label>
+                   <edition>1965</edition>
+                </book>
+             </books>
+          </categories>
+          <categories code="2" name="Kids" numberOfBooks="1">
+             <books>
+                <book title="Matilda" />
+             </books>
+          </categories>
        </bookstore>
     </shops>
 
-**Note.** 'categories' is a Yang List and 'code' is its key leaf. All other data nodes are Yang Containers
+**Note.** 'categories' is a Yang List and 'code' is its key leaf. All other data nodes are Yang Containers. 'label' and 'edition' are both leaf-lists.
 
 General Notes
 =============
 
-- String values must be wrapped in quotation marks (U+0022) or apostrophes (U+0027).
+- String values must be wrapped in quotation marks ``"`` (U+0022) or apostrophes ``'`` (U+0027).
 - String comparisons are case sensitive.
+- List key-fields containing ``\`` or ``@[`` will not be processed correctly when being referenced with such key values in absolute or descendant paths. This means such entries will be omitted from any query result. See `CPS-500 <https://jira.onap.org/browse/CPS-500>`_ Special Character Limitations of cpsPath Queries
 
-Supported Queries
-=================
+Query Syntax
+============
 
-Get List Elements by Any Attribute Value
-----------------------------------------
+``( <absolute-path> | <descendant-path> ) [ <leaf-conditions> ] [ <text()-condition> ] [ <ancestor-axis> ]``
 
-**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.
+Each CPS path expression need to start with an 'absolute' or 'descendant' xpath.
+
+absolute-path
+-------------
+
+**Syntax**: ``'/' <container-name> ( '[' <list-key> ']' )? ( '/' <containerName> ( '[' <list-key> ']' )? )*``
+
+  - ``container name``: Any yang container or list.
+  - ``list-key``:  One or more key-value pairs, each preceded by the ``@`` symbol, combined using the ``and`` keyword.
+  - The above van repeated any number of times.
 
 **Examples**
-  - ``/shops/bookstore/categories[@numberOfBooks=1]``
-  - ``/shops/bookstore/categories[@name="Kids"]``
-  - ``/shops/bookstore/categories[@name='Kids']``
+  - ``/shops/bookstore``
+  - ``/shops/bookstore/categories[@code=1]``
+  - ``/shops/bookstore/categories[@code=1]/book``
 
 **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).
+  - Absolute paths must start with the top element (data node) as per the model tree.
+  - Each list reference must include a valid instance reference to the key for that list. Except when it is the last element.
 
-**Notes**
-  - For performance reasons it does not make sense to query using key leaf as attribute. If the key value is known it is better to execute a get request with the complete xpath.
+descendant-path
+---------------
 
-Get Any Descendant
-------------------
+**Syntax**: ``'//' <container-name> ( '[' <list-key> ']' )? ( '/' <containerName> ( '[' <list-key> ']' )? )*``
 
-**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]``.
+  - The syntax of a descendant path is identical to a absolute path except that it is preceded by a double slash ``//``.
 
 **Examples**
-  - ``//book``
-  - ``//books/book``
-  - ``//categories[@code=1]``
-  - ``//categories[@code=1]/books``
+  - ``//bookstore``
+  - ``//categories[@code=1]/book``
+  - ``//bookstore/categories``
 
 **Limitations**
-  - List elements can only be addressed using the list key leaf.
+  - Each list reference must include a valid instance reference to the key for that list.  Except when it is the last element.
 
-Get Any Descendant by Any Attribute Value
------------------------------------------
+leaf-conditions
+---------------
 
-**Syntax**: ``//<direct-ancestors><target-node>[@<leaf-name>=<leaf-value>]``
-  - ``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 which elements will queried.
-  - ``leaf1-name .. leafN-name:``: One or more leaves whose value needs to be compared.
-  - ``leaf1-value .. leafN-value:``: One or more required leaf values (multiple condition can be combined using the 'and' keyword).
+**Syntax**: ``<xpath> '[' @<leaf-name1> '=' <leaf-value1> ( ' and ' @<leaf-name> '=' <leaf-value> )* ']'``
+  - ``xpath``: Absolute or descendant or xpath to the (list) node which elements will be 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]``
+  - ``//categories[@name="Kids"]``
   - ``//categories[@name='Kids']``
-  - ``//categories[@name='Kids' and @numberOfBooks=1]``
+  - ``//categories[@code=1]/book[@title='Dune' and price=5]``
 
 **Limitations**
-  - Only string and integer values are supported (boolean and float values are not supported).
-  - Multiple attributes can only be combined using 'and'. 'or' and bracketing is not supported.
+  - Only the last list or container can be queried leaf values. Any ancestor list will have to be referenced by its key name-value pair(s).
+  - Multiple attributes can only be combined using ``and``. ``or`` and bracketing is not supported.
+  - Only leaves can be used, leaf-list are not supported.
+  - 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 using key leaf as attribute. If the key value is known it is better to execute a get request with the complete xpath.
+
+text()-condition
+----------------
+
+The text()-condition  can be added to any CPS path query.
 
-Query Extensions
-================
+**Syntax**: ``<cps-path> ( '/' <leaf-name> '[text()=' <string-value> ']' )?``
+  - ``cps-path``: Any CPS path query.
+  - ``leaf-name``: The name of the leaf or leaf-list which value needs to be compared.
+  - ``string-value``: The required value of the leaf or leaf-list element as a string wrapped in quotation marks (U+0022) or apostrophes (U+0027). This wil still match integer values.
+
+**Examples**
+  - ``//book/label[text()="classic"]``
+  - ``//book/edition[text()="1965"]``
+
+**Limitations**
+  - Only the last list or container can be queried for leaf values with a text() condition. Any ancestor list will have to be referenced by its key name-value pair(s).
+  - Only one leaf or leaf-list can be tested.
+  - Only string and integer values are supported, boolean and float values are not supported.
+  - Since CPS cannot return individual leaves it will always return the container with all its leaves. Ancestor-axis can be used to specify a parent higher up the tree.
+  - When querying a leaf value (instead of leaf-list) it is better, more performant to use a text value condition use @<leaf-name> as described above.
 
-Ancestor Axis
+ancestor-axis
 -------------
 
-The ancestor axis can be added to any CPS path query.
+The ancestor axis can be added to any CPS path query but has to be the last part.
 
-**Syntax**: ``//<cps-path>/ancestor::<ancestor-path>``
+**Syntax**: ``<cps-path> ( '/ancestor::' <ancestor-path> )?``
   - ``cps-path``: Any CPS path query.
-  - ``ancestor-path``:  Partial path to ancestors of the target node. This can contain one or more ancestor nodes separated by a /.
+  - ``ancestor-path``: Partial path to ancestors of the target node. This can contain one or more ancestor nodes separated by a ``/``.
 
 **Examples**
   - ``//book/ancestor::categories``
   - ``//categories[@genre="SciFi"]/book/ancestor::bookstore``
   - ``book/ancestor::categories[@code=1]/books``
+  - ``//book/label[text()="classic"]/ancestor::shop``
 
 **Limitations**
   - Ancestor list elements can only be addressed using the list key leaf.
-  - List elements with compound keys are not supported.
\ No newline at end of file
+  - List elements with compound keys are not supported.