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 }