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 ManageDsaIT control as described
038     * in <A HREF="http://www.ietf.org/rfc/rfc3296.txt">RFC 3296</A>.  This control
039     * may be used to request that the directory server treat all entries as if they
040     * were regular entries.
041     * <BR><BR>
042     * One of the most common uses of the ManageDsaIT control is to request that the
043     * directory server to treat an entry containing the "{@code referral}" object
044     * class as a regular entry rather than a smart referral.  Normally, when the
045     * server encounters an entry with the {@code referral} object class, it sends
046     * a referral with the URLs contained in the {@code ref} attribute of that
047     * entry.  However, if the ManageDsaIT control is included then the operation
048     * will attempt to operate on the referral definition itself rather than sending
049     * that referral to the client.
050     * <BR><BR>
051     * <H2>Example</H2>
052     * The following example demonstrates the use of the ManageDsaIT control to
053     * delete an entry that may or may not be a referral:
054     * <PRE>
055     * // Establish a connection to the directory server.  Even though it's the
056     * // default behavior, we'll explicitly configure the connection to not follow
057     * // referrals.
058     * LDAPConnectionOptions connectionOptions = new LDAPConnectionOptions();
059     * connectionOptions.setFollowReferrals(false);
060     * LDAPConnection connection = new LDAPConnection(connectionOptions,
061     *      serverAddress, serverPort, bindDN, bindPassword);
062     *
063     * // Try to delete an entry that will result in a referral.  Without the
064     * // ManageDsaIT request control, we should get an exception.
065     * DeleteRequest deleteRequest =
066     *      new DeleteRequest("ou=referral entry,dc=example,dc=com");
067     * LDAPResult deleteResult;
068     * try
069     * {
070     *   deleteResult = connection.delete(deleteRequest);
071     * }
072     * catch (LDAPException le)
073     * {
074     *   // This exception is expected because we should get a referral, and
075     *   // the connection is configured to not follow referrals.
076     *   deleteResult = le.toLDAPResult();
077     *   ResultCode resultCode = le.getResultCode();
078     *   String errorMessageFromServer = le.getDiagnosticMessage();
079     *   String[] referralURLs = le.getReferralURLs();
080     * }
081     * LDAPTestUtils.assertResultCodeEquals(deleteResult, ResultCode.REFERRAL);
082     * LDAPTestUtils.assertHasReferral(deleteResult);
083     *
084     * // Update the delete request to include the ManageDsaIT request control,
085     * // which will cause the server to try to delete the referral entry instead
086     * // of returning a referral response.  We'll assume that the delete is
087     * // successful.
088     * deleteRequest.addControl(new ManageDsaITRequestControl());
089     * try
090     * {
091     *   deleteResult = connection.delete(deleteRequest);
092     * }
093     * catch (LDAPException le)
094     * {
095     *   // The delete shouldn't trigger a referral, but it's possible that the
096     *   // operation failed for some other reason (e.g., entry doesn't exist, the
097     *   // user doesn't have permission to delete it, etc.).
098     *   deleteResult = le.toLDAPResult();
099     * }
100     * LDAPTestUtils.assertResultCodeEquals(deleteResult, ResultCode.SUCCESS);
101     * LDAPTestUtils.assertMissingReferral(deleteResult);
102     *
103     * connection.close();
104     * </PRE>
105     */
106    @NotMutable()
107    @ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
108    public final class ManageDsaITRequestControl
109           extends Control
110    {
111      /**
112       * The OID (2.16.840.1.113730.3.4.2) for the ManageDsaIT request control.
113       */
114      public static final String MANAGE_DSA_IT_REQUEST_OID =
115           "2.16.840.1.113730.3.4.2";
116    
117    
118    
119      /**
120       * The serial version UID for this serializable class.
121       */
122      private static final long serialVersionUID = -4540943247829123783L;
123    
124    
125    
126      /**
127       * Creates a new ManageDsaIT request control.  The control will not be marked
128       * critical.
129       */
130      public ManageDsaITRequestControl()
131      {
132        super(MANAGE_DSA_IT_REQUEST_OID, false, null);
133      }
134    
135    
136    
137      /**
138       * Creates a new ManageDsaIT request control.
139       *
140       * @param  isCritical  Indicates whether the control should be marked
141       *                     critical.
142       */
143      public ManageDsaITRequestControl(final boolean isCritical)
144      {
145        super(MANAGE_DSA_IT_REQUEST_OID, isCritical, null);
146      }
147    
148    
149    
150      /**
151       * Creates a new ManageDsaIT request control which is decoded from the
152       * provided generic control.
153       *
154       * @param  control  The generic control to be decoded as a ManageDsaIT request
155       *                  control.
156       *
157       * @throws  LDAPException  If the provided control cannot be decoded as a
158       *                         ManageDsaIT request control.
159       */
160      public ManageDsaITRequestControl(final Control control)
161             throws LDAPException
162      {
163        super(control);
164    
165        if (control.hasValue())
166        {
167          throw new LDAPException(ResultCode.DECODING_ERROR,
168                                  ERR_MANAGE_DSA_IT_HAS_VALUE.get());
169        }
170      }
171    
172    
173    
174      /**
175       * {@inheritDoc}
176       */
177      @Override()
178      public String getControlName()
179      {
180        return INFO_CONTROL_NAME_MANAGE_DSAIT_REQUEST.get();
181      }
182    
183    
184    
185      /**
186       * {@inheritDoc}
187       */
188      @Override()
189      public void toString(final StringBuilder buffer)
190      {
191        buffer.append("ManageDsaITRequestControl(isCritical=");
192        buffer.append(isCritical());
193        buffer.append(')');
194      }
195    }