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}