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}