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    }