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