001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *
024 *      Copyright 2009 Sun Microsystems, Inc.
025 *      Portions copyright 2012 ForgeRock AS.
026 */
027
028package org.forgerock.opendj.ldap.responses;
029
030import java.util.List;
031
032import org.forgerock.opendj.ldap.ByteString;
033import org.forgerock.opendj.ldap.DecodeException;
034import org.forgerock.opendj.ldap.DecodeOptions;
035import org.forgerock.opendj.ldap.controls.Control;
036import org.forgerock.opendj.ldap.controls.ControlDecoder;
037
038/**
039 * An Intermediate response provides a general mechanism for defining
040 * single-request/multiple-response operations. This response is intended to be
041 * used in conjunction with the Extended operation to define new
042 * single-request/multiple-response operations or in conjunction with a control
043 * when extending existing operations in a way that requires them to return
044 * Intermediate response information.
045 * <p>
046 * An Intermediate response may convey an optional response name and value.
047 * These can be retrieved using the {@link #getOID} and {@link #getValue}
048 * methods respectively.
049 *
050 * @see <a href="http://tools.ietf.org/html/rfc3771">RFC 3771 - The Lightweight
051 *      Directory Access Protocol (LDAP) Intermediate Response Message</a>
052 */
053public interface IntermediateResponse extends Response {
054
055    @Override
056    IntermediateResponse addControl(Control control);
057
058    @Override
059    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
060            throws DecodeException;
061
062    @Override
063    List<Control> getControls();
064
065    /**
066     * Returns the numeric OID, if any, associated with this intermediate
067     * response.
068     *
069     * @return The numeric OID associated with this intermediate response, or
070     *         {@code null} if there is no OID.
071     */
072    String getOID();
073
074    /**
075     * Returns the value, if any, associated with this intermediate response.
076     * Its format is defined by the specification of this intermediate response.
077     *
078     * @return The value associated with this intermediate response, or
079     *         {@code null} if there is no value.
080     */
081    ByteString getValue();
082
083    /**
084     * Returns {@code true} if this intermediate response has a value. In some
085     * circumstances it may be useful to determine if an intermediate response
086     * has a value, without actually calculating the value and incurring any
087     * performance costs.
088     *
089     * @return {@code true} if this intermediate response has a value, or
090     *         {@code false} if there is no value.
091     */
092    boolean hasValue();
093
094}