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 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.List;
  30 import java.util.Map;
  31 import org.onap.cps.spi.FetchDescendantsOption;
  32 import org.onap.cps.spi.model.DataNode;
  33 import org.onap.cps.spi.model.DeltaReport;
  34 import org.onap.cps.utils.ContentType;
  35
  36 /*
  37  * Datastore interface for handling CPS data.
  38  */
  39 public interface CpsDataService {
  40
  41     /**
  42      * Persists data for the given anchor and dataspace.
  43      *
  44      * @param dataspaceName dataspace name
  45      * @param anchorName    anchor name
  46      * @param nodeData      node data
  47      * @param observedTimestamp observedTimestamp
  48      */
  49     void saveData(String dataspaceName, String anchorName, String nodeData, OffsetDateTime observedTimestamp);
  50
  51     /**
  52      * Persists data for the given anchor and dataspace.
  53      *
  54      * @param dataspaceName dataspace name
  55      * @param anchorName    anchor name
  56      * @param nodeData      node data
  57      * @param observedTimestamp observedTimestamp
  58      * @param contentType       node data content type
  59      */
  60     void saveData(String dataspaceName, String anchorName, String nodeData, OffsetDateTime observedTimestamp,
  61                   ContentType contentType);
  62
  63     /**
  64      * Persists child data fragment under existing data node for the given anchor and dataspace.
  65      *
  66      * @param dataspaceName   dataspace name
  67      * @param anchorName      anchor name
  68      * @param parentNodeXpath parent node xpath
  69      * @param nodeData        node data
  70      * @param observedTimestamp observedTimestamp
  71      */
  72     void saveData(String dataspaceName, String anchorName, String parentNodeXpath, String nodeData,
  73                   OffsetDateTime observedTimestamp);
  74
  75     /**
  76      * Persists child data fragment under existing data node for the given anchor, dataspace and content type.
  77      *
  78      * @param dataspaceName     dataspace name
  79      * @param anchorName        anchor name
  80      * @param parentNodeXpath   parent node xpath
  81      * @param nodeData          node data
  82      * @param observedTimestamp observedTimestamp
  83      * @param contentType       node data content type
  84      *
  85      */
  86     void saveData(String dataspaceName, String anchorName, String parentNodeXpath, String nodeData,
  87                   OffsetDateTime observedTimestamp, ContentType contentType);
  88
  89     /**
  90      * Persists child data fragment representing one or more list elements under existing data node for the
  91      * given anchor and dataspace.
  92      *
  93      * @param dataspaceName     dataspace name
  94      * @param anchorName        anchor name
  95      * @param parentNodeXpath   parent node xpath
  96      * @param jsonData          json data representing list element(s)
  97      * @param observedTimestamp observedTimestamp
  98      */
  99     void saveListElements(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
 100         OffsetDateTime observedTimestamp);
 101
 102     /**
 103      * Retrieves all the datanodes by XPath for given dataspace and anchor.
 104      *
 105      * @param dataspaceName           dataspace name
 106      * @param anchorName              anchor name
 107      * @param xpath                   xpath
 108      * @param fetchDescendantsOption  defines the scope of data to fetch: either single node or all the descendant nodes
 109      *                                (recursively) as well
 110      * @return collection of data node objects
 111      */
 112     Collection<DataNode> getDataNodes(String dataspaceName, String anchorName, String xpath,
 113                                       FetchDescendantsOption fetchDescendantsOption);
 114
 115     /**
 116      * Retrieves all the datanodes for multiple XPaths for given dataspace and anchor.
 117      *
 118      * @param dataspaceName           dataspace name
 119      * @param anchorName              anchor name
 120      * @param xpaths                  collection of xpaths
 121      * @param fetchDescendantsOption  defines the scope of data to fetch: either single node or all the descendant nodes
 122      *                                (recursively) as well
 123      * @return collection of data node objects
 124      */
 125     Collection<DataNode> getDataNodesForMultipleXpaths(String dataspaceName, String anchorName,
 126                                                        Collection<String> xpaths,
 127                                                        FetchDescendantsOption fetchDescendantsOption);
 128
 129     /**
 130      * Updates multiple data nodes for given dataspace and anchor using xpath to parent node.
 131      *
 132      * @param dataspaceName   dataspace name
 133      * @param anchorName      anchor name
 134      * @param parentNodeXpath xpath to parent node
 135      * @param jsonData        json data
 136      * @param observedTimestamp observedTimestamp
 137      */
 138     void updateNodeLeaves(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
 139         OffsetDateTime observedTimestamp);
 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 jsonData          json data
 148      * @param observedTimestamp observedTimestamp
 149      */
 150     void updateDataNodeAndDescendants(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
 151                                        OffsetDateTime observedTimestamp);
 152
 153     /**
 154      * Replaces multiple existing data nodes' content including descendants in a batch operation.
 155      *
 156      * @param dataspaceName   dataspace name
 157      * @param anchorName      anchor name
 158      * @param nodesJsonData   map of xpath and node JSON data
 159      * @param observedTimestamp observedTimestamp
 160      */
 161     void updateDataNodesAndDescendants(String dataspaceName, String anchorName, Map<String, String> nodesJsonData,
 162                                        OffsetDateTime observedTimestamp);
 163
 164     /**
 165      * Replaces list content by removing all existing elements and inserting the given new elements as json
 166      * under given parent, anchor and dataspace.
 167      *
 168      * @param dataspaceName     dataspace name
 169      * @param anchorName        anchor name
 170      * @param parentNodeXpath   parent node xpath
 171      * @param jsonData          json data representing the new list elements
 172      * @param observedTimestamp observedTimestamp
 173      */
 174     void replaceListContent(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
 175         OffsetDateTime observedTimestamp);
 176
 177     /**
 178      * Replaces list content by removing all existing elements and inserting the given new elements as data nodes
 179      * under given parent, anchor and dataspace.
 180      *
 181      * @param dataspaceName     dataspace-name
 182      * @param anchorName        anchor name
 183      * @param parentNodeXpath   parent node xpath
 184      * @param dataNodes         datanodes representing the updated data
 185      * @param observedTimestamp observedTimestamp
 186      */
 187     void replaceListContent(String dataspaceName, String anchorName, String parentNodeXpath,
 188             Collection<DataNode> dataNodes, OffsetDateTime observedTimestamp);
 189
 190     /**
 191      * Deletes data node for given anchor and dataspace.
 192      *
 193      * @param dataspaceName     dataspace name
 194      * @param anchorName        anchor name
 195      * @param dataNodeXpath     data node xpath
 196      * @param observedTimestamp observed timestamp
 197      */
 198     void deleteDataNode(String dataspaceName, String anchorName, String dataNodeXpath,
 199         OffsetDateTime observedTimestamp);
 200
 201     /**
 202      * Deletes multiple data nodes for given anchor and dataspace.
 203      *
 204      * @param dataspaceName     dataspace name
 205      * @param anchorName        anchor name
 206      * @param dataNodeXpaths    data node xpaths
 207      * @param observedTimestamp observed timestamp
 208      */
 209     void deleteDataNodes(String dataspaceName, String anchorName, Collection<String> dataNodeXpaths,
 210                          OffsetDateTime observedTimestamp);
 211
 212     /**
 213      * Deletes all data nodes for a given anchor in a dataspace.
 214      *
 215      * @param dataspaceName     dataspace name
 216      * @param anchorName        anchor name
 217      * @param observedTimestamp observed timestamp
 218      */
 219     void deleteDataNodes(String dataspaceName, String anchorName, OffsetDateTime observedTimestamp);
 220
 221     /**
 222      * Deletes all data nodes for multiple anchors in a dataspace.
 223      *
 224      * @param dataspaceName     dataspace name
 225      * @param anchorNames       anchor names
 226      * @param observedTimestamp observed timestamp
 227      */
 228     void deleteDataNodes(String dataspaceName, Collection<String> anchorNames, OffsetDateTime observedTimestamp);
 229
 230     /**
 231      * Deletes a list or a list-element under given anchor and dataspace.
 232      *
 233      * @param dataspaceName dataspace name
 234      * @param anchorName    anchor name
 235      * @param listElementXpath list element xpath
 236      * @param observedTimestamp observedTimestamp
 237      */
 238     void deleteListOrListElement(String dataspaceName, String anchorName, String listElementXpath,
 239         OffsetDateTime observedTimestamp);
 240
 241     /**
 242      * Updates leaves of DataNode for given dataspace and anchor using xpath, along with the leaves of each Child Data
 243      * Node which already exists. This method will throw an exception if data node update or any descendant update does
 244      * not exist.
 245      *
 246      * @param dataspaceName         dataspace name
 247      * @param anchorName            anchor name
 248      * @param parentNodeXpath       xpath
 249      * @param dataNodeUpdatesAsJson json data representing data node updates
 250      * @param observedTimestamp observedTimestamp
 251      */
 252     void updateNodeLeavesAndExistingDescendantLeaves(String dataspaceName, String anchorName, String parentNodeXpath,
 253         String dataNodeUpdatesAsJson, OffsetDateTime observedTimestamp);
 254
 255     /**
 256      * Starts a session which allows use of locks and batch interaction with the persistence service.
 257      *
 258      * @return Session ID string
 259      */
 260     String startSession();
 261
 262     /**
 263      * Close session.
 264      *
 265      * @param sessionId session ID
 266      *
 267      */
 268     void closeSession(String sessionId);
 269
 270     /**
 271      * Lock anchor with default timeout.
 272      * To release locks(s), the session holding the lock(s) must be closed.
 273      *
 274      * @param sessionID session ID
 275      * @param dataspaceName dataspace name
 276      * @param anchorName anchor name
 277      */
 278     void lockAnchor(String sessionID, String dataspaceName, String anchorName);
 279
 280     /**
 281      * Lock anchor with custom timeout.
 282      * To release locks(s), the session holding the lock(s) must be closed.
 283      *
 284      * @param sessionID session ID
 285      * @param dataspaceName dataspace name
 286      * @param anchorName anchor name
 287      * @param timeoutInMilliseconds lock attempt timeout in milliseconds
 288      */
 289     void lockAnchor(String sessionID, String dataspaceName, String anchorName, Long timeoutInMilliseconds);
 290
 291     /**
 292      * Retrieves the delta between two anchors by xpath within a dataspace.
 293      *
 294      * @param dataspaceName          dataspace name
 295      * @param sourceAnchorName       source anchor name
 296      * @param targetAnchorName       target anchor name
 297      * @param xpath                  xpath
 298      * @param fetchDescendantsOption defines the scope of data to fetch: either single node or all the descendant
 299      *                               nodes (recursively) as well
 300      * @return                       list containing {@link DeltaReport} objects
 301      */
 302     List<DeltaReport> getDeltaByDataspaceAndAnchors(String dataspaceName, String sourceAnchorName,
 303                                                     String targetAnchorName, String xpath,
 304                                                     FetchDescendantsOption fetchDescendantsOption);
 305 }