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