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 data node for given dataspace and anchor using xpath to parent node. This method can currently
 142      * update only one top level data node. The method will throw DataValidationException when more than one top level
 143      * data nodes are provided in jsonData
 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 }