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