001/*
002 * Copyright 2009-2018 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2015-2018 Ping Identity Corporation
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.unboundidds.controls;
022
023
024
025import com.unboundid.asn1.ASN1OctetString;
026import com.unboundid.ldap.sdk.Control;
027import com.unboundid.util.NotMutable;
028import com.unboundid.util.ThreadSafety;
029import com.unboundid.util.ThreadSafetyLevel;
030
031import static com.unboundid.ldap.sdk.unboundidds.controls.ControlMessages.*;
032
033
034
035/**
036 * This class provides an implementation of a Directory Server control that may
037 * be used to indicate that the associated operation is used for performing some
038 * administrative operation within the server rather than one that was requested
039 * by a "normal" client.  The server can use this indication to treat the
040 * operation differently (e.g., exclude it from the processing time histogram,
041 * or to include additional information about the purpose of the operation in
042 * the access log).
043 * <BR>
044 * <BLOCKQUOTE>
045 *   <B>NOTE:</B>  This class, and other classes within the
046 *   {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only
047 *   supported for use against Ping Identity, UnboundID, and
048 *   Nokia/Alcatel-Lucent 8661 server products.  These classes provide support
049 *   for proprietary functionality or for external specifications that are not
050 *   considered stable or mature enough to be guaranteed to work in an
051 *   interoperable way with other types of LDAP servers.
052 * </BLOCKQUOTE>
053 * <BR>
054 * This request control has an OID of 1.3.6.1.4.1.30221.2.5.11 and a criticality
055 * of false.  It may optionally have a value that is simply the bytes that
056 * comprise the message to include in the control.
057 */
058@NotMutable()
059@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
060public final class AdministrativeOperationRequestControl
061       extends Control
062{
063  /**
064   * The OID (1.3.6.1.4.1.30221.2.5.11) for the administrative operation request
065   * control.
066   */
067  public static final String ADMINISTRATIVE_OPERATION_REQUEST_OID =
068       "1.3.6.1.4.1.30221.2.5.11";
069
070
071
072  /**
073   * The serial version UID for this serializable class.
074   */
075  private static final long serialVersionUID = 4958642483402677725L;
076
077
078
079  // The informational message to include in the control, if defined.
080  private final String message;
081
082
083
084  /**
085   * Creates a new administrative operation request control with no message.
086   */
087  public AdministrativeOperationRequestControl()
088  {
089    this((String) null);
090  }
091
092
093
094  /**
095   * Creates a new administrative operation request control with the provided
096   * informational message.
097   *
098   * @param  message  A message with additional information about the purpose of
099   *                  the associated operation.  It may be {@code null} if no
100   *                  additional message should be provided.
101   */
102  public AdministrativeOperationRequestControl(final String message)
103  {
104    super(ADMINISTRATIVE_OPERATION_REQUEST_OID, false, encodeValue(message));
105
106    this.message = message;
107  }
108
109
110
111  /**
112   * Creates a new administrative operation request control decoded from the
113   * provided generic control.
114   *
115   * @param  control  The generic control to be decoded as an administrative
116   *                  operation request control.
117   */
118  public AdministrativeOperationRequestControl(final Control control)
119  {
120    super(control);
121
122    if (control.hasValue())
123    {
124      message = control.getValue().stringValue();
125    }
126    else
127    {
128      message = null;
129    }
130  }
131
132
133
134  /**
135   * Generates an appropriately-encoded value for this control with the provided
136   * message.
137   *
138   * @param  message  A message with additional information about the purpose of
139   *                  the associated operation.  It may be {@code null} if no
140   *                  additional message should be provided.
141   *
142   * @return  An appropriately-encoded value for this control, or {@code null}
143   *          if no value is needed.
144   */
145  private static ASN1OctetString encodeValue(final String message)
146  {
147    if (message == null)
148    {
149      return null;
150    }
151    else
152    {
153      return new ASN1OctetString(message);
154    }
155  }
156
157
158
159  /**
160   * Retrieves the informational message for this control, if defined.
161   *
162   * @return  The informational message for this control, or {@code null} if
163   *          none was provided.
164   */
165  public String getMessage()
166  {
167    return message;
168  }
169
170
171
172  /**
173   * {@inheritDoc}
174   */
175  @Override()
176  public String getControlName()
177  {
178    return INFO_CONTROL_NAME_ADMINISTRATIVE_OPERATION_REQUEST.get();
179  }
180
181
182
183  /**
184   * {@inheritDoc}
185   */
186  @Override()
187  public void toString(final StringBuilder buffer)
188  {
189    buffer.append("AdministrativeOperationRequestControl(");
190
191    if (message != null)
192    {
193      buffer.append("message='");
194      buffer.append(message);
195      buffer.append('\'');
196    }
197
198    buffer.append(')');
199  }
200}