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 /**
20 * A completion handler for consuming the results of a query request.
21 * <p>
22 * A query result completion handler may be specified when performing query
23 * requests using a {@link Connection} object. The {@link #handleResource}
24 * method is invoked for each resource which matches the query criteria,
25 * followed by returning a {@link QueryResponse} or a {@link ResourceException}
26 * indicating that no more JSON resources will be returned.
27 * <p>
28 * Implementations of these methods should complete in a timely manner so as to
29 * avoid keeping the invoking thread from dispatching to other completion
30 * handlers.
31 * <p>
32 * <b>Synchronization note:</b> each invocation of
33 * {@link #handleResource(ResourceResponse) handleResource} for a resource <i><a href=
34 * "http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/package-summary.html#MemoryVisibility"
35 * >happens-before</a></i> the invocation of {@code handleResource} for the next
36 * resource. Invocation of {@code handleResource} for the final resource
37 * <i>happens-before</i> returning a {@link QueryResponse} or a
38 * {@link ResourceException} are invoked with the final query status. In other
39 * words, query resource handler method invocations will occur sequentially and
40 * one at a time.
41 */
42 public interface QueryResourceHandler {
43
44 /**
45 * Invoked each time a matching JSON resource is returned from a query
46 * request. More specifically, if a query request matches 10 resources, then
47 * this method will be invoked 10 times, once for each matching resource.
48 *
49 * <p>Refer to
50 * {@link RequestHandler#handleQuery(org.forgerock.services.context.Context, QueryRequest, QueryResourceHandler)}
51 * for information regarding the concurrency and the order in which events
52 * are processed.</p>
53 *
54 * @param resource
55 * The matching JSON resource.
56 * @return {@code true} if this handler should continue to be notified of
57 * any remaining matching JSON resources, or {@code false} if the
58 * remaining JSON resources should be skipped for some reason (e.g.
59 * a client side size limit has been reached).
60 */
61 boolean handleResource(ResourceResponse resource);
62 }