001/* 002 * Copyright 2008-2022 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright 2008-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) 2008-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.ldap.sdk.DecodeableControl; 043import com.unboundid.ldap.sdk.LDAPException; 044import com.unboundid.ldap.sdk.LDAPResult; 045import com.unboundid.ldap.sdk.ResultCode; 046import com.unboundid.ldap.sdk.SearchResultEntry; 047import com.unboundid.ldap.sdk.SearchResultReference; 048import com.unboundid.util.NotMutable; 049import com.unboundid.util.NotNull; 050import com.unboundid.util.Nullable; 051import com.unboundid.util.ThreadSafety; 052import com.unboundid.util.ThreadSafetyLevel; 053import com.unboundid.util.Validator; 054 055import static com.unboundid.ldap.sdk.unboundidds.controls.ControlMessages.*; 056 057 058 059/** 060 * This class provides a response control that may be used to provide the server 061 * ID of the Directory Server instance that processed the associated request. 062 * For search operations, each entry and reference returned will include the 063 * server ID of the server that provided that entry or reference. For all other 064 * types of operations, it will be in the {@code LDAPResult} (or appropriate 065 * subclass) returned for that operation. 066 * <BR> 067 * <BLOCKQUOTE> 068 * <B>NOTE:</B> This class, and other classes within the 069 * {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only 070 * supported for use against Ping Identity, UnboundID, and 071 * Nokia/Alcatel-Lucent 8661 server products. These classes provide support 072 * for proprietary functionality or for external specifications that are not 073 * considered stable or mature enough to be guaranteed to work in an 074 * interoperable way with other types of LDAP servers. 075 * </BLOCKQUOTE> 076 * <BR> 077 * This control has an OID of 1.3.6.1.4.1.30221.2.5.15 and a criticality of 078 * false. This control must have a value, which will simply be the string 079 * representation of the server ID of the associated server. 080 */ 081@NotMutable() 082@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 083public final class GetServerIDResponseControl 084 extends Control 085 implements DecodeableControl 086{ 087 /** 088 * The OID (1.3.6.1.4.1.30221.2.5.15) for the get server ID response control. 089 */ 090 @NotNull public static final String GET_SERVER_ID_RESPONSE_OID = 091 "1.3.6.1.4.1.30221.2.5.15"; 092 093 094 /** 095 * The serial version UID for this serializable class. 096 */ 097 private static final long serialVersionUID = 5271084342514677677L; 098 099 100 101 // The server ID of the server that processed the associated request. 102 @NotNull private final String serverID; 103 104 105 106 /** 107 * Creates a new empty control instance that is intended to be used only for 108 * decoding controls via the {@code DecodeableControl} interface. 109 */ 110 GetServerIDResponseControl() 111 { 112 serverID = null; 113 } 114 115 116 117 /** 118 * Creates a new get server ID response control with the provided server ID. 119 * 120 * @param serverID The server ID of the server that processed the associated 121 * request. It must not be {@code null}. 122 */ 123 public GetServerIDResponseControl(@NotNull final String serverID) 124 { 125 super(GET_SERVER_ID_RESPONSE_OID, false, new ASN1OctetString(serverID)); 126 127 Validator.ensureNotNull(serverID); 128 129 this.serverID = serverID; 130 } 131 132 133 134 /** 135 * Creates a new get server ID response control decoded from the given generic 136 * control contents. 137 * 138 * @param oid The OID for the control. 139 * @param isCritical Indicates whether this control should be marked 140 * critical. 141 * @param value The value for the control. It may be {@code null} if 142 * the control to decode does not have a value. 143 * 144 * @throws LDAPException If a problem occurs while attempting to decode the 145 * generic control as a get server ID response 146 * control. 147 */ 148 public GetServerIDResponseControl(@NotNull final String oid, 149 final boolean isCritical, 150 @Nullable final ASN1OctetString value) 151 throws LDAPException 152 { 153 super(oid, isCritical, value); 154 155 if (value == null) 156 { 157 throw new LDAPException(ResultCode.DECODING_ERROR, 158 ERR_GET_SERVER_ID_RESPONSE_MISSING_VALUE.get()); 159 } 160 161 serverID = value.stringValue(); 162 } 163 164 165 166 /** 167 * {@inheritDoc} 168 */ 169 @Override() 170 @NotNull() 171 public GetServerIDResponseControl decodeControl(@NotNull final String oid, 172 final boolean isCritical, 173 @Nullable final ASN1OctetString value) 174 throws LDAPException 175 { 176 return new GetServerIDResponseControl(oid, isCritical, value); 177 } 178 179 180 181 /** 182 * Extracts a get server ID response control from the provided result. 183 * 184 * @param result The result from which to retrieve the get server ID 185 * response control. 186 * 187 * @return The get server ID response control contained in the provided 188 * result, or {@code null} if the result did not contain a get server 189 * ID response control. 190 * 191 * @throws LDAPException If a problem is encountered while attempting to 192 * decode the get server ID response control contained 193 * in the provided result. 194 */ 195 @Nullable() 196 public static GetServerIDResponseControl get(@NotNull final LDAPResult result) 197 throws LDAPException 198 { 199 final Control c = result.getResponseControl(GET_SERVER_ID_RESPONSE_OID); 200 if (c == null) 201 { 202 return null; 203 } 204 205 if (c instanceof GetServerIDResponseControl) 206 { 207 return (GetServerIDResponseControl) c; 208 } 209 else 210 { 211 return new GetServerIDResponseControl(c.getOID(), c.isCritical(), 212 c.getValue()); 213 } 214 } 215 216 217 218 /** 219 * Extracts a get server ID response control from the provided search result 220 * entry. 221 * 222 * @param entry The search result entry from which to retrieve the get 223 * server ID response control. 224 * 225 * @return The get server ID response control contained in the provided 226 * search result entry, or {@code null} if the entry did not contain 227 * a get server ID response control. 228 * 229 * @throws LDAPException If a problem is encountered while attempting to 230 * decode the get server ID response control contained 231 * in the provided entry. 232 */ 233 @Nullable() 234 public static GetServerIDResponseControl get( 235 @NotNull final SearchResultEntry entry) 236 throws LDAPException 237 { 238 final Control c = entry.getControl(GET_SERVER_ID_RESPONSE_OID); 239 if (c == null) 240 { 241 return null; 242 } 243 244 if (c instanceof GetServerIDResponseControl) 245 { 246 return (GetServerIDResponseControl) c; 247 } 248 else 249 { 250 return new GetServerIDResponseControl(c.getOID(), c.isCritical(), 251 c.getValue()); 252 } 253 } 254 255 256 257 /** 258 * Extracts a get server ID response control from the provided search result 259 * reference. 260 * 261 * @param ref The search result reference from which to retrieve the get 262 * server ID response control. 263 * 264 * @return The get server ID response control contained in the provided 265 * search result reference, or {@code null} if the reference did not 266 * contain a get server ID response control. 267 * 268 * @throws LDAPException If a problem is encountered while attempting to 269 * decode the get server ID response control contained 270 * in the provided reference. 271 */ 272 @Nullable() 273 public static GetServerIDResponseControl get( 274 @NotNull final SearchResultReference ref) 275 throws LDAPException 276 { 277 final Control c = ref.getControl(GET_SERVER_ID_RESPONSE_OID); 278 if (c == null) 279 { 280 return null; 281 } 282 283 if (c instanceof GetServerIDResponseControl) 284 { 285 return (GetServerIDResponseControl) c; 286 } 287 else 288 { 289 return new GetServerIDResponseControl(c.getOID(), c.isCritical(), 290 c.getValue()); 291 } 292 } 293 294 295 296 /** 297 * Retrieves the server ID of the server that actually processed the 298 * associated request. 299 * 300 * @return The server ID of the server that actually processed the associated 301 * request. 302 */ 303 @NotNull() 304 public String getServerID() 305 { 306 return serverID; 307 } 308 309 310 311 /** 312 * {@inheritDoc} 313 */ 314 @Override() 315 @NotNull() 316 public String getControlName() 317 { 318 return INFO_CONTROL_NAME_GET_SERVER_ID_RESPONSE.get(); 319 } 320 321 322 323 /** 324 * {@inheritDoc} 325 */ 326 @Override() 327 public void toString(@NotNull final StringBuilder buffer) 328 { 329 buffer.append("GetServerIDResponseControl(serverID='"); 330 buffer.append(serverID); 331 buffer.append("')"); 332 } 333}