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 Sun Microsystems, Inc.
015 * Portions copyright 2012 ForgeRock AS.
016 */
017
018package org.forgerock.opendj.ldap.responses;
019
020import java.util.List;
021
022import org.forgerock.opendj.ldap.ByteString;
023import org.forgerock.opendj.ldap.DecodeException;
024import org.forgerock.opendj.ldap.DecodeOptions;
025import org.forgerock.opendj.ldap.controls.Control;
026import org.forgerock.opendj.ldap.controls.ControlDecoder;
027
028/**
029 * An Intermediate response provides a general mechanism for defining
030 * single-request/multiple-response operations. This response is intended to be
031 * used in conjunction with the Extended operation to define new
032 * single-request/multiple-response operations or in conjunction with a control
033 * when extending existing operations in a way that requires them to return
034 * Intermediate response information.
035 * <p>
036 * An Intermediate response may convey an optional response name and value.
037 * These can be retrieved using the {@link #getOID} and {@link #getValue}
038 * methods respectively.
039 *
040 * @see <a href="http://tools.ietf.org/html/rfc3771">RFC 3771 - The Lightweight
041 *      Directory Access Protocol (LDAP) Intermediate Response Message</a>
042 */
043public interface IntermediateResponse extends Response {
044
045    @Override
046    IntermediateResponse addControl(Control control);
047
048    @Override
049    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
050            throws DecodeException;
051
052    @Override
053    List<Control> getControls();
054
055    /**
056     * Returns the numeric OID, if any, associated with this intermediate
057     * response.
058     *
059     * @return The numeric OID associated with this intermediate response, or
060     *         {@code null} if there is no OID.
061     */
062    String getOID();
063
064    /**
065     * Returns the value, if any, associated with this intermediate response.
066     * Its format is defined by the specification of this intermediate response.
067     *
068     * @return The value associated with this intermediate response, or
069     *         {@code null} if there is no value.
070     */
071    ByteString getValue();
072
073    /**
074     * Returns {@code true} if this intermediate response has a value. In some
075     * circumstances it may be useful to determine if an intermediate response
076     * has a value, without actually calculating the value and incurring any
077     * performance costs.
078     *
079     * @return {@code true} if this intermediate response has a value, or
080     *         {@code false} if there is no value.
081     */
082    boolean hasValue();
083
084}