001/* 002 * Copyright 2009-2019 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright (C) 2015-2019 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}