001/* 002 * Copyright 2009-2022 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright 2009-2022 Ping Identity Corporation 007 * 008 * Licensed under the Apache License, Version 2.0 (the "License"); 009 * you may not use this file except in compliance with the License. 010 * You may obtain a copy of the License at 011 * 012 * http://www.apache.org/licenses/LICENSE-2.0 013 * 014 * Unless required by applicable law or agreed to in writing, software 015 * distributed under the License is distributed on an "AS IS" BASIS, 016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 017 * See the License for the specific language governing permissions and 018 * limitations under the License. 019 */ 020/* 021 * Copyright (C) 2009-2022 Ping Identity Corporation 022 * 023 * This program is free software; you can redistribute it and/or modify 024 * it under the terms of the GNU General Public License (GPLv2 only) 025 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only) 026 * as published by the Free Software Foundation. 027 * 028 * This program is distributed in the hope that it will be useful, 029 * but WITHOUT ANY WARRANTY; without even the implied warranty of 030 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 031 * GNU General Public License for more details. 032 * 033 * You should have received a copy of the GNU General Public License 034 * along with this program; if not, see <http://www.gnu.org/licenses>. 035 */ 036package com.unboundid.ldap.sdk.unboundidds.controls; 037 038 039 040import com.unboundid.asn1.ASN1OctetString; 041import com.unboundid.ldap.sdk.Control; 042import com.unboundid.util.NotMutable; 043import com.unboundid.util.NotNull; 044import com.unboundid.util.Nullable; 045import com.unboundid.util.ThreadSafety; 046import com.unboundid.util.ThreadSafetyLevel; 047 048import static com.unboundid.ldap.sdk.unboundidds.controls.ControlMessages.*; 049 050 051 052/** 053 * This class provides an implementation of a Directory Server control that may 054 * be used to indicate that the associated operation is used for performing some 055 * administrative operation within the server rather than one that was requested 056 * by a "normal" client. The server can use this indication to treat the 057 * operation differently (e.g., exclude it from the processing time histogram, 058 * or to include additional information about the purpose of the operation in 059 * the access log). 060 * <BR> 061 * <BLOCKQUOTE> 062 * <B>NOTE:</B> This class, and other classes within the 063 * {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only 064 * supported for use against Ping Identity, UnboundID, and 065 * Nokia/Alcatel-Lucent 8661 server products. These classes provide support 066 * for proprietary functionality or for external specifications that are not 067 * considered stable or mature enough to be guaranteed to work in an 068 * interoperable way with other types of LDAP servers. 069 * </BLOCKQUOTE> 070 * <BR> 071 * This request control has an OID of 1.3.6.1.4.1.30221.2.5.11 and a criticality 072 * of false. It may optionally have a value that is simply the bytes that 073 * comprise the message to include in the control. 074 */ 075@NotMutable() 076@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 077public final class AdministrativeOperationRequestControl 078 extends Control 079{ 080 /** 081 * The OID (1.3.6.1.4.1.30221.2.5.11) for the administrative operation request 082 * control. 083 */ 084 @NotNull public static final String ADMINISTRATIVE_OPERATION_REQUEST_OID = 085 "1.3.6.1.4.1.30221.2.5.11"; 086 087 088 089 /** 090 * The serial version UID for this serializable class. 091 */ 092 private static final long serialVersionUID = 4958642483402677725L; 093 094 095 096 // The informational message to include in the control, if defined. 097 @Nullable private final String message; 098 099 100 101 /** 102 * Creates a new administrative operation request control with no message. 103 */ 104 public AdministrativeOperationRequestControl() 105 { 106 this((String) null); 107 } 108 109 110 111 /** 112 * Creates a new administrative operation request control with the provided 113 * informational message. 114 * 115 * @param message A message with additional information about the purpose of 116 * the associated operation. It may be {@code null} if no 117 * additional message should be provided. 118 */ 119 public AdministrativeOperationRequestControl(@Nullable final String message) 120 { 121 super(ADMINISTRATIVE_OPERATION_REQUEST_OID, false, encodeValue(message)); 122 123 this.message = message; 124 } 125 126 127 128 /** 129 * Creates a new administrative operation request control decoded from the 130 * provided generic control. 131 * 132 * @param control The generic control to be decoded as an administrative 133 * operation request control. 134 */ 135 public AdministrativeOperationRequestControl(@NotNull final Control control) 136 { 137 super(control); 138 139 if (control.hasValue()) 140 { 141 message = control.getValue().stringValue(); 142 } 143 else 144 { 145 message = null; 146 } 147 } 148 149 150 151 /** 152 * Generates an appropriately-encoded value for this control with the provided 153 * message. 154 * 155 * @param message A message with additional information about the purpose of 156 * the associated operation. It may be {@code null} if no 157 * additional message should be provided. 158 * 159 * @return An appropriately-encoded value for this control, or {@code null} 160 * if no value is needed. 161 */ 162 @Nullable() 163 private static ASN1OctetString encodeValue(@Nullable final String message) 164 { 165 if (message == null) 166 { 167 return null; 168 } 169 else 170 { 171 return new ASN1OctetString(message); 172 } 173 } 174 175 176 177 /** 178 * Retrieves the informational message for this control, if defined. 179 * 180 * @return The informational message for this control, or {@code null} if 181 * none was provided. 182 */ 183 @Nullable() 184 public String getMessage() 185 { 186 return message; 187 } 188 189 190 191 /** 192 * {@inheritDoc} 193 */ 194 @Override() 195 @NotNull() 196 public String getControlName() 197 { 198 return INFO_CONTROL_NAME_ADMINISTRATIVE_OPERATION_REQUEST.get(); 199 } 200 201 202 203 /** 204 * {@inheritDoc} 205 */ 206 @Override() 207 public void toString(@NotNull final StringBuilder buffer) 208 { 209 buffer.append("AdministrativeOperationRequestControl("); 210 211 if (message != null) 212 { 213 buffer.append("message='"); 214 buffer.append(message); 215 buffer.append('\''); 216 } 217 218 buffer.append(')'); 219 } 220}