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}