2 * ============LICENSE_START=======================================================
3 * Copyright (C) 2020-2022 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 * Updates data node for given dataspace and anchor using xpath to parent node.
128 * @param dataspaceName dataspace name
129 * @param anchorName anchor name
130 * @param parentNodeXpath xpath to parent node
131 * @param jsonData json data
132 * @param observedTimestamp observedTimestamp
134 void updateNodeLeaves(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
135 OffsetDateTime observedTimestamp);
138 * Replaces an existing data node's content including descendants.
140 * @param dataspaceName dataspace name
141 * @param anchorName anchor name
142 * @param parentNodeXpath xpath to parent node
143 * @param jsonData json data
144 * @param observedTimestamp observedTimestamp
146 void updateDataNodeAndDescendants(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
147 OffsetDateTime observedTimestamp);
150 * Replaces multiple existing data nodes' content including descendants in a batch operation.
152 * @param dataspaceName dataspace name
153 * @param anchorName anchor name
154 * @param nodesJsonData map of xpath and node JSON data
155 * @param observedTimestamp observedTimestamp
157 void updateDataNodesAndDescendants(String dataspaceName, String anchorName, Map<String, String> nodesJsonData,
158 OffsetDateTime observedTimestamp);
161 * Replaces list content by removing all existing elements and inserting the given new elements as json
162 * under given parent, anchor and dataspace.
164 * @param dataspaceName dataspace name
165 * @param anchorName anchor name
166 * @param parentNodeXpath parent node xpath
167 * @param jsonData json data representing the new list elements
168 * @param observedTimestamp observedTimestamp
170 void replaceListContent(String dataspaceName, String anchorName, String parentNodeXpath, String jsonData,
171 OffsetDateTime observedTimestamp);
174 * Replaces list content by removing all existing elements and inserting the given new elements as data nodes
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 dataNodes datanodes representing the updated data
181 * @param observedTimestamp observedTimestamp
183 void replaceListContent(String dataspaceName, String anchorName, String parentNodeXpath,
184 Collection<DataNode> dataNodes, OffsetDateTime observedTimestamp);
187 * Deletes data node for given anchor and dataspace.
189 * @param dataspaceName dataspace name
190 * @param anchorName anchor name
191 * @param dataNodeXpath data node xpath
192 * @param observedTimestamp observed timestamp
194 void deleteDataNode(String dataspaceName, String anchorName, String dataNodeXpath,
195 OffsetDateTime observedTimestamp);
198 * Deletes all data nodes for a given anchor in a dataspace.
200 * @param dataspaceName dataspace name
201 * @param anchorName anchor name
202 * @param observedTimestamp observed timestamp
204 void deleteDataNodes(String dataspaceName, String anchorName, OffsetDateTime observedTimestamp);
207 * Deletes a list or a list-element under given anchor and dataspace.
209 * @param dataspaceName dataspace name
210 * @param anchorName anchor name
211 * @param listElementXpath list element xpath
212 * @param observedTimestamp observedTimestamp
214 void deleteListOrListElement(String dataspaceName, String anchorName, String listElementXpath,
215 OffsetDateTime observedTimestamp);
218 * Updates leaves of DataNode for given dataspace and anchor using xpath, along with the leaves of each Child Data
219 * Node which already exists. This method will throw an exception if data node update or any descendant update does
222 * @param dataspaceName dataspace name
223 * @param anchorName anchor name
224 * @param parentNodeXpath xpath
225 * @param dataNodeUpdatesAsJson json data representing data node updates
226 * @param observedTimestamp observedTimestamp
228 void updateNodeLeavesAndExistingDescendantLeaves(String dataspaceName, String anchorName, String parentNodeXpath,
229 String dataNodeUpdatesAsJson, OffsetDateTime observedTimestamp);
232 * Starts a session which allows use of locks and batch interaction with the persistence service.
234 * @return Session ID string
236 String startSession();
241 * @param sessionId session ID
244 void closeSession(String sessionId);
247 * Lock anchor with default timeout.
248 * To release locks(s), the session holding the lock(s) must be closed.
250 * @param sessionID session ID
251 * @param dataspaceName dataspace name
252 * @param anchorName anchor name
254 void lockAnchor(String sessionID, String dataspaceName, String anchorName);
257 * Lock anchor with custom timeout.
258 * To release locks(s), the session holding the lock(s) must be closed.
260 * @param sessionID session ID
261 * @param dataspaceName dataspace name
262 * @param anchorName anchor name
263 * @param timeoutInMilliseconds lock attempt timeout in milliseconds
265 void lockAnchor(String sessionID, String dataspaceName, String anchorName, Long timeoutInMilliseconds);