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
13 * http://www.apache.org/licenses/LICENSE-2.0
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.
21 * SPDX-License-Identifier: Apache-2.0
22 * ============LICENSE_END=========================================================
25 package org.onap.cps.api;
27 import java.time.OffsetDateTime;
28 import java.util.Collection;
29 import java.util.List;
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;
37 * Datastore interface for handling CPS data.
39 public interface CpsDataService {
42 * Persists data for the given anchor and dataspace.
44 * @param dataspaceName dataspace name
45 * @param anchorName anchor name
46 * @param nodeData node data
47 * @param observedTimestamp observedTimestamp
49 void saveData(String dataspaceName, String anchorName, String nodeData, OffsetDateTime observedTimestamp);
52 * Persists data for the given anchor and dataspace.
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
60 void saveData(String dataspaceName, String anchorName, String nodeData, OffsetDateTime observedTimestamp,
61 ContentType contentType);
64 * Persists child data fragment under existing data node for the given anchor and dataspace.
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
72 void saveData(String dataspaceName, String anchorName, String parentNodeXpath, String nodeData,
73 OffsetDateTime observedTimestamp);
76 * Persists child data fragment under existing data node for the given anchor, dataspace and content type.
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
86 void saveData(String dataspaceName, String anchorName, String parentNodeXpath, String nodeData,
87 OffsetDateTime observedTimestamp, ContentType contentType);
90 * Persists child data fragment representing one or more list elements under existing data node for the
91 * given anchor and dataspace.
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
99 void saveListElements(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
100 OffsetDateTime observedTimestamp);
103 * Retrieves all the datanodes by XPath for given dataspace and anchor.
105 * @param dataspaceName dataspace name
106 * @param anchorName anchor name
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
112 Collection<DataNode> getDataNodes(String dataspaceName, String anchorName, String xpath,
113 FetchDescendantsOption fetchDescendantsOption);
116 * Retrieves all the datanodes for multiple XPaths for given dataspace and anchor.
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
125 Collection<DataNode> getDataNodesForMultipleXpaths(String dataspaceName, String anchorName,
126 Collection<String> xpaths,
127 FetchDescendantsOption fetchDescendantsOption);
130 * Updates multiple data nodes for given dataspace and anchor using xpath to parent node.
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
138 void updateNodeLeaves(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
139 OffsetDateTime observedTimestamp);
142 * Replaces an existing data node's content including descendants.
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
150 void updateDataNodeAndDescendants(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
151 OffsetDateTime observedTimestamp);
154 * Replaces multiple existing data nodes' content including descendants in a batch operation.
156 * @param dataspaceName dataspace name
157 * @param anchorName anchor name
158 * @param nodesJsonData map of xpath and node JSON data
159 * @param observedTimestamp observedTimestamp
161 void updateDataNodesAndDescendants(String dataspaceName, String anchorName, Map<String, String> nodesJsonData,
162 OffsetDateTime observedTimestamp);
165 * Replaces list content by removing all existing elements and inserting the given new elements as json
166 * under given parent, anchor and dataspace.
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
174 void replaceListContent(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
175 OffsetDateTime observedTimestamp);
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.
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
187 void replaceListContent(String dataspaceName, String anchorName, String parentNodeXpath,
188 Collection<DataNode> dataNodes, OffsetDateTime observedTimestamp);
191 * Deletes data node for given anchor and dataspace.
193 * @param dataspaceName dataspace name
194 * @param anchorName anchor name
195 * @param dataNodeXpath data node xpath
196 * @param observedTimestamp observed timestamp
198 void deleteDataNode(String dataspaceName, String anchorName, String dataNodeXpath,
199 OffsetDateTime observedTimestamp);
202 * Deletes multiple data nodes for given anchor and dataspace.
204 * @param dataspaceName dataspace name
205 * @param anchorName anchor name
206 * @param dataNodeXpaths data node xpaths
207 * @param observedTimestamp observed timestamp
209 void deleteDataNodes(String dataspaceName, String anchorName, Collection<String> dataNodeXpaths,
210 OffsetDateTime observedTimestamp);
213 * Deletes all data nodes for a given anchor in a dataspace.
215 * @param dataspaceName dataspace name
216 * @param anchorName anchor name
217 * @param observedTimestamp observed timestamp
219 void deleteDataNodes(String dataspaceName, String anchorName, OffsetDateTime observedTimestamp);
222 * Deletes all data nodes for multiple anchors in a dataspace.
224 * @param dataspaceName dataspace name
225 * @param anchorNames anchor names
226 * @param observedTimestamp observed timestamp
228 void deleteDataNodes(String dataspaceName, Collection<String> anchorNames, OffsetDateTime observedTimestamp);
231 * Deletes a list or a list-element under given anchor and dataspace.
233 * @param dataspaceName dataspace name
234 * @param anchorName anchor name
235 * @param listElementXpath list element xpath
236 * @param observedTimestamp observedTimestamp
238 void deleteListOrListElement(String dataspaceName, String anchorName, String listElementXpath,
239 OffsetDateTime observedTimestamp);
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
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
252 void updateNodeLeavesAndExistingDescendantLeaves(String dataspaceName, String anchorName, String parentNodeXpath,
253 String dataNodeUpdatesAsJson, OffsetDateTime observedTimestamp);
256 * Starts a session which allows use of locks and batch interaction with the persistence service.
258 * @return Session ID string
260 String startSession();
265 * @param sessionId session ID
268 void closeSession(String sessionId);
271 * Lock anchor with default timeout.
272 * To release locks(s), the session holding the lock(s) must be closed.
274 * @param sessionID session ID
275 * @param dataspaceName dataspace name
276 * @param anchorName anchor name
278 void lockAnchor(String sessionID, String dataspaceName, String anchorName);
281 * Lock anchor with custom timeout.
282 * To release locks(s), the session holding the lock(s) must be closed.
284 * @param sessionID session ID
285 * @param dataspaceName dataspace name
286 * @param anchorName anchor name
287 * @param timeoutInMilliseconds lock attempt timeout in milliseconds
289 void lockAnchor(String sessionID, String dataspaceName, String anchorName, Long timeoutInMilliseconds);
292 * Retrieves the delta between two anchors by xpath within a dataspace.
294 * @param dataspaceName dataspace name
295 * @param sourceAnchorName source anchor name
296 * @param targetAnchorName target anchor name
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
302 List<DeltaReport> getDeltaByDataspaceAndAnchors(String dataspaceName, String sourceAnchorName,
303 String targetAnchorName, String xpath,
304 FetchDescendantsOption fetchDescendantsOption);