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
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;
30 import org.onap.cps.spi.FetchDescendantsOption;
31 import org.onap.cps.spi.model.DataNode;
32 import org.onap.cps.utils.ContentType;
35 * Datastore interface for handling CPS data.
37 public interface CpsDataService {
40 * Persists data for the given anchor and dataspace.
42 * @param dataspaceName dataspace name
43 * @param anchorName anchor name
44 * @param nodeData node data
45 * @param observedTimestamp observedTimestamp
47 void saveData(String dataspaceName, String anchorName, String nodeData, OffsetDateTime observedTimestamp);
50 * Persists data for the given anchor and dataspace.
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
58 void saveData(String dataspaceName, String anchorName, String nodeData, OffsetDateTime observedTimestamp,
59 ContentType contentType);
62 * Persists child data fragment under existing data node for the given anchor and dataspace.
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
70 void saveData(String dataspaceName, String anchorName, String parentNodeXpath, String nodeData,
71 OffsetDateTime observedTimestamp);
74 * Persists child data fragment under existing data node for the given anchor, dataspace and content type.
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
84 void saveData(String dataspaceName, String anchorName, String parentNodeXpath, String nodeData,
85 OffsetDateTime observedTimestamp, ContentType contentType);
88 * Persists child data fragment representing one or more list elements under existing data node for the
89 * given anchor and dataspace.
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
97 void saveListElements(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
98 OffsetDateTime observedTimestamp);
101 * Persists child data fragment representing one or more list elements under existing data node for the
102 * given anchor and dataspace.
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
110 void saveListElementsBatch(String dataspaceName, String anchorName, String parentNodeXpath,
111 Collection<String> jsonDataList, OffsetDateTime observedTimestamp);
114 * Retrieves all the datanodes by XPath for given dataspace and anchor.
116 * @param dataspaceName dataspace name
117 * @param anchorName anchor name
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
123 Collection<DataNode> getDataNodes(String dataspaceName, String anchorName, String xpath,
124 FetchDescendantsOption fetchDescendantsOption);
127 * Retrieves all the datanodes for multiple XPaths for given dataspace and anchor.
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
136 Collection<DataNode> getDataNodesForMultipleXpaths(String dataspaceName, String anchorName,
137 Collection<String> xpaths,
138 FetchDescendantsOption fetchDescendantsOption);
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
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
151 void updateNodeLeaves(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
152 OffsetDateTime observedTimestamp);
155 * Replaces an existing data node's content including descendants.
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
163 void updateDataNodeAndDescendants(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
164 OffsetDateTime observedTimestamp);
167 * Replaces multiple existing data nodes' content including descendants in a batch operation.
169 * @param dataspaceName dataspace name
170 * @param anchorName anchor name
171 * @param nodesJsonData map of xpath and node JSON data
172 * @param observedTimestamp observedTimestamp
174 void updateDataNodesAndDescendants(String dataspaceName, String anchorName, Map<String, String> nodesJsonData,
175 OffsetDateTime observedTimestamp);
178 * Replaces list content by removing all existing elements and inserting the given new elements as json
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 jsonData json data representing the new list elements
185 * @param observedTimestamp observedTimestamp
187 void replaceListContent(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
188 OffsetDateTime observedTimestamp);
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.
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
200 void replaceListContent(String dataspaceName, String anchorName, String parentNodeXpath,
201 Collection<DataNode> dataNodes, OffsetDateTime observedTimestamp);
204 * Deletes data node for given anchor and dataspace.
206 * @param dataspaceName dataspace name
207 * @param anchorName anchor name
208 * @param dataNodeXpath data node xpath
209 * @param observedTimestamp observed timestamp
211 void deleteDataNode(String dataspaceName, String anchorName, String dataNodeXpath,
212 OffsetDateTime observedTimestamp);
215 * Deletes multiple data nodes for given anchor and dataspace.
217 * @param dataspaceName dataspace name
218 * @param anchorName anchor name
219 * @param dataNodeXpaths data node xpaths
220 * @param observedTimestamp observed timestamp
222 void deleteDataNodes(String dataspaceName, String anchorName, Collection<String> dataNodeXpaths,
223 OffsetDateTime observedTimestamp);
226 * Deletes all data nodes for a given anchor in a dataspace.
228 * @param dataspaceName dataspace name
229 * @param anchorName anchor name
230 * @param observedTimestamp observed timestamp
232 void deleteDataNodes(String dataspaceName, String anchorName, OffsetDateTime observedTimestamp);
235 * Deletes all data nodes for multiple anchors in a dataspace.
237 * @param dataspaceName dataspace name
238 * @param anchorNames anchor names
239 * @param observedTimestamp observed timestamp
241 void deleteDataNodes(String dataspaceName, Collection<String> anchorNames, OffsetDateTime observedTimestamp);
244 * Deletes a list or a list-element under given anchor and dataspace.
246 * @param dataspaceName dataspace name
247 * @param anchorName anchor name
248 * @param listElementXpath list element xpath
249 * @param observedTimestamp observedTimestamp
251 void deleteListOrListElement(String dataspaceName, String anchorName, String listElementXpath,
252 OffsetDateTime observedTimestamp);
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
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
265 void updateNodeLeavesAndExistingDescendantLeaves(String dataspaceName, String anchorName, String parentNodeXpath,
266 String dataNodeUpdatesAsJson, OffsetDateTime observedTimestamp);
269 * Starts a session which allows use of locks and batch interaction with the persistence service.
271 * @return Session ID string
273 String startSession();
278 * @param sessionId session ID
281 void closeSession(String sessionId);
284 * Lock anchor with default timeout.
285 * To release locks(s), the session holding the lock(s) must be closed.
287 * @param sessionID session ID
288 * @param dataspaceName dataspace name
289 * @param anchorName anchor name
291 void lockAnchor(String sessionID, String dataspaceName, String anchorName);
294 * Lock anchor with custom timeout.
295 * To release locks(s), the session holding the lock(s) must be closed.
297 * @param sessionID session ID
298 * @param dataspaceName dataspace name
299 * @param anchorName anchor name
300 * @param timeoutInMilliseconds lock attempt timeout in milliseconds
302 void lockAnchor(String sessionID, String dataspaceName, String anchorName, Long timeoutInMilliseconds);