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