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 Copyrighted [year] [name of copyright owner]".
13 *
14 * Copyright 2012-2015 ForgeRock AS.
15 */
16
17 package org.forgerock.json.resource;
18
19 import java.util.Collection;
20
21 import org.forgerock.services.context.Context;
22
23 /**
24 * An interface for implementing synchronous {@link RequestHandler}s. A
25 * synchronous request handler will block the caller until an operation has
26 * completed which may impact scalability in many environments, such as
27 * application servers. Therefore it is recommended that request handlers which
28 * are intended for use in production environments implement the asynchronous
29 * {@link RequestHandler} interface. This interface can be easily "mocked" and
30 * is therefore suitable for use in unit tests.
31 * <p>
32 * A synchronous request handler can be adapted as a {@link RequestHandler}
33 * using the {@link Resources#asRequestHandler(SynchronousRequestHandler)}
34 * method.
35 * <p>
36 * For more documentation about the individual operations see
37 * {@link RequestHandler}.
38 *
39 * @see RequestHandler
40 * @see Resources#asRequestHandler(SynchronousRequestHandler)
41 */
42 public interface SynchronousRequestHandler {
43
44 /**
45 * Handles performing an action on a resource, and optionally returns an
46 * associated result. The execution of an action is allowed to incur side
47 * effects.
48 *
49 * @param context
50 * The request server context, such as associated principal.
51 * @param request
52 * The action request.
53 * @return The possibly {@code null} result of the action.
54 * @throws ResourceException
55 * If the request failed for some reason.
56 * @see RequestHandler#handleAction(Context, ActionRequest)
57 */
58 ActionResponse handleAction(Context context, ActionRequest request) throws ResourceException;
59
60 /**
61 * Adds a new JSON resource.
62 *
63 * @param context
64 * The request server context, such as associated principal.
65 * @param request
66 * The create request.
67 * @return The new resource.
68 * @throws ResourceException
69 * If the request failed for some reason.
70 * @see RequestHandler#handleCreate(Context, CreateRequest)
71 */
72 ResourceResponse handleCreate(Context context, CreateRequest request) throws ResourceException;
73
74 /**
75 * Deletes a JSON resource.
76 *
77 * @param context
78 * The request server context, such as associated principal.
79 * @param request
80 * The delete request.
81 * @return The deleted resource.
82 * @throws ResourceException
83 * If the request failed for some reason.
84 * @see RequestHandler#handleDelete(Context, DeleteRequest)
85 */
86 ResourceResponse handleDelete(Context context, DeleteRequest request) throws ResourceException;
87
88 /**
89 * Updates a JSON resource by applying a set of changes to its existing
90 * content.
91 *
92 * @param context
93 * The request server context, such as associated principal.
94 * @param request
95 * The patch request.
96 * @return The patched resource.
97 * @throws ResourceException
98 * If the request failed for some reason.
99 * @see RequestHandler#handlePatch(Context, PatchRequest)
100 */
101 ResourceResponse handlePatch(Context context, PatchRequest request) throws ResourceException;
102
103 /**
104 * Searches for all JSON resources matching a user specified set of
105 * criteria.
106 *
107 * @param context
108 * The request server context, such as associated principal.
109 * @param request
110 * The query request.
111 * @param resources
112 * A non-{@code null} collection into which matching resources
113 * should be put.
114 * @return The query result.
115 * @throws ResourceException
116 * If the request failed for some reason.
117 * @see RequestHandler#handleQuery(Context, QueryRequest, QueryResourceHandler)
118 */
119 QueryResponse handleQuery(Context context, QueryRequest request,
120 Collection<ResourceResponse> resources) throws ResourceException;
121
122 /**
123 * Reads a JSON resource.
124 *
125 * @param context
126 * The request server context, such as associated principal.
127 * @param request
128 * The read request.
129 * @return The resource.
130 * @throws ResourceException
131 * If the request failed for some reason.
132 * @see RequestHandler#handleRead(Context, ReadRequest)
133 */
134 ResourceResponse handleRead(Context context, ReadRequest request) throws ResourceException;
135
136 /**
137 * Updates a JSON resource by replacing its existing content with new
138 * content.
139 *
140 * @param context
141 * The request server context, such as associated principal.
142 * @param request
143 * The update request.
144 * @return The updated resource.
145 * @throws ResourceException
146 * If the request failed for some reason.
147 * @see RequestHandler#handleUpdate(Context, UpdateRequest)
148 */
149 ResourceResponse handleUpdate(Context context, UpdateRequest request) throws ResourceException;
150 }