cps-service/src/main/java/org/onap/cps/api/CpsDataService.java

   1 /*
   2  *  ============LICENSE_START=======================================================
   3  *  Copyright (C) 2020-2024 Nordix Foundation
   4  *  Modifications Copyright (C) 2021 Pantheon.tech
   5  *  Modifications Copyright (C) 2021-2022 Bell Canada
   6  *  Modifications Copyright (C) 2022 Deutsche Telekom AG
   7  *  Modifications Copyright (C) 2023-2025 TechMahindra Ltd.
   8  *  ================================================================================
   9  *  Licensed under the Apache License, Version 2.0 (the "License");
  10  *  you may not use this file except in compliance with the License.
  11  *  You may obtain a copy of the License at
  12  *
  13  *        http://www.apache.org/licenses/LICENSE-2.0
  14  *
  15  *  Unless required by applicable law or agreed to in writing, software
  16  *  distributed under the License is distributed on an "AS IS" BASIS,
  17  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  *  See the License for the specific language governing permissions and
  19  *  limitations under the License.
  20  *
  21  *  SPDX-License-Identifier: Apache-2.0
  22  *  ============LICENSE_END=========================================================
  23  */
  24
  25 package org.onap.cps.api;
  26
  27 import java.time.OffsetDateTime;
  28 import java.util.Collection;
  29 import java.util.Map;
  30 import org.onap.cps.api.model.DataNode;
  31 import org.onap.cps.api.parameters.FetchDescendantsOption;
  32 import org.onap.cps.utils.ContentType;
  33
  34 /*
  35  * Datastore interface for handling CPS data.
  36  */
  37 public interface CpsDataService {
  38
  39     /**
  40      * Persists data for the given anchor and dataspace.
  41      *
  42      * @param dataspaceName dataspace name
  43      * @param anchorName    anchor name
  44      * @param nodeData      node data
  45      * @param observedTimestamp observedTimestamp
  46      */
  47     void saveData(String dataspaceName, String anchorName, String nodeData, OffsetDateTime observedTimestamp);
  48
  49     /**
  50      * Persists data for the given anchor and dataspace.
  51      *
  52      * @param dataspaceName dataspace name
  53      * @param anchorName    anchor name
  54      * @param nodeData      node data
  55      * @param observedTimestamp observedTimestamp
  56      * @param contentType       JSON/XML content type
  57      */
  58     void saveData(String dataspaceName, String anchorName, String nodeData, OffsetDateTime observedTimestamp,
  59                   ContentType contentType);
  60
  61     /**
  62      * Persists child data fragment under existing data node for the given anchor and dataspace.
  63      *
  64      * @param dataspaceName   dataspace name
  65      * @param anchorName      anchor name
  66      * @param parentNodeXpath parent node xpath
  67      * @param nodeData        node data
  68      * @param observedTimestamp observedTimestamp
  69      */
  70     void saveData(String dataspaceName, String anchorName, String parentNodeXpath, String nodeData,
  71                   OffsetDateTime observedTimestamp);
  72
  73     /**
  74      * Persists child data fragment under existing data node for the given anchor, dataspace and content type.
  75      *
  76      * @param dataspaceName     dataspace name
  77      * @param anchorName        anchor name
  78      * @param parentNodeXpath   parent node xpath
  79      * @param nodeData          node data
  80      * @param observedTimestamp observedTimestamp
  81      * @param contentType       JSON/XML content type
  82      *
  83      */
  84     void saveData(String dataspaceName, String anchorName, String parentNodeXpath, String nodeData,
  85                   OffsetDateTime observedTimestamp, ContentType contentType);
  86
  87     /**
  88      * Persists child data fragment representing one or more list elements under existing data node for the
  89      * given anchor and dataspace.
  90      *
  91      * @param dataspaceName     dataspace name
  92      * @param anchorName        anchor name
  93      * @param parentNodeXpath   parent node xpath
  94      * @param nodeData          node data representing list element(s)
  95      * @param observedTimestamp observedTimestamp
  96      * @param contentType       JSON/XML content type
  97      */
  98     void saveListElements(String dataspaceName, String anchorName, String parentNodeXpath, String nodeData,
  99         OffsetDateTime observedTimestamp, ContentType contentType);
 100
 101     /**
 102      * Retrieves all the datanodes by XPath for given dataspace and anchor.
 103      *
 104      * @param dataspaceName           dataspace name
 105      * @param anchorName              anchor name
 106      * @param xpath                   xpath
 107      * @param fetchDescendantsOption  defines the scope of data to fetch: either single node or all the descendant nodes
 108      *                                (recursively) as well
 109      * @return collection of data node objects
 110      */
 111     Collection<DataNode> getDataNodes(String dataspaceName, String anchorName, String xpath,
 112                                       FetchDescendantsOption fetchDescendantsOption);
 113
 114     /**
 115      * Retrieves all the datanodes for multiple XPaths for given dataspace and anchor.
 116      *
 117      * @param dataspaceName           dataspace name
 118      * @param anchorName              anchor name
 119      * @param xpaths                  collection of xpaths
 120      * @param fetchDescendantsOption  defines the scope of data to fetch: either single node or all the descendant nodes
 121      *                                (recursively) as well
 122      * @return collection of data node objects
 123      */
 124     Collection<DataNode> getDataNodesForMultipleXpaths(String dataspaceName, String anchorName,
 125                                                        Collection<String> xpaths,
 126                                                        FetchDescendantsOption fetchDescendantsOption);
 127
 128     /**
 129      * Updates multiple data nodes for given dataspace and anchor using xpath to parent node.
 130      *
 131      * @param dataspaceName   dataspace name
 132      * @param anchorName      anchor name
 133      * @param parentNodeXpath xpath to parent node
 134      * @param nodeData        node data
 135      * @param observedTimestamp observedTimestamp
 136      * @param contentType       JSON/XML content type
 137      */
 138     void updateNodeLeaves(String dataspaceName, String anchorName, String parentNodeXpath, String nodeData,
 139         OffsetDateTime observedTimestamp, ContentType contentType);
 140
 141     /**
 142      * Replaces an existing data node's content including descendants.
 143      *
 144      * @param dataspaceName     dataspace name
 145      * @param anchorName        anchor name
 146      * @param parentNodeXpath   xpath to parent node
 147      * @param nodeData          node data
 148      * @param observedTimestamp observedTimestamp
 149      * @param contentType       JSON/XML content type
 150      */
 151     void updateDataNodeAndDescendants(String dataspaceName, String anchorName, String parentNodeXpath, String nodeData,
 152                                        OffsetDateTime observedTimestamp, ContentType contentType);
 153
 154     /**
 155      * Replaces multiple existing data nodes' content including descendants in a batch operation.
 156      *
 157      * @param dataspaceName   dataspace name
 158      * @param anchorName      anchor name
 159      * @param nodeDataPerXPath   map of xpath and node JSON/XML data
 160      * @param observedTimestamp observedTimestamp
 161      * @param contentType       JSON/XML content type
 162      */
 163     void updateDataNodesAndDescendants(String dataspaceName, String anchorName, Map<String, String> nodeDataPerXPath,
 164                                        OffsetDateTime observedTimestamp, ContentType contentType);
 165
 166     /**
 167      * Replaces list content by removing all existing elements and inserting the given new elements as json
 168      * under given parent, anchor and dataspace.
 169      *
 170      * @param dataspaceName     dataspace name
 171      * @param anchorName        anchor name
 172      * @param parentNodeXpath   parent node xpath
 173      * @param nodeData          node data representing the new list elements
 174      * @param observedTimestamp observedTimestamp
 175      * @param contentType       JSON/XML content type
 176      */
 177     void replaceListContent(String dataspaceName, String anchorName, String parentNodeXpath, String nodeData,
 178         OffsetDateTime observedTimestamp, ContentType contentType);
 179
 180     /**
 181      * Replaces list content by removing all existing elements and inserting the given new elements as data nodes
 182      * under given parent, anchor and dataspace.
 183      *
 184      * @param dataspaceName     dataspace-name
 185      * @param anchorName        anchor name
 186      * @param parentNodeXpath   parent node xpath
 187      * @param dataNodes         datanodes representing the updated data
 188      * @param observedTimestamp observedTimestamp
 189      */
 190     void replaceListContent(String dataspaceName, String anchorName, String parentNodeXpath,
 191             Collection<DataNode> dataNodes, OffsetDateTime observedTimestamp);
 192
 193     /**
 194      * Deletes data node for given anchor and dataspace.
 195      *
 196      * @param dataspaceName     dataspace name
 197      * @param anchorName        anchor name
 198      * @param dataNodeXpath     data node xpath
 199      * @param observedTimestamp observed timestamp
 200      */
 201     void deleteDataNode(String dataspaceName, String anchorName, String dataNodeXpath,
 202         OffsetDateTime observedTimestamp);
 203
 204     /**
 205      * Deletes multiple data nodes for given anchor and dataspace.
 206      *
 207      * @param dataspaceName     dataspace name
 208      * @param anchorName        anchor name
 209      * @param dataNodeXpaths    data node xpaths
 210      * @param observedTimestamp observed timestamp
 211      */
 212     void deleteDataNodes(String dataspaceName, String anchorName, Collection<String> dataNodeXpaths,
 213                          OffsetDateTime observedTimestamp);
 214
 215     /**
 216      * Deletes all data nodes for a given anchor in a dataspace.
 217      *
 218      * @param dataspaceName     dataspace name
 219      * @param anchorName        anchor name
 220      * @param observedTimestamp observed timestamp
 221      */
 222     void deleteDataNodes(String dataspaceName, String anchorName, OffsetDateTime observedTimestamp);
 223
 224     /**
 225      * Deletes all data nodes for multiple anchors in a dataspace.
 226      *
 227      * @param dataspaceName     dataspace name
 228      * @param anchorNames       anchor names
 229      * @param observedTimestamp observed timestamp
 230      */
 231     void deleteDataNodes(String dataspaceName, Collection<String> anchorNames, OffsetDateTime observedTimestamp);
 232
 233     /**
 234      * Deletes a list or a list-element under given anchor and dataspace.
 235      *
 236      * @param dataspaceName dataspace name
 237      * @param anchorName    anchor name
 238      * @param listElementXpath list element xpath
 239      * @param observedTimestamp observedTimestamp
 240      */
 241     void deleteListOrListElement(String dataspaceName, String anchorName, String listElementXpath,
 242         OffsetDateTime observedTimestamp);
 243
 244     /**
 245      * Updates leaves of DataNode for given dataspace and anchor using xpath, along with the leaves of each Child Data
 246      * Node which already exists. This method will throw an exception if data node update or any descendant update does
 247      * not exist.
 248      *
 249      * @param dataspaceName         dataspace name
 250      * @param anchorName            anchor name
 251      * @param parentNodeXpath       xpath
 252      * @param dataNodeUpdatesAsJson json data representing data node updates
 253      * @param observedTimestamp observedTimestamp
 254      */
 255     void updateNodeLeavesAndExistingDescendantLeaves(String dataspaceName, String anchorName, String parentNodeXpath,
 256         String dataNodeUpdatesAsJson, OffsetDateTime observedTimestamp);
 257
 258     /**
 259      * Starts a session which allows use of locks and batch interaction with the persistence service.
 260      *
 261      * @return Session ID string
 262      */
 263     String startSession();
 264
 265     /**
 266      * Close session.
 267      *
 268      * @param sessionId session ID
 269      *
 270      */
 271     void closeSession(String sessionId);
 272
 273     /**
 274      * Lock anchor with default timeout.
 275      * To release locks(s), the session holding the lock(s) must be closed.
 276      *
 277      * @param sessionID session ID
 278      * @param dataspaceName dataspace name
 279      * @param anchorName anchor name
 280      */
 281     void lockAnchor(String sessionID, String dataspaceName, String anchorName);
 282
 283     /**
 284      * Lock anchor with custom timeout.
 285      * To release locks(s), the session holding the lock(s) must be closed.
 286      *
 287      * @param sessionID session ID
 288      * @param dataspaceName dataspace name
 289      * @param anchorName anchor name
 290      * @param timeoutInMilliseconds lock attempt timeout in milliseconds
 291      */
 292     void lockAnchor(String sessionID, String dataspaceName, String anchorName, Long timeoutInMilliseconds);
 293
 294     /**
 295      * Validates JSON or XML data by parsing it using the schema associated to an anchor within the given dataspace.
 296      * Validation is performed without persisting the data.
 297      *
 298      * @param dataspaceName     the name of the dataspace where the anchor is located.
 299      * @param anchorName        the name of the anchor used to validate the data.
 300      * @param parentNodeXpath   the xpath of the parent node where the data is to be validated.
 301      * @param nodeData          the JSON or XML data to be validated.
 302      * @param contentType       the content type of the data (e.g., JSON or XML).
 303      */
 304     void validateData(String dataspaceName, String anchorName, String parentNodeXpath, String nodeData,
 305                                  ContentType contentType);
 306 }