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}