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 org.forgerock.services.context.Context;
20 import org.forgerock.util.promise.Promise;
21
22 /**
23 * An implementation interface for resource providers which exposes a collection
24 * of resource instances. The resource collection supports the following
25 * operations:
26 * <ul>
27 * <li>action
28 * <li>create - with an optional client provided resource ID as part of the
29 * request itself
30 * <li>query
31 * </ul>
32 * Whereas resource instances within the collection support the following
33 * operations:
34 * <ul>
35 * <li>action
36 * <li>delete
37 * <li>patch
38 * <li>read
39 * <li>update
40 * </ul>
41 * <p>
42 * <b>NOTE:</b> field filtering alters the structure of a JSON resource and MUST
43 * only be performed once while processing a request. It is therefore the
44 * responsibility of front-end implementations (e.g. HTTP listeners, Servlets,
45 * etc) to perform field filtering. Request handler and resource provider
46 * implementations SHOULD NOT filter fields, but MAY choose to optimise their
47 * processing in order to return a resource containing only the fields targeted
48 * by the field filters.
49 */
50 public interface CollectionResourceProvider {
51
52 /**
53 * Performs the provided
54 * {@link RequestHandler#handleAction(Context, ActionRequest) action}
55 * against the resource collection.
56 *
57 * @param context
58 * The request server context.
59 * @param request
60 * The action request.
61 * @return A {@code Promise} containing the result of the operation.
62 * @see RequestHandler#handleAction(Context, ActionRequest)
63 */
64 Promise<ActionResponse, ResourceException> actionCollection(Context context, ActionRequest request);
65
66 /**
67 * Performs the provided
68 * {@link RequestHandler#handleAction(Context, ActionRequest)
69 * action} against a resource within the collection.
70 *
71 * @param context
72 * The request server context.
73 * @param resourceId
74 * The ID of the targeted resource within the collection.
75 * @param request
76 * The action request.
77 * @return A {@code Promise} containing the result of the operation.
78 * @see RequestHandler#handleAction(Context, ActionRequest)
79 */
80 Promise<ActionResponse, ResourceException> actionInstance(Context context, String resourceId,
81 ActionRequest request);
82
83 /**
84 * {@link RequestHandler#handleCreate(Context, CreateRequest)
85 * Adds} a new resource instance to the collection.
86 * <p>
87 * Create requests are targeted at the collection itself and may include a
88 * user-provided resource ID for the new resource as part of the request
89 * itself. The user-provider resource ID may be accessed using the method
90 * {@link CreateRequest#getNewResourceId()}.
91 *
92 * @param context
93 * The request server context.
94 * @param request
95 * The create request.
96 * @return A {@code Promise} containing the result of the operation.
97 * @see RequestHandler#handleCreate(Context, CreateRequest)
98 * @see CreateRequest#getNewResourceId()
99 */
100 Promise<ResourceResponse, ResourceException> createInstance(Context context, CreateRequest request);
101
102 /**
103 * {@link RequestHandler#handleDelete(Context, DeleteRequest)
104 * Removes} a resource instance from the collection.
105 *
106 * @param context
107 * The request server context.
108 * @param resourceId
109 * The ID of the targeted resource within the collection.
110 * @param request
111 * The delete request.
112 * @return A {@code Promise} containing the result of the operation.
113 * @see RequestHandler#handleDelete(Context, DeleteRequest)
114 */
115 Promise<ResourceResponse, ResourceException> deleteInstance(Context context, String resourceId,
116 DeleteRequest request);
117
118 /**
119 * {@link RequestHandler#handlePatch(Context, PatchRequest)
120 * Patches} an existing resource within the collection.
121 *
122 * @param context
123 * The request server context.
124 * @param resourceId
125 * The ID of the targeted resource within the collection.
126 * @param request
127 * The patch request.
128 * @return A {@code Promise} containing the result of the operation.
129 * @see RequestHandler#handlePatch(Context, PatchRequest)
130 */
131 Promise<ResourceResponse, ResourceException> patchInstance(Context context, String resourceId,
132 PatchRequest request);
133
134 /**
135 * {@link RequestHandler#handleQuery(Context, QueryRequest, QueryResourceHandler)
136 * Searches} the collection for all resources which match the query request
137 * criteria.
138 * <p>
139 * Implementations must invoke
140 * {@link QueryResourceHandler#handleResource(ResourceResponse)} for each resource
141 * which matches the query criteria. Once all matching resources have been
142 * returned implementations are required to return either a
143 * {@link QueryResponse} if the query has completed successfully, or
144 * {@link ResourceException} if the query did not complete successfully
145 * (even if some matching resources were returned).
146 *
147 * @param context
148 * The request server context.
149 * @param request
150 * The query request.
151 * @param handler
152 * The query resource handler to be notified for each matching
153 * resource.
154 * @return A {@code Promise} containing the result of the operation.
155 * @see RequestHandler#handleQuery(Context, QueryRequest, QueryResourceHandler)
156 */
157 Promise<QueryResponse, ResourceException> queryCollection(Context context, QueryRequest request,
158 QueryResourceHandler handler);
159
160 /**
161 * {@link RequestHandler#handleRead(Context, ReadRequest)
162 * Reads} an existing resource within the collection.
163 *
164 * @param context
165 * The request server context.
166 * @param resourceId
167 * The ID of the targeted resource within the collection.
168 * @param request
169 * The read request.
170 * @return A {@code Promise} containing the result of the operation.
171 * @see RequestHandler#handleRead(Context, ReadRequest)
172 */
173 Promise<ResourceResponse, ResourceException> readInstance(Context context, String resourceId,
174 ReadRequest request);
175
176 /**
177 * {@link RequestHandler#handleUpdate(Context, UpdateRequest)
178 * Updates} an existing resource within the collection.
179 *
180 * @param context
181 * The request server context.
182 * @param resourceId
183 * The ID of the targeted resource within the collection.
184 * @param request
185 * The update request.
186 * @return A {@code Promise} containing the result of the operation.
187 * @see RequestHandler#handleUpdate(Context, UpdateRequest)
188 */
189 Promise<ResourceResponse, ResourceException> updateInstance(Context context, String resourceId,
190 UpdateRequest request);
191 }