001/*
002 * Copyright 2009-2014 UnboundID Corp.
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2009-2014 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 */
021package com.unboundid.ldap.sdk.controls;
022
023
024
025import com.unboundid.ldap.sdk.Control;
026import com.unboundid.ldap.sdk.LDAPException;
027import com.unboundid.ldap.sdk.ResultCode;
028import com.unboundid.util.NotMutable;
029import com.unboundid.util.ThreadSafety;
030import com.unboundid.util.ThreadSafetyLevel;
031
032import static com.unboundid.ldap.sdk.controls.ControlMessages.*;
033
034
035
036/**
037 * This class provides an implementation of the permissive modify request
038 * control, which is supported by a number of servers and may be included in a
039 * modify request to indicate that the server should not reject a modify
040 * request which attempts to add an attribute value which already exists or
041 * remove an attribute value which does not exist.  Normally, such modification
042 * attempts would be rejected.
043 * <BR><BR>
044 * The OID for this control is "1.2.840.113556.1.4.1413".  It does not have a
045 * value.
046 * <BR><BR>
047 * <H2>Example</H2>
048 * The following example demonstrates the use of the permissive modify request
049 * control to process a modification that attempts to add an attribute value
050 * to an entry that already contains that value.
051 * <PRE>
052 * // Ensure that we start with a known description value in the test entry
053 * // by using a replace to overwrite any existing value(s).
054 * ModifyRequest replaceRequest = new ModifyRequest(
055 *      "uid=test.user,ou=People,dc=example,dc=com",
056 *      new Modification(ModificationType.REPLACE, "description", "value"));
057 * LDAPResult replaceResult = connection.modify(replaceRequest);
058 *
059 * // Create a modify request that will attempt to add the value that already
060 * // exists.  If we attempt to do this without the permissive modify control,
061 * // the attempt should fail.
062 * ModifyRequest addExistingValueRequest = new ModifyRequest(
063 *      "uid=test.user,ou=People,dc=example,dc=com",
064 *      new Modification(ModificationType.ADD, "description", "value"));
065 * LDAPResult addExistingValueResultWithoutControl;
066 * try
067 * {
068 *   addExistingValueResultWithoutControl =
069 *        connection.modify(addExistingValueRequest);
070 *   // We shouldn't get here because the attempt to add the existing value
071 *   // should fail.
072 * }
073 * catch (LDAPException le)
074 * {
075 *   // We expected this failure because the value we're trying to add already
076 *   // exists in the entry.
077 *   addExistingValueResultWithoutControl = le.toLDAPResult();
078 *   ResultCode resultCode = le.getResultCode();
079 *   String errorMessageFromServer = le.getDiagnosticMessage();
080 * }
081 *
082 * // Update the modify request to include the permissive modify request
083 * // control, and re-send the request.  The operation should now succeed.
084 * addExistingValueRequest.addControl(new PermissiveModifyRequestControl());
085 * LDAPResult addExistingValueResultWithControl;
086 * try
087 * {
088 *   addExistingValueResultWithControl =
089 *        connection.modify(addExistingValueRequest);
090 *   // If we've gotten here, then the modification was successful.
091 * }
092 * catch (LDAPException le)
093 * {
094 *   // If we've gotten here, then the modification failed for some reason.
095 *   addExistingValueResultWithControl = le.toLDAPResult();
096 *   ResultCode resultCode = le.getResultCode();
097 *   String errorMessageFromServer = le.getDiagnosticMessage();
098 * }
099 * </PRE>
100 */
101@NotMutable()
102@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
103public final class PermissiveModifyRequestControl
104       extends Control
105{
106  /**
107   * The OID (1.2.840.113556.1.4.1413) for the permissive modify request
108   * control.
109   */
110  public static final String PERMISSIVE_MODIFY_REQUEST_OID =
111       "1.2.840.113556.1.4.1413";
112
113
114
115  /**
116   * The serial version UID for this serializable class.
117   */
118  private static final long serialVersionUID = -2599039772002106760L;
119
120
121
122  /**
123   * Creates a new permissive modify request control.  The control will not be
124   * marked critical.
125   */
126  public PermissiveModifyRequestControl()
127  {
128    super(PERMISSIVE_MODIFY_REQUEST_OID, false, null);
129  }
130
131
132
133  /**
134   * Creates a new permissive modify request control.
135   *
136   * @param  isCritical  Indicates whether the control should be marked
137   *                     critical.
138   */
139  public PermissiveModifyRequestControl(final boolean isCritical)
140  {
141    super(PERMISSIVE_MODIFY_REQUEST_OID, isCritical, null);
142  }
143
144
145
146  /**
147   * Creates a new permissive modify request control which is decoded from the
148   * provided generic control.
149   *
150   * @param  control  The generic control to be decoded as a permissive modify
151   *                  request control.
152   *
153   * @throws  LDAPException  If the provided control cannot be decoded as a
154   *                         permissive modify request control.
155   */
156  public PermissiveModifyRequestControl(final Control control)
157         throws LDAPException
158  {
159    super(control);
160
161    if (control.hasValue())
162    {
163      throw new LDAPException(ResultCode.DECODING_ERROR,
164                              ERR_PERMISSIVE_MODIFY_HAS_VALUE.get());
165    }
166  }
167
168
169
170  /**
171   * {@inheritDoc}
172   */
173  @Override()
174  public String getControlName()
175  {
176    return INFO_CONTROL_NAME_PERMISSIVE_MODIFY_REQUEST.get();
177  }
178
179
180
181  /**
182   * {@inheritDoc}
183   */
184  @Override()
185  public void toString(final StringBuilder buffer)
186  {
187    buffer.append("PermissiveModifyRequestControl(isCritical=");
188    buffer.append(isCritical());
189    buffer.append(')');
190  }
191}