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