blob: 6d8dbfe5001fc42fd98be487f24f3c68a5e00e30 [file] [log] [blame]
Carmelo Cascone4c289b72019-01-22 15:30:45 -08001/*
2 * Copyright 2019-present Open Networking Foundation
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package org.onosproject.p4runtime.api;
18
19import org.onosproject.net.pi.model.PiPipeconf;
20import org.onosproject.net.pi.runtime.PiEntity;
21import org.onosproject.net.pi.runtime.PiEntityType;
22import org.onosproject.net.pi.runtime.PiHandle;
23
24import java.util.Collection;
25import java.util.concurrent.CompletableFuture;
26
27/**
28 * P4Runtime client interface for the Write RPC that allows inserting, modifying
29 * and deleting PI entities. Allows batching of write requests and it returns a
30 * detailed response for each PI entity in the request.
31 */
32public interface P4RuntimeWriteClient {
33
34 /**
35 * Returns a new {@link WriteRequest} instance that can be used to build a
36 * batched write request, for the given pipeconf.
37 *
38 * @param pipeconf pipeconf
39 * @return new write request
40 */
41 WriteRequest write(PiPipeconf pipeconf);
42
43 /**
44 * Signals the type of write operation for a given PI entity.
45 */
46 enum UpdateType {
47 /**
48 * Inserts an entity.
49 */
50 INSERT,
51 /**
52 * Modifies an existing entity.
53 */
54 MODIFY,
55 /**
56 * Deletes an existing entity.
57 */
58 DELETE
59 }
60
61 /**
62 * Signals if the entity was written successfully or not.
63 */
64 enum WriteResponseStatus {
65 /**
66 * The entity was written successfully, no errors occurred.
67 */
68 OK,
69 /**
70 * The server didn't return any status for the entity.
71 */
72 PENDING,
73 /**
74 * The entity was not added to the write request because it was not
75 * possible to encode/decode it.
76 */
77 CODEC_ERROR,
78 /**
79 * Server responded that it was not possible to insert the entity as
80 * another one with the same handle already exists.
81 */
82 ALREADY_EXIST,
83 /**
84 * Server responded that it was not possible to modify or delete the
85 * entity as the same cannot be found on the server.
86 */
87 NOT_FOUND,
88 /**
89 * Other error. See {@link WriteEntityResponse#explanation()} or {@link
90 * WriteEntityResponse#throwable()} for more details.
91 */
92 OTHER_ERROR,
93 }
94
95 /**
96 * Signals the atomicity mode that the server should follow when executing a
97 * write request. For more information on each atomicity mode please see the
98 * P4Runtime spec.
99 */
100 enum Atomicity {
101 /**
102 * Continue on error. Default value for all write requests.
103 */
104 CONTINUE_ON_ERROR,
105 /**
106 * Rollback on error.
107 */
108 ROLLBACK_ON_ERROR,
109 /**
110 * Dataplane atomic.
111 */
112 DATAPLANE_ATOMIC,
113 }
114
115 /**
116 * Abstraction of a P4Runtime write request that follows the builder
117 * pattern. Multiple entities can be added to the same request before
118 * submitting it. The implementation should guarantee that entities are
119 * added in the final P4Runtime protobuf message in the same order as added
120 * in this write request.
121 */
122 interface WriteRequest {
123
124 /**
125 * Sets the atomicity mode of this write request. Default value is
126 * {@link Atomicity#CONTINUE_ON_ERROR}.
127 *
128 * @param atomicity atomicity mode
129 * @return this
130 */
131 WriteRequest withAtomicity(Atomicity atomicity);
132
133 /**
134 * Requests to insert one PI entity.
135 *
136 * @param entity PI entity
137 * @return this
138 */
139 WriteRequest insert(PiEntity entity);
140
141 /**
142 * Requests to insert multiple PI entities.
143 *
144 * @param entities iterable of PI entities
145 * @return this
146 */
147 WriteRequest insert(Iterable<? extends PiEntity> entities);
148
149 /**
150 * Requests to modify one PI entity.
151 *
152 * @param entity PI entity
153 * @return this
154 */
155 WriteRequest modify(PiEntity entity);
156
157 /**
158 * Requests to modify multiple PI entities.
159 *
160 * @param entities iterable of PI entities
161 * @return this
162 */
163 WriteRequest modify(Iterable<? extends PiEntity> entities);
164
165 /**
166 * Requests to delete one PI entity identified by the given handle.
167 *
168 * @param handle PI handle
169 * @return this
170 */
171 WriteRequest delete(PiHandle handle);
172
173 /**
174 * Requests to delete multiple PI entities identified by the given
175 * handles.
176 *
177 * @param handles iterable of handles
178 * @return this
179 */
180 WriteRequest delete(Iterable<? extends PiHandle> handles);
181
182 /**
183 * Requests to write the given PI entity with the given update type. If
184 * {@code updateType} is {@link UpdateType#DELETE}, then only the handle
185 * will be considered by the request.
186 *
187 * @param entity PI entity
188 * @param updateType update type
189 * @return this
190 */
191 WriteRequest entity(PiEntity entity, UpdateType updateType);
192
193 /**
194 * Requests to write the given PI entities with the given update type.
195 * If {@code updateType} is {@link UpdateType#DELETE}, then only the
196 * handles will be considered by the request.
197 *
198 * @param entities iterable of PI entity
199 * @param updateType update type
200 * @return this
201 */
202 WriteRequest entities(Iterable<? extends PiEntity> entities, UpdateType updateType);
203
204 /**
205 * Submits this write request to the server and returns a completable
206 * future holding the response. The future is completed only after the
207 * server signals that all entities are written.
208 *
209 * @return completable future of the write response
210 */
211 CompletableFuture<WriteResponse> submit();
212
213 /**
214 * Similar to {@link #submit()}, but blocks until the operation is
215 * completed, after which, it returns a read response.
216 *
217 * @return read response
218 */
219 P4RuntimeWriteClient.WriteResponse submitSync();
220 }
221
222 /**
223 * Abstraction of a response obtained from a P4Runtime server after a write
224 * request is submitted. It allows returning a detailed response ({@link
225 * WriteEntityResponse}) for each PI entity in the original request. Entity
226 * responses are guaranteed to be returned in the same order as the
227 * corresponding PI entity in the request.
228 */
229 interface WriteResponse {
230
231 /**
232 * Returns true if all entities in the request were successfully
233 * written. In other words, if no errors occurred. False otherwise.
234 *
235 * @return true if all entities were written successfully, false
236 * otherwise
237 */
238 boolean isSuccess();
239
240 /**
241 * Returns a detailed response for each PI entity in the request. The
242 * implementation of this method should guarantee that the returned
243 * collection has size equal to the number of PI entities in the
244 * original write request.
245 *
246 * @return collection of {@link WriteEntityResponse}
247 */
248 Collection<WriteEntityResponse> all();
249
250 /**
251 * Returns a detailed response for each PI entity that was successfully
252 * written. If {@link #isSuccess()} is {@code true}, then this method is
253 * expected to return the same values as {@link #all()}.
254 *
255 * @return collection of {@link WriteEntityResponse}
256 */
257 Collection<WriteEntityResponse> success();
258
259 /**
260 * Returns a detailed response for each PI entity for which the server
261 * returned an error. If {@link #isSuccess()} is {@code true}, then this
262 * method is expected to return an empty collection.
263 *
264 * @return collection of {@link WriteEntityResponse}
265 */
266 Collection<WriteEntityResponse> failed();
267
268 /**
269 * Returns a detailed response for each PI entity for which the server
270 * returned the given status.
271 *
272 * @param status status
273 * @return collection of {@link WriteEntityResponse}
274 */
275 Collection<WriteEntityResponse> status(WriteResponseStatus status);
276 }
277
278 /**
279 * Represents the response of a write request for a specific PI entity.
280 */
281 interface WriteEntityResponse {
282
283 /**
284 * Returns the handle associated with the PI entity.
285 *
286 * @return handle
287 */
288 PiHandle handle();
289
290 /**
291 * Returns the original PI entity as provided in the write request.
292 * Returns {@code null} if the update type was {@link
293 * UpdateType#DELETE}, in which case only the handle was used in the
294 * request.
295 *
296 * @return PI entity or null
297 */
298 PiEntity entity();
299
300 /**
301 * Returns the type of write request performed for this entity.
302 *
303 * @return update type
304 */
305 UpdateType updateType();
306
307 /**
308 * Returns the type of this entity.
309 *
310 * @return PI entity type
311 */
312 PiEntityType entityType();
313
314 /**
315 * Returns true if this PI entity was written successfully, false
316 * otherwise.
317 *
318 * @return true if this PI entity was written successfully, false
319 * otherwise
320 */
321 boolean isSuccess();
322
323 /**
324 * Returns the status for this PI entity. If {@link #isSuccess()}
325 * returns {@code true}, then this method is expected to return {@link
326 * WriteResponseStatus#OK}. If {@link WriteResponseStatus#OTHER_ERROR}
327 * is returned, further details might be provided in {@link
328 * #explanation()} and {@link #throwable()}.
329 *
330 * @return status
331 */
332 WriteResponseStatus status();
333
334 /**
335 * If the PI entity was NOT written successfully, this method returns a
336 * message explaining the error occurred. Returns an empty string if
337 * such message is not available, or {@code null} if no errors
338 * occurred.
339 *
340 * @return error explanation or empty string or null
341 */
342 String explanation();
343
344 /**
345 * If the PI entity was NOT written successfully, this method returns
346 * the internal throwable instance associated with the error (e.g. a
347 * {@link io.grpc.StatusRuntimeException} instance). Returns null if
348 * such throwable instance is not available or if no errors occurred.
349 *
350 * @return throwable instance associated with this PI entity
351 */
352 Throwable throwable();
353 }
354}