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 2010 Sun Microsystems, Inc.
015 * Portions copyright 2011 ForgeRock AS.
016 */
017
018package org.forgerock.opendj.ldap;
019
020import org.forgerock.opendj.ldap.responses.IntermediateResponse;
021
022/**
023 * A completion handler for consuming intermediate responses returned from
024 * extended operations, or other operations for which an appropriate control was
025 * sent.
026 * <p>
027 * Intermediate responses are rarely used in practice and are therefore only
028 * supported in a few specialized cases where they are most likely to be
029 * encountered:
030 * <ul>
031 * <li>when performing extended requests using the
032 * {@link Connection#extendedRequest} methods
033 * <li>when using the asynchronous operation methods, such as
034 * {@link Connection#addAsync}
035 * </ul>
036 * When no handler is provided any intermediate responses will be discarded.
037 * <p>
038 * The {@link #handleIntermediateResponse} method is invoked each time a
039 * Intermediate Response is returned from the Directory Server.
040 * <p>
041 * Implementations of these methods should complete in a timely manner so as to
042 * avoid keeping the invoking thread from dispatching to other completion
043 * handlers.
044 */
045public interface IntermediateResponseHandler {
046    /**
047     * Invoked each time an intermediate response is returned from the Directory
048     * Server.
049     *
050     * @param response
051     *            The intermediate response.
052     * @return {@code true} if this handler should continue to be notified of
053     *         any remaining intermediate responses, or {@code false} if the
054     *         remaining responses should be skipped for some reason (e.g. a
055     *         client side size limit has been reached).
056     */
057    boolean handleIntermediateResponse(IntermediateResponse response);
058}