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

   1 /*
   2  *  ============LICENSE_START=======================================================
   3  *  Copyright (C) 2020-2023 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      * Persists child data fragment representing one or more list elements under existing data node for the
 104      * given anchor and dataspace.
 105      *
 106      * @param dataspaceName     dataspace name
 107      * @param anchorName        anchor name
 108      * @param parentNodeXpath   parent node xpath
 109      * @param jsonDataList      collection of json data representing list element(s)
 110      * @param observedTimestamp observedTimestamp
 111      */
 112     void saveListElementsBatch(String dataspaceName, String anchorName, String parentNodeXpath,
 113             Collection<String> jsonDataList, OffsetDateTime observedTimestamp);
 114
 115     /**
 116      * Retrieves all the datanodes by XPath for given dataspace and anchor.
 117      *
 118      * @param dataspaceName           dataspace name
 119      * @param anchorName              anchor name
 120      * @param xpath                   xpath
 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> getDataNodes(String dataspaceName, String anchorName, String xpath,
 126                                       FetchDescendantsOption fetchDescendantsOption);
 127
 128     /**
 129      * Retrieves all the datanodes for multiple XPaths for given dataspace and anchor.
 130      *
 131      * @param dataspaceName           dataspace name
 132      * @param anchorName              anchor name
 133      * @param xpaths                  collection of xpaths
 134      * @param fetchDescendantsOption  defines the scope of data to fetch: either single node or all the descendant nodes
 135      *                                (recursively) as well
 136      * @return collection of data node objects
 137      */
 138     Collection<DataNode> getDataNodesForMultipleXpaths(String dataspaceName, String anchorName,
 139                                                        Collection<String> xpaths,
 140                                                        FetchDescendantsOption fetchDescendantsOption);
 141
 142     /**
 143      * Updates multiple data nodes for given dataspace and anchor using xpath to parent node.
 144      *
 145      * @param dataspaceName   dataspace name
 146      * @param anchorName      anchor name
 147      * @param parentNodeXpath xpath to parent node
 148      * @param jsonData        json data
 149      * @param observedTimestamp observedTimestamp
 150      */
 151     void updateNodeLeaves(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
 152         OffsetDateTime observedTimestamp);
 153
 154     /**
 155      * Replaces an existing data node's content including descendants.
 156      *
 157      * @param dataspaceName     dataspace name
 158      * @param anchorName        anchor name
 159      * @param parentNodeXpath   xpath to parent node
 160      * @param jsonData          json data
 161      * @param observedTimestamp observedTimestamp
 162      */
 163     void updateDataNodeAndDescendants(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
 164                                        OffsetDateTime observedTimestamp);
 165
 166     /**
 167      * Replaces multiple existing data nodes' content including descendants in a batch operation.
 168      *
 169      * @param dataspaceName   dataspace name
 170      * @param anchorName      anchor name
 171      * @param nodesJsonData   map of xpath and node JSON data
 172      * @param observedTimestamp observedTimestamp
 173      */
 174     void updateDataNodesAndDescendants(String dataspaceName, String anchorName, Map<String, String> nodesJsonData,
 175                                        OffsetDateTime observedTimestamp);
 176
 177     /**
 178      * Replaces list content by removing all existing elements and inserting the given new elements as json
 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 jsonData          json data representing the new list elements
 185      * @param observedTimestamp observedTimestamp
 186      */
 187     void replaceListContent(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
 188         OffsetDateTime observedTimestamp);
 189
 190     /**
 191      * Replaces list content by removing all existing elements and inserting the given new elements as data nodes
 192      * under given parent, anchor and dataspace.
 193      *
 194      * @param dataspaceName     dataspace-name
 195      * @param anchorName        anchor name
 196      * @param parentNodeXpath   parent node xpath
 197      * @param dataNodes         datanodes representing the updated data
 198      * @param observedTimestamp observedTimestamp
 199      */
 200     void replaceListContent(String dataspaceName, String anchorName, String parentNodeXpath,
 201             Collection<DataNode> dataNodes, OffsetDateTime observedTimestamp);
 202
 203     /**
 204      * Deletes data node for given anchor and dataspace.
 205      *
 206      * @param dataspaceName     dataspace name
 207      * @param anchorName        anchor name
 208      * @param dataNodeXpath     data node xpath
 209      * @param observedTimestamp observed timestamp
 210      */
 211     void deleteDataNode(String dataspaceName, String anchorName, String dataNodeXpath,
 212         OffsetDateTime observedTimestamp);
 213
 214     /**
 215      * Deletes multiple data nodes for given anchor and dataspace.
 216      *
 217      * @param dataspaceName     dataspace name
 218      * @param anchorName        anchor name
 219      * @param dataNodeXpaths    data node xpaths
 220      * @param observedTimestamp observed timestamp
 221      */
 222     void deleteDataNodes(String dataspaceName, String anchorName, Collection<String> dataNodeXpaths,
 223                          OffsetDateTime observedTimestamp);
 224
 225     /**
 226      * Deletes all data nodes for a given anchor in a dataspace.
 227      *
 228      * @param dataspaceName     dataspace name
 229      * @param anchorName        anchor name
 230      * @param observedTimestamp observed timestamp
 231      */
 232     void deleteDataNodes(String dataspaceName, String anchorName, OffsetDateTime observedTimestamp);
 233
 234     /**
 235      * Deletes all data nodes for multiple anchors in a dataspace.
 236      *
 237      * @param dataspaceName     dataspace name
 238      * @param anchorNames       anchor names
 239      * @param observedTimestamp observed timestamp
 240      */
 241     void deleteDataNodes(String dataspaceName, Collection<String> anchorNames, OffsetDateTime observedTimestamp);
 242
 243     /**
 244      * Deletes a list or a list-element under given anchor and dataspace.
 245      *
 246      * @param dataspaceName dataspace name
 247      * @param anchorName    anchor name
 248      * @param listElementXpath list element xpath
 249      * @param observedTimestamp observedTimestamp
 250      */
 251     void deleteListOrListElement(String dataspaceName, String anchorName, String listElementXpath,
 252         OffsetDateTime observedTimestamp);
 253
 254     /**
 255      * Updates leaves of DataNode for given dataspace and anchor using xpath, along with the leaves of each Child Data
 256      * Node which already exists. This method will throw an exception if data node update or any descendant update does
 257      * not exist.
 258      *
 259      * @param dataspaceName         dataspace name
 260      * @param anchorName            anchor name
 261      * @param parentNodeXpath       xpath
 262      * @param dataNodeUpdatesAsJson json data representing data node updates
 263      * @param observedTimestamp observedTimestamp
 264      */
 265     void updateNodeLeavesAndExistingDescendantLeaves(String dataspaceName, String anchorName, String parentNodeXpath,
 266         String dataNodeUpdatesAsJson, OffsetDateTime observedTimestamp);
 267
 268     /**
 269      * Starts a session which allows use of locks and batch interaction with the persistence service.
 270      *
 271      * @return Session ID string
 272      */
 273     String startSession();
 274
 275     /**
 276      * Close session.
 277      *
 278      * @param sessionId session ID
 279      *
 280      */
 281     void closeSession(String sessionId);
 282
 283     /**
 284      * Lock anchor with default 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      */
 291     void lockAnchor(String sessionID, String dataspaceName, String anchorName);
 292
 293     /**
 294      * Lock anchor with custom timeout.
 295      * To release locks(s), the session holding the lock(s) must be closed.
 296      *
 297      * @param sessionID session ID
 298      * @param dataspaceName dataspace name
 299      * @param anchorName anchor name
 300      * @param timeoutInMilliseconds lock attempt timeout in milliseconds
 301      */
 302     void lockAnchor(String sessionID, String dataspaceName, String anchorName, Long timeoutInMilliseconds);
 303
 304     /**
 305      * Retrieves the delta between two anchors by xpath within a dataspace.
 306      *
 307      * @param dataspaceName          dataspace name
 308      * @param sourceAnchorName       source anchor name
 309      * @param targetAnchorName       target anchor name
 310      * @param xpath                  xpath
 311      * @param fetchDescendantsOption defines the scope of data to fetch: either single node or all the descendant
 312      *                               nodes (recursively) as well
 313      * @return                       list containing {@link DeltaReport} objects
 314      */
 315     List<DeltaReport> getDeltaByDataspaceAndAnchors(String dataspaceName, String sourceAnchorName,
 316                                                     String targetAnchorName, String xpath,
 317                                                     FetchDescendantsOption fetchDescendantsOption);
 318 }