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