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.DecodeException; 033import org.forgerock.opendj.ldap.DecodeOptions; 034import org.forgerock.opendj.ldap.ResultCode; 035import org.forgerock.opendj.ldap.controls.Control; 036import org.forgerock.opendj.ldap.controls.ControlDecoder; 037 038/** 039 * A Result is used to indicate the status of an operation performed by the 040 * server. A Result is comprised of several fields: 041 * <ul> 042 * <li>The <b>result code</b> can be retrieved using the method 043 * {@link #getResultCode}. This indicates the overall outcome of the operation. 044 * In particular, whether or not it succeeded which is indicated using a value 045 * of {@link ResultCode#SUCCESS}. 046 * <li>The optional <b>diagnostic message</b> can be retrieved using the method 047 * {@link #getDiagnosticMessage}. At the server's discretion, a diagnostic 048 * message may be included in a Result in order to supplement the result code 049 * with additional human-readable information. 050 * <li>The optional <b>matched DN</b> can be retrieved using the method 051 * {@link #getMatchedDN}. For certain result codes, this is used to indicate to 052 * the client the last entry used in finding the Request's target (or base) 053 * entry. 054 * <li>The optional <b>referrals</b> can be retrieved using the method 055 * {@link #getReferralURIs}. Referrals are present in a Result if the result 056 * code is set to {@link ResultCode#REFERRAL}, and it are absent with all other 057 * result codes. 058 * </ul> 059 */ 060public interface Result extends Response { 061 062 @Override 063 Result addControl(Control control); 064 065 /** 066 * Adds the provided referral URI to this result. 067 * 068 * @param uri 069 * The referral URI to be added. 070 * @return This result. 071 * @throws UnsupportedOperationException 072 * If this result does not permit referrals to be added. 073 * @throws NullPointerException 074 * If {@code uri} was {@code null}. 075 */ 076 Result addReferralURI(String uri); 077 078 /** 079 * Returns the throwable cause associated with this result if available. A 080 * cause may be provided in cases where a result indicates a failure due to 081 * a client-side error. 082 * 083 * @return The throwable cause, or {@code null} if none was provided. 084 */ 085 Throwable getCause(); 086 087 @Override 088 <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options) 089 throws DecodeException; 090 091 @Override 092 List<Control> getControls(); 093 094 /** 095 * Returns the diagnostic message associated with this result. 096 * 097 * @return The diagnostic message, which may be empty if none was provided 098 * (never {@code null}). 099 */ 100 String getDiagnosticMessage(); 101 102 /** 103 * Returns the matched DN associated with this result. 104 * 105 * @return The matched DN, which may be empty if none was provided (never 106 * {@code null}). 107 */ 108 String getMatchedDN(); 109 110 /** 111 * Returns a {@code List} containing the referral URIs included with this 112 * result. The returned {@code List} may be modified if permitted by this 113 * result. 114 * 115 * @return A {@code List} containing the referral URIs. 116 */ 117 List<String> getReferralURIs(); 118 119 /** 120 * Returns the result code associated with this result. 121 * 122 * @return The result code. 123 */ 124 ResultCode getResultCode(); 125 126 /** 127 * Indicates whether or not a referral needs to be chased in order to 128 * complete the operation. 129 * <p> 130 * Specifically, this method returns {@code true} if the result code is 131 * equal to {@link ResultCode#REFERRAL}. 132 * 133 * @return {@code true} if a referral needs to be chased, otherwise 134 * {@code false}. 135 */ 136 boolean isReferral(); 137 138 /** 139 * Indicates whether or not the request succeeded or not. This method will 140 * return {code true} for all non-error responses. 141 * 142 * @return {@code true} if the request succeeded, otherwise {@code false}. 143 */ 144 boolean isSuccess(); 145 146 /** 147 * Sets the throwable cause associated with this result if available. A 148 * cause may be provided in cases where a result indicates a failure due to 149 * a client-side error. 150 * 151 * @param cause 152 * The throwable cause, which may be {@code null} indicating that 153 * none was provided. 154 * @return This result. 155 * @throws UnsupportedOperationException 156 * If this result does not permit the cause to be set. 157 */ 158 Result setCause(Throwable cause); 159 160 /** 161 * Sets the diagnostic message associated with this result. 162 * 163 * @param message 164 * The diagnostic message, which may be empty or {@code null} 165 * indicating that none was provided. 166 * @return This result. 167 * @throws UnsupportedOperationException 168 * If this result does not permit the diagnostic message to be 169 * set. 170 */ 171 Result setDiagnosticMessage(String message); 172 173 /** 174 * Sets the matched DN associated with this result. 175 * 176 * @param dn 177 * The matched DN associated, which may be empty or {@code null} 178 * indicating that none was provided. 179 * @return This result. 180 * @throws UnsupportedOperationException 181 * If this result does not permit the matched DN to be set. 182 */ 183 Result setMatchedDN(String dn); 184 185 /** 186 * Sets the result code associated with this result. 187 * 188 * @param resultCode 189 * The result code. 190 * @return This result. 191 * @throws UnsupportedOperationException 192 * If this result does not permit the result code to be set. 193 * @throws NullPointerException 194 * If {@code resultCode} was {@code null}. 195 */ 196 Result setResultCode(ResultCode resultCode); 197 198}