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 Copyrighted [year] [name of copyright owner]".
013 *
014 * Copyright 2012-2015 ForgeRock AS.
015 */
016
017package org.forgerock.json.resource;
018
019/**
020 * A completion handler for consuming the results of a query request.
021 * <p>
022 * A query result completion handler may be specified when performing query
023 * requests using a {@link Connection} object. The {@link #handleResource}
024 * method is invoked for each resource which matches the query criteria,
025 * followed by returning a {@link QueryResponse} or a {@link ResourceException}
026 * indicating that no more JSON resources will be returned.
027 * <p>
028 * Implementations of these methods should complete in a timely manner so as to
029 * avoid keeping the invoking thread from dispatching to other completion
030 * handlers.
031 * <p>
032 * <b>Synchronization note:</b> each invocation of
033 * {@link #handleResource(ResourceResponse) handleResource} for a resource <i><a href=
034 * "http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/package-summary.html#MemoryVisibility"
035 * >happens-before</a></i> the invocation of {@code handleResource} for the next
036 * resource. Invocation of {@code handleResource} for the final resource
037 * <i>happens-before</i> returning a {@link QueryResponse} or a
038 * {@link ResourceException} are invoked with the final query status. In other
039 * words, query resource handler method invocations will occur sequentially and
040 * one at a time.
041 */
042public interface QueryResourceHandler {
043
044    /**
045     * Invoked each time a matching JSON resource is returned from a query
046     * request. More specifically, if a query request matches 10 resources, then
047     * this method will be invoked 10 times, once for each matching resource.
048     *
049     * <p>Refer to
050     * {@link RequestHandler#handleQuery(org.forgerock.services.context.Context, QueryRequest, QueryResourceHandler)}
051     * for information regarding the concurrency and the order in which events
052     * are processed.</p>
053     *
054     * @param resource
055     *            The matching JSON resource.
056     * @return {@code true} if this handler should continue to be notified of
057     *         any remaining matching JSON resources, or {@code false} if the
058     *         remaining JSON resources should be skipped for some reason (e.g.
059     *         a client side size limit has been reached).
060     */
061    boolean handleResource(ResourceResponse resource);
062}