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