001    /*
002     * Copyright 2007-2016 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2008-2016 UnboundID Corp.
007     *
008     * This program is free software; you can redistribute it and/or modify
009     * it under the terms of the GNU General Public License (GPLv2 only)
010     * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011     * as published by the Free Software Foundation.
012     *
013     * This program is distributed in the hope that it will be useful,
014     * but WITHOUT ANY WARRANTY; without even the implied warranty of
015     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016     * GNU General Public License for more details.
017     *
018     * You should have received a copy of the GNU General Public License
019     * along with this program; if not, see <http://www.gnu.org/licenses>.
020     */
021    package com.unboundid.ldap.sdk.controls;
022    
023    
024    
025    import com.unboundid.ldap.sdk.Control;
026    import com.unboundid.ldap.sdk.LDAPException;
027    import com.unboundid.ldap.sdk.ResultCode;
028    import com.unboundid.util.NotMutable;
029    import com.unboundid.util.ThreadSafety;
030    import com.unboundid.util.ThreadSafetyLevel;
031    
032    import static com.unboundid.ldap.sdk.controls.ControlMessages.*;
033    
034    
035    
036    /**
037     * This class provides an implementation of the authorization identity bind
038     * request control as described in
039     * <A HREF="http://www.ietf.org/rfc/rfc3829.txt">RFC 3829</A>.  It may be
040     * included in a bind request to request that the server include the
041     * authorization identity associated with the client connection in the bind
042     * response message, in the form of an
043     * {@link AuthorizationIdentityResponseControl}.
044     * <BR><BR>
045     * The authorization identity request control is similar to the "Who Am I?"
046     * extended request as implemented in the
047     * {@link com.unboundid.ldap.sdk.extensions.WhoAmIExtendedRequest} class.  The
048     * primary difference between them is that the "Who Am I?" extended request can
049     * be used at any time but requires a separate operation, while the
050     * authorization identity request control can be included only with a bind
051     * request but does not require a separate operation.
052     * <BR><BR>
053     * <H2>Example</H2>
054     * The following example demonstrates the use of the authorization identity
055     * request and response controls.  It authenticates to the directory server and
056     * attempts to retrieve the authorization identity from the response:
057     * <PRE>
058     * String authzID = null;
059     * BindRequest bindRequest =
060     *      new SimpleBindRequest("uid=test.user,ou=People,dc=example,dc=com",
061     *           "password", new AuthorizationIdentityRequestControl());
062     *
063     * BindResult bindResult = connection.bind(bindRequest);
064     * AuthorizationIdentityResponseControl authzIdentityResponse =
065     *      AuthorizationIdentityResponseControl.get(bindResult);
066     * if (authzIdentityResponse != null)
067     * {
068     *   authzID = authzIdentityResponse.getAuthorizationID();
069     * }
070     * </PRE>
071     */
072    @NotMutable()
073    @ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
074    public final class AuthorizationIdentityRequestControl
075           extends Control
076    {
077      /**
078       * The OID (2.16.840.1.113730.3.4.16) for the authorization identity request
079       * control.
080       */
081      public static final String AUTHORIZATION_IDENTITY_REQUEST_OID =
082           "2.16.840.1.113730.3.4.16";
083    
084    
085    
086      /**
087       * The serial version UID for this serializable class.
088       */
089      private static final long serialVersionUID = -4059607155175828138L;
090    
091    
092    
093      /**
094       * Creates a new authorization identity request control.  The control will not
095       * be marked critical.
096       */
097      public AuthorizationIdentityRequestControl()
098      {
099        super(AUTHORIZATION_IDENTITY_REQUEST_OID, false, null);
100      }
101    
102    
103    
104      /**
105       * Creates a new authorization identity request control.
106       *
107       * @param  isCritical  Indicates whether the control should be marked
108       *                     critical.
109       */
110      public AuthorizationIdentityRequestControl(final boolean isCritical)
111      {
112        super(AUTHORIZATION_IDENTITY_REQUEST_OID, isCritical, null);
113      }
114    
115    
116    
117      /**
118       * Creates a new authorization identity request control which is decoded from
119       * the provided generic control.
120       *
121       * @param  control  The generic control to be decoded as an authorization
122       *                  identity request control.
123       *
124       * @throws  LDAPException  If the provided control cannot be decoded as an
125       *                         authorization identity request control.
126       */
127      public AuthorizationIdentityRequestControl(final Control control)
128             throws LDAPException
129      {
130        super(control);
131    
132        if (control.hasValue())
133        {
134          throw new LDAPException(ResultCode.DECODING_ERROR,
135                                  ERR_AUTHZID_REQUEST_HAS_VALUE.get());
136        }
137      }
138    
139    
140    
141      /**
142       * {@inheritDoc}
143       */
144      @Override()
145      public String getControlName()
146      {
147        return INFO_CONTROL_NAME_AUTHZID_REQUEST.get();
148      }
149    
150    
151    
152      /**
153       * {@inheritDoc}
154       */
155      @Override()
156      public void toString(final StringBuilder buffer)
157      {
158        buffer.append("AuthorizationIdentityRequestControl(isCritical=");
159        buffer.append(isCritical());
160        buffer.append(')');
161      }
162    }