001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2012-2016 ForgeRock AS.
015 */
016
017package org.forgerock.json.resource;
018
019import java.io.Closeable;
020import java.util.Collection;
021
022import org.forgerock.services.context.Context;
023import org.forgerock.util.promise.Promise;
024
025/**
026 * A client connection to a JSON resource provider over which read and update
027 * requests may be performed.
028 */
029public interface Connection extends Closeable {
030
031    /**
032     * Performs an action against a specific resource, or set of resources. Bulk
033     * updates are an example of an action request.
034     *
035     * @param context
036     *            The request context, such as associated principal.
037     * @param request
038     *            The action request.
039     * @return A JSON object containing the result of the action, the content of
040     *         which is specified by the action.
041     * @throws ResourceException
042     *             If the action could not be performed.
043     * @throws UnsupportedOperationException
044     *             If this connection does not support action requests.
045     * @throws IllegalStateException
046     *             If this connection has already been closed, i.e. if
047     *             {@code isClosed() == true}.
048     */
049    ActionResponse action(Context context, ActionRequest request) throws ResourceException;
050
051    /**
052     * Asynchronously performs an action against a specific resource, or set of
053     * resources. Bulk updates are an example of an action request.
054     *
055     * @param context
056     *            The request context, such as associated principal.
057     * @param request
058     *            The action request.
059     * @return A future representing the result of the request.
060     * @throws UnsupportedOperationException
061     *             If this connection does not support action requests.
062     * @throws IllegalStateException
063     *             If this connection has already been closed, i.e. if
064     *             {@code isClosed() == true}.
065     */
066    Promise<ActionResponse, ResourceException> actionAsync(Context context, ActionRequest request);
067
068    /**
069     * Releases any resources associated with this connection. For physical
070     * connections to a server this will mean that the underlying socket is
071     * closed.
072     * <p>
073     * Other connection implementations may behave differently. For example, a
074     * pooled connection will be released and returned to its connection pool.
075     * <p>
076     * Calling {@code close} on a connection that is already closed has no
077     * effect.
078     */
079    void close();
080
081    /**
082     * Adds a new JSON resource.
083     *
084     * @param context
085     *            The request context, such as associated principal.
086     * @param request
087     *            The create request.
088     * @return The newly created JSON resource.
089     * @throws ResourceException
090     *             If the JSON resource could not be created.
091     * @throws UnsupportedOperationException
092     *             If this connection does not support create requests.
093     * @throws IllegalStateException
094     *             If this connection has already been closed, i.e. if
095     *             {@code isClosed() == true}.
096     */
097    ResourceResponse create(Context context, CreateRequest request) throws ResourceException;
098
099    /**
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}