1 /*
2 * The contents of this file are subject to the terms of the Common Development and
3 * Distribution License (the License). You may not use this file except in compliance with the
4 * License.
5 *
6 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
7 * specific language governing permission and limitations under the License.
8 *
9 * When distributing Covered Software, include this CDDL Header Notice in each file and include
10 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
11 * Header, with the fields enclosed by brackets [] replaced by your own identifying
12 * information: "Portions Copyright [year] [name of copyright owner]".
13 *
14 * Copyright 2012-2016 ForgeRock AS.
15 */
16
17 package org.forgerock.json.resource;
18
19 import java.io.Closeable;
20 import java.util.Collection;
21
22 import org.forgerock.services.context.Context;
23 import org.forgerock.util.promise.Promise;
24
25 /**
26 * A client connection to a JSON resource provider over which read and update
27 * requests may be performed.
28 */
29 public interface Connection extends Closeable {
30
31 /**
32 * Performs an action against a specific resource, or set of resources. Bulk
33 * updates are an example of an action request.
34 *
35 * @param context
36 * The request context, such as associated principal.
37 * @param request
38 * The action request.
39 * @return A JSON object containing the result of the action, the content of
40 * which is specified by the action.
41 * @throws ResourceException
42 * If the action could not be performed.
43 * @throws UnsupportedOperationException
44 * If this connection does not support action requests.
45 * @throws IllegalStateException
46 * If this connection has already been closed, i.e. if
47 * {@code isClosed() == true}.
48 */
49 ActionResponse action(Context context, ActionRequest request) throws ResourceException;
50
51 /**
52 * Asynchronously performs an action against a specific resource, or set of
53 * resources. Bulk updates are an example of an action request.
54 *
55 * @param context
56 * The request context, such as associated principal.
57 * @param request
58 * The action request.
59 * @return A future representing the result of the request.
60 * @throws UnsupportedOperationException
61 * If this connection does not support action requests.
62 * @throws IllegalStateException
63 * If this connection has already been closed, i.e. if
64 * {@code isClosed() == true}.
65 */
66 Promise<ActionResponse, ResourceException> actionAsync(Context context, ActionRequest request);
67
68 /**
69 * Releases any resources associated with this connection. For physical
70 * connections to a server this will mean that the underlying socket is
71 * closed.
72 * <p>
73 * Other connection implementations may behave differently. For example, a
74 * pooled connection will be released and returned to its connection pool.
75 * <p>
76 * Calling {@code close} on a connection that is already closed has no
77 * effect.
78 */
79 void close();
80
81 /**
82 * Adds a new JSON resource.
83 *
84 * @param context
85 * The request context, such as associated principal.
86 * @param request
87 * The create request.
88 * @return The newly created JSON resource.
89 * @throws ResourceException
90 * If the JSON resource could not be created.
91 * @throws UnsupportedOperationException
92 * If this connection does not support create requests.
93 * @throws IllegalStateException
94 * If this connection has already been closed, i.e. if
95 * {@code isClosed() == true}.
96 */
97 ResourceResponse create(Context context, CreateRequest request) throws ResourceException;
98
99 /**
100 * Asynchronously adds a new JSON resource.
101 *
102 * @param context
103 * The request context, such as associated principal.
104 * @param request
105 * The create request.
106 * @return A future representing the result of the request.
107 * @throws UnsupportedOperationException
108 * If this connection does not support create requests.
109 * @throws IllegalStateException
110 * If this connection has already been closed, i.e. if
111 * {@code isClosed() == true}.
112 */
113 Promise<ResourceResponse, ResourceException> createAsync(Context context, CreateRequest request);
114
115 /**
116 * Deletes a JSON resource.
117 *
118 * @param context
119 * The request context, such as associated principal.
120 * @param request
121 * The delete request.
122 * @return The deleted JSON resource.
123 * @throws ResourceException
124 * If the JSON resource could not be deleted.
125 * @throws UnsupportedOperationException
126 * If this connection does not support delete requests.
127 * @throws IllegalStateException
128 * If this connection has already been closed, i.e. if
129 * {@code isClosed() == true}.
130 */
131 ResourceResponse delete(Context context, DeleteRequest request) throws ResourceException;
132
133 /**
134 * Asynchronously deletes a JSON resource.
135 *
136 * @param context
137 * The request context, such as associated principal.
138 * @param request
139 * The delete request.
140 * @return A future representing the result of the request.
141 * @throws UnsupportedOperationException
142 * If this connection does not support delete requests.
143 * @throws IllegalStateException
144 * If this connection has already been closed, i.e. if
145 * {@code isClosed() == true}.
146 */
147 Promise<ResourceResponse, ResourceException> deleteAsync(Context context, DeleteRequest request);
148
149 /**
150 * Indicates whether or not this connection has been explicitly closed by
151 * calling {@code close}. This method will not return {@code true} if a
152 * fatal error has occurred on the connection unless {@code close} has been
153 * called.
154 *
155 * @return {@code true} if this connection has been explicitly closed by
156 * calling {@code close}, or {@code false} otherwise.
157 */
158 boolean isClosed();
159
160 /**
161 * Returns {@code true} if this connection has not been closed and no fatal
162 * errors have been detected. This method is guaranteed to return
163 * {@code false} only when it is called after the method {@code close} has
164 * been called.
165 *
166 * @return {@code true} if this connection is valid, {@code false}
167 * otherwise.
168 */
169 boolean isValid();
170
171 /**
172 * Updates a JSON resource by applying a set of changes to its existing
173 * content.
174 *
175 * @param context
176 * The request context, such as associated principal.
177 * @param request
178 * The update request.
179 * @return The updated JSON resource.
180 * @throws ResourceException
181 * If the JSON resource could not be updated.
182 * @throws UnsupportedOperationException
183 * If this connection does not support patch requests.
184 * @throws IllegalStateException
185 * If this connection has already been closed, i.e. if
186 * {@code isClosed() == true}.
187 */
188 ResourceResponse patch(Context context, PatchRequest request) throws ResourceException;
189
190 /**
191 * Asynchronously updates a JSON resource by applying a set of changes to
192 * its existing content.
193 *
194 * @param context
195 * The request context, such as associated principal.
196 * @param request
197 * The patch request.
198 * @return A future representing the result of the request.
199 * @throws UnsupportedOperationException
200 * If this connection does not support patch requests.
201 * @throws IllegalStateException
202 * If this connection has already been closed, i.e. if
203 * {@code isClosed() == true}.
204 */
205 Promise<ResourceResponse, ResourceException> patchAsync(Context context, PatchRequest request);
206
207 /**
208 * Searches for all JSON resources matching a user specified set of
209 * criteria, and returns a {@code Promise} that will be completed with the
210 * results of the search.
211 * <p>
212 * Result processing <b><i>happens-before</i></b> this method returns to the
213 * caller.
214 *
215 * @param context
216 * The request context, such as associated principal.
217 * @param request
218 * The query request.
219 * @param handler
220 * A query resource handler which can be used to process
221 * matching resources as they are received.
222 * @return The query result.
223 * @throws ResourceException
224 * If the query could not be performed.
225 * @throws UnsupportedOperationException
226 * If this connection does not support query requests.
227 * @throws IllegalStateException
228 * If this connection has already been closed, i.e. if
229 * {@code isClosed() == true}.
230 */
231 QueryResponse query(Context context, QueryRequest request, QueryResourceHandler handler)
232 throws ResourceException;
233
234 /**
235 * Searches for all JSON resources matching a user specified set of
236 * criteria, and places the results in the provided collection.
237 *
238 * @param context
239 * The request context, such as associated principal.
240 * @param request
241 * The query request.
242 * @param results
243 * A collection into which matching resources will be added as
244 * they are received.
245 * @return The query result.
246 * @throws ResourceException
247 * If the query could not be performed.
248 * @throws UnsupportedOperationException
249 * If this connection does not support query requests.
250 * @throws IllegalStateException
251 * If this connection has already been closed, i.e. if
252 * {@code isClosed() == true}.
253 */
254 QueryResponse query(Context context, QueryRequest request, Collection<? super ResourceResponse> results)
255 throws ResourceException;
256
257 /**
258 * Asynchronously searches for all JSON resources matching a user specified
259 * set of criteria, and returns a {@code Promise} that will be completed with the
260 * results of the search.
261 * <p>
262 * Result processing <b><i>happens-before</i></b> the returned future
263 * completes.
264 *
265 * @param context
266 * The request context, such as associated principal.
267 * @param request
268 * The create request.
269 * @param handler
270 * A non-{@code null} query resource handler which should be
271 * used to process matching resources as they are received.
272 * @return A future representing the result of the request.
273 * @throws UnsupportedOperationException
274 * If this connection does not support query requests.
275 * @throws IllegalStateException
276 * If this connection has already been closed, i.e. if
277 * {@code isClosed() == true}.
278 */
279 Promise<QueryResponse, ResourceException> queryAsync(Context context, QueryRequest request,
280 QueryResourceHandler handler);
281
282 /**
283 * Reads a JSON resource.
284 *
285 * @param context
286 * The request context, such as associated principal.
287 * @param request
288 * The read request.
289 * @return The JSON resource.
290 * @throws ResourceException
291 * If the JSON resource could not be read.
292 * @throws UnsupportedOperationException
293 * If this connection does not support read requests.
294 * @throws IllegalStateException
295 * If this connection has already been closed, i.e. if
296 * {@code isClosed() == true}.
297 */
298 ResourceResponse read(Context context, ReadRequest request) throws ResourceException;
299
300 /**
301 * Asynchronously reads a JSON resource.
302 *
303 * @param context
304 * The request context, such as associated principal.
305 * @param request
306 * The read request.
307 * @return A future representing the result of the request.
308 * @throws UnsupportedOperationException
309 * If this connection does not support read requests.
310 * @throws IllegalStateException
311 * If this connection has already been closed, i.e. if
312 * {@code isClosed() == true}.
313 */
314 Promise<ResourceResponse, ResourceException> readAsync(Context context, ReadRequest request);
315
316 /**
317 * Updates a JSON resource by replacing its existing content with new
318 * content.
319 *
320 * @param context
321 * The request context, such as associated principal.
322 * @param request
323 * The update request.
324 * @return The updated JSON resource.
325 * @throws ResourceException
326 * If the JSON resource could not be updated.
327 * @throws UnsupportedOperationException
328 * If this connection does not support update requests.
329 * @throws IllegalStateException
330 * If this connection has already been closed, i.e. if
331 * {@code isClosed() == true}.
332 */
333 ResourceResponse update(Context context, UpdateRequest request) throws ResourceException;
334
335 /**
336 * Asynchronously updates a JSON resource by replacing its existing content
337 * with new content.
338 *
339 * @param context
340 * The request context, such as associated principal.
341 * @param request
342 * The update request.
343 * @return A future representing the result of the request.
344 * @throws UnsupportedOperationException
345 * If this connection does not support update requests.
346 * @throws IllegalStateException
347 * If this connection has already been closed, i.e. if
348 * {@code isClosed() == true}.
349 */
350 Promise<ResourceResponse, ResourceException> updateAsync(Context context, UpdateRequest request);
351 }