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 2010 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.i18n.LocalizedIllegalArgumentException;
033import org.forgerock.opendj.ldap.ByteString;
034import org.forgerock.opendj.ldap.DecodeException;
035import org.forgerock.opendj.ldap.DecodeOptions;
036import org.forgerock.opendj.ldap.ResultCode;
037import org.forgerock.opendj.ldap.controls.Control;
038import org.forgerock.opendj.ldap.controls.ControlDecoder;
039
040/**
041 * The who am I extended result as defined in RFC 4532. The result includes the
042 * primary authorization identity, in its primary form, that the server has
043 * associated with the user or application entity, but only if the who am I
044 * request succeeded.
045 * <p>
046 * The authorization identity is specified using an authorization ID, or
047 * {@code authzId}, as defined in RFC 4513 section 5.2.1.8.
048 * <p>
049 * The following example demonstrates use of the Who Am I? request and response.
050 *
051 * <pre>
052 * Connection connection = ...;
053 * String name = ...;
054 * char[] password = ...;
055 *
056 * Result result = connection.bind(name, password);
057 * if (result.isSuccess()) {
058 *     WhoAmIExtendedRequest request = Requests.newWhoAmIExtendedRequest();
059 *     WhoAmIExtendedResult extResult = connection.extendedRequest(request);
060 *
061 *     if (extResult.isSuccess()) {
062 *         // Authz ID: "  + extResult.getAuthorizationID());
063 *     }
064 * }
065 * </pre>
066 *
067 * @see org.forgerock.opendj.ldap.requests.WhoAmIExtendedRequest
068 * @see org.forgerock.opendj.ldap.controls.AuthorizationIdentityRequestControl
069 * @see <a href="http://tools.ietf.org/html/rfc4532">RFC 4532 - Lightweight
070 *      Directory Access Protocol (LDAP) "Who am I?" Operation </a>
071 * @see <a href="http://tools.ietf.org/html/rfc4513#section-5.2.1.8">RFC 4513 -
072 *      SASL Authorization Identities (authzId) </a>
073 */
074public interface WhoAmIExtendedResult extends ExtendedResult {
075
076    @Override
077    WhoAmIExtendedResult addControl(Control control);
078
079    @Override
080    WhoAmIExtendedResult addReferralURI(String uri);
081
082    /**
083     * Returns the authorization ID of the user. The authorization ID usually
084     * has the form "dn:" immediately followed by the distinguished name of the
085     * user, or "u:" followed by a user ID string, but other forms are
086     * permitted.
087     *
088     * @return The authorization ID of the user, or {@code null} if this result
089     *         does not contain an authorization ID.
090     */
091    String getAuthorizationID();
092
093    @Override
094    Throwable getCause();
095
096    @Override
097    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
098            throws DecodeException;
099
100    @Override
101    List<Control> getControls();
102
103    @Override
104    String getDiagnosticMessage();
105
106    @Override
107    String getMatchedDN();
108
109    @Override
110    String getOID();
111
112    @Override
113    List<String> getReferralURIs();
114
115    @Override
116    ResultCode getResultCode();
117
118    @Override
119    ByteString getValue();
120
121    @Override
122    boolean hasValue();
123
124    @Override
125    boolean isReferral();
126
127    @Override
128    boolean isSuccess();
129
130    /**
131     * Sets the authorization ID of the user. The authorization ID usually has
132     * the form "dn:" immediately followed by the distinguished name of the
133     * user, or "u:" followed by a user ID string, but other forms are
134     * permitted.
135     *
136     * @param authorizationID
137     *            The authorization ID of the user, which may be {@code null} if
138     *            this result does not contain an authorization ID.
139     * @return This who am I result.
140     * @throws LocalizedIllegalArgumentException
141     *             If {@code authorizationID} was non-empty and did not contain
142     *             a valid authorization ID type.
143     * @throws UnsupportedOperationException
144     *             If this who am I extended result does not permit the
145     *             authorization ID to be set.
146     */
147    WhoAmIExtendedResult setAuthorizationID(String authorizationID);
148
149    @Override
150    WhoAmIExtendedResult setCause(Throwable cause);
151
152    @Override
153    WhoAmIExtendedResult setDiagnosticMessage(String message);
154
155    @Override
156    WhoAmIExtendedResult setMatchedDN(String dn);
157
158    @Override
159    WhoAmIExtendedResult setResultCode(ResultCode resultCode);
160
161}