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 * ================================================================================
8 * Licensed under the Apache License, Version 2.0 (the "License");
9 * you may not use this file except in compliance with the License.
10 * You may obtain a copy of the License at
12 * http://www.apache.org/licenses/LICENSE-2.0
14 * Unless required by applicable law or agreed to in writing, software
15 * distributed under the License is distributed on an "AS IS" BASIS,
16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17 * See the License for the specific language governing permissions and
18 * limitations under the License.
20 * SPDX-License-Identifier: Apache-2.0
21 * ============LICENSE_END=========================================================
24 package org.onap.cps.api;
26 import java.time.OffsetDateTime;
27 import java.util.Collection;
29 import org.onap.cps.spi.FetchDescendantsOption;
30 import org.onap.cps.spi.model.DataNode;
31 import org.onap.cps.utils.ContentType;
34 * Datastore interface for handling CPS data.
36 public interface CpsDataService {
39 * Persists data for the given anchor and dataspace.
41 * @param dataspaceName dataspace name
42 * @param anchorName anchor name
43 * @param nodeData node data
44 * @param observedTimestamp observedTimestamp
46 void saveData(String dataspaceName, String anchorName, String nodeData, OffsetDateTime observedTimestamp);
49 * Persists data for the given anchor and dataspace.
51 * @param dataspaceName dataspace name
52 * @param anchorName anchor name
53 * @param nodeData node data
54 * @param observedTimestamp observedTimestamp
55 * @param contentType node data content type
57 void saveData(String dataspaceName, String anchorName, String nodeData, OffsetDateTime observedTimestamp,
58 ContentType contentType);
61 * Persists child data fragment under existing data node for the given anchor and dataspace.
63 * @param dataspaceName dataspace name
64 * @param anchorName anchor name
65 * @param parentNodeXpath parent node xpath
66 * @param nodeData node data
67 * @param observedTimestamp observedTimestamp
69 void saveData(String dataspaceName, String anchorName, String parentNodeXpath, String nodeData,
70 OffsetDateTime observedTimestamp);
73 * Persists child data fragment under existing data node for the given anchor, dataspace and content type.
75 * @param dataspaceName dataspace name
76 * @param anchorName anchor name
77 * @param parentNodeXpath parent node xpath
78 * @param nodeData node data
79 * @param observedTimestamp observedTimestamp
80 * @param contentType node data content type
83 void saveData(String dataspaceName, String anchorName, String parentNodeXpath, String nodeData,
84 OffsetDateTime observedTimestamp, ContentType contentType);
87 * Persists child data fragment representing one or more list elements under existing data node for the
88 * given anchor and dataspace.
90 * @param dataspaceName dataspace name
91 * @param anchorName anchor name
92 * @param parentNodeXpath parent node xpath
93 * @param jsonData json data representing list element(s)
94 * @param observedTimestamp observedTimestamp
96 void saveListElements(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
97 OffsetDateTime observedTimestamp);
100 * Persists child data fragment representing one or more list elements under existing data node for the
101 * given anchor and dataspace.
103 * @param dataspaceName dataspace name
104 * @param anchorName anchor name
105 * @param parentNodeXpath parent node xpath
106 * @param jsonDataList collection of json data representing list element(s)
107 * @param observedTimestamp observedTimestamp
109 void saveListElementsBatch(String dataspaceName, String anchorName, String parentNodeXpath,
110 Collection<String> jsonDataList, OffsetDateTime observedTimestamp);
113 * Retrieves datanode by XPath for given dataspace and anchor.
115 * @param dataspaceName dataspace name
116 * @param anchorName anchor name
118 * @param fetchDescendantsOption defines the scope of data to fetch: either single node or all the descendant nodes
119 * (recursively) as well
120 * @return data node object
122 DataNode getDataNode(String dataspaceName, String anchorName, String xpath,
123 FetchDescendantsOption fetchDescendantsOption);
126 * Retrieves datanodes by XPath for given dataspace and anchor.
128 * @param dataspaceName dataspace name
129 * @param anchorName anchor name
130 * @param xpaths collection of xpath
131 * @param fetchDescendantsOption defines the scope of data to fetch: either single node or all the descendant nodes
132 * (recursively) as well
133 * @return data node object
135 Collection<DataNode> getDataNodes(String dataspaceName, String anchorName, Collection<String> xpaths,
136 FetchDescendantsOption fetchDescendantsOption);
139 * Updates data node for given dataspace and anchor using xpath to parent node.
141 * @param dataspaceName dataspace name
142 * @param anchorName anchor name
143 * @param parentNodeXpath xpath to parent node
144 * @param jsonData json data
145 * @param observedTimestamp observedTimestamp
147 void updateNodeLeaves(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
148 OffsetDateTime observedTimestamp);
151 * Replaces an existing data node's content including descendants.
153 * @param dataspaceName dataspace name
154 * @param anchorName anchor name
155 * @param parentNodeXpath xpath to parent node
156 * @param jsonData json data
157 * @param observedTimestamp observedTimestamp
159 void updateDataNodeAndDescendants(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
160 OffsetDateTime observedTimestamp);
163 * Replaces multiple existing data nodes' content including descendants in a batch operation.
165 * @param dataspaceName dataspace name
166 * @param anchorName anchor name
167 * @param nodesJsonData map of xpath and node JSON data
168 * @param observedTimestamp observedTimestamp
170 void updateDataNodesAndDescendants(String dataspaceName, String anchorName, Map<String, String> nodesJsonData,
171 OffsetDateTime observedTimestamp);
174 * Replaces list content by removing all existing elements and inserting the given new elements as json
175 * under given parent, anchor and dataspace.
177 * @param dataspaceName dataspace name
178 * @param anchorName anchor name
179 * @param parentNodeXpath parent node xpath
180 * @param jsonData json data representing the new list elements
181 * @param observedTimestamp observedTimestamp
183 void replaceListContent(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
184 OffsetDateTime observedTimestamp);
187 * Replaces list content by removing all existing elements and inserting the given new elements as data nodes
188 * under given parent, anchor and dataspace.
190 * @param dataspaceName dataspace-name
191 * @param anchorName anchor name
192 * @param parentNodeXpath parent node xpath
193 * @param dataNodes datanodes representing the updated data
194 * @param observedTimestamp observedTimestamp
196 void replaceListContent(String dataspaceName, String anchorName, String parentNodeXpath,
197 Collection<DataNode> dataNodes, OffsetDateTime observedTimestamp);
200 * Deletes data node for given anchor and dataspace.
202 * @param dataspaceName dataspace name
203 * @param anchorName anchor name
204 * @param dataNodeXpath data node xpath
205 * @param observedTimestamp observed timestamp
207 void deleteDataNode(String dataspaceName, String anchorName, String dataNodeXpath,
208 OffsetDateTime observedTimestamp);
211 * Deletes multiple data nodes for given anchor and dataspace.
213 * @param dataspaceName dataspace name
214 * @param anchorName anchor name
215 * @param dataNodeXpaths data node xpaths
216 * @param observedTimestamp observed timestamp
218 void deleteDataNodes(String dataspaceName, String anchorName, Collection<String> dataNodeXpaths,
219 OffsetDateTime observedTimestamp);
222 * Deletes all data nodes for a given anchor in a dataspace.
224 * @param dataspaceName dataspace name
225 * @param anchorName anchor name
226 * @param observedTimestamp observed timestamp
228 void deleteDataNodes(String dataspaceName, String anchorName, 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);