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 2009-2010 Sun Microsystems, Inc.
015 * Portions copyright 2011-2014 ForgeRock AS.
016 */
017
018package org.forgerock.opendj.ldap;
019
020import org.forgerock.opendj.ldap.responses.SearchResultEntry;
021import org.forgerock.opendj.ldap.responses.SearchResultReference;
022
023/**
024 * A completion handler for consuming the results of a Search operation.
025 * <p>
026 * {@link Connection} and {@link Connection} objects allow a search result
027 * completion handler to be specified when sending Search operation requests to
028 * a Directory Server. The {@link #handleEntry} method is invoked each time a
029 * Search Result Entry is returned from the Directory Server. The
030 * {@link #handleReference} method is invoked for each Search Result Reference
031 * returned from the Directory Server.
032 * <p>
033 * Implementations of these methods should complete in a timely manner so as to
034 * avoid keeping the invoking thread from dispatching to other completion
035 * handlers.
036 */
037public interface SearchResultHandler {
038    /**
039     * Invoked each time a search result entry is returned from an asynchronous
040     * search operation.
041     *
042     * @param entry
043     *            The search result entry.
044     * @return {@code true} if this handler should continue to be notified of
045     *         any remaining entries and references, or {@code false} if the
046     *         remaining entries and references should be skipped for some
047     *         reason (e.g. a client side size limit has been reached).
048     */
049    boolean handleEntry(SearchResultEntry entry);
050
051    /**
052     * Invoked each time a search result reference is returned from an
053     * asynchronous search operation.
054     *
055     * @param reference
056     *            The search result reference.
057     * @return {@code true} if this handler should continue to be notified of
058     *         any remaining entries and references, or {@code false} if the
059     *         remaining entries and references should be skipped for some
060     *         reason (e.g. a client side size limit has been reached).
061     */
062    boolean handleReference(SearchResultReference reference);
063}