001    /*
002     * Copyright 2007-2014 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2008-2014 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;
022    
023    
024    
025    import java.util.ArrayList;
026    import java.util.Arrays;
027    import java.util.Collections;
028    import java.util.List;
029    import java.util.Timer;
030    import java.util.concurrent.LinkedBlockingQueue;
031    import java.util.concurrent.TimeUnit;
032    
033    import com.unboundid.asn1.ASN1Boolean;
034    import com.unboundid.asn1.ASN1Buffer;
035    import com.unboundid.asn1.ASN1BufferSequence;
036    import com.unboundid.asn1.ASN1Element;
037    import com.unboundid.asn1.ASN1Enumerated;
038    import com.unboundid.asn1.ASN1Integer;
039    import com.unboundid.asn1.ASN1OctetString;
040    import com.unboundid.asn1.ASN1Sequence;
041    import com.unboundid.ldap.protocol.LDAPMessage;
042    import com.unboundid.ldap.protocol.LDAPResponse;
043    import com.unboundid.ldap.protocol.ProtocolOp;
044    import com.unboundid.util.InternalUseOnly;
045    
046    import static com.unboundid.ldap.sdk.LDAPMessages.*;
047    import static com.unboundid.util.Debug.*;
048    import static com.unboundid.util.StaticUtils.*;
049    import static com.unboundid.util.Validator.*;
050    
051    
052    
053    /**
054     * This class implements the processing necessary to perform an LDAPv3 search
055     * operation, which can be used to retrieve entries that match a given set of
056     * criteria.  A search request may include the following elements:
057     * <UL>
058     *   <LI>Base DN -- Specifies the base DN for the search.  Only entries at or
059     *       below this location in the server (based on the scope) will be
060     *       considered potential matches.</LI>
061     *   <LI>Scope -- Specifies the range of entries relative to the base DN that
062     *       may be considered potential matches.</LI>
063     *   <LI>Dereference Policy -- Specifies the behavior that the server should
064     *       exhibit if any alias entries are encountered while processing the
065     *       search.  If no dereference policy is provided, then a default of
066     *       {@code DereferencePolicy.NEVER} will be used.</LI>
067     *   <LI>Size Limit -- Specifies the maximum number of entries that should be
068     *       returned from the search.  A value of zero indicates that there should
069     *       not be any limit enforced.  Note that the directory server may also
070     *       be configured with a server-side size limit which can also limit the
071     *       number of entries that may be returned to the client and in that case
072     *       the smaller of the client-side and server-side limits will be
073     *       used.  If no size limit is provided, then a default of zero (unlimited)
074     *       will be used.</LI>
075     *   <LI>Time Limit -- Specifies the maximum length of time in seconds that the
076     *       server should spend processing the search.  A value of zero indicates
077     *       that there should not be any limit enforced.  Note that the directory
078     *       server may also be configured with a server-side time limit which can
079     *       also limit the processing time, and in that case the smaller of the
080     *       client-side and server-side limits will be used.  If no time limit is
081     *       provided, then a default of zero (unlimited) will be used.</LI>
082     *   <LI>Types Only -- Indicates whether matching entries should include only
083     *       attribute names, or both attribute names and values.  If no value is
084     *       provided, then a default of {@code false} will be used.</LI>
085     *   <LI>Filter -- Specifies the criteria for determining which entries should
086     *       be returned.  See the {@code Filter} class for the types of filters
087     *       that may be used.
088     *       <BR><BR>
089     *       Note that filters can be specified using either their string
090     *       representations or as {@code Filter} objects.  As noted in the
091     *       documentation for the {@code Filter} class, using the string
092     *       representation may be somewhat dangerous if the data is not properly
093     *       sanitized because special characters contained in the filter may cause
094     *       it to be invalid or worse expose a vulnerability that could cause the
095     *       filter to request more information than was intended.  As a result, if
096     *       the filter may include special characters or user-provided strings,
097     *       then it is recommended that you use {@code Filter} objects created from
098     *       their individual components rather than their string representations.
099     * </LI>
100     *   <LI>Attributes -- Specifies the set of attributes that should be included
101     *       in matching entries.  If no attributes are provided, then the server
102     *       will default to returning all user attributes.  If a specified set of
103     *       attributes is given, then only those attributes will be included.
104     *       Values that may be included to indicate a special meaning include:
105     *       <UL>
106     *         <LI>{@code NO_ATTRIBUTES} -- Indicates that no attributes should be
107     *             returned.  That is, only the DNs of matching entries will be
108     *             returned.</LI>
109     *         <LI>{@code ALL_USER_ATTRIBUTES} -- Indicates that all user attributes
110     *             should be included in matching entries.  This is the default if
111     *             no attributes are provided, but this special value may be
112     *             included if a specific set of operational attributes should be
113     *             included along with all user attributes.</LI>
114     *         <LI>{@code ALL_OPERATIONAL_ATTRIBUTES} -- Indicates that all
115     *             operational attributes should be included in matching
116     *             entries.</LI>
117     *       </UL>
118     *       These special values may be used alone or in conjunction with each
119     *       other and/or any specific attribute names or OIDs.</LI>
120     *   <LI>An optional set of controls to include in the request to send to the
121     *       server.</LI>
122     *   <LI>An optional {@code SearchResultListener} which may be used to process
123     *       search result entries and search result references returned by the
124     *       server in the course of processing the request.  If this is
125     *       {@code null}, then the entries and references will be collected and
126     *       returned in the {@code SearchResult} object that is returned.</LI>
127     * </UL>
128     * When processing a search operation, there are three ways that the returned
129     * entries and references may be accessed:
130     * <UL>
131     *   <LI>If the {@code LDAPInterface#search(SearchRequest)} method is used and
132     *       the provided search request does not include a
133     *       {@code SearchResultListener} object, then the entries and references
134     *       will be collected internally and made available in the
135     *       {@code SearchResult} object that is returned.</LI>
136     *   <LI>If the {@code LDAPInterface#search(SearchRequest)} method is used and
137     *       the provided search request does include a {@code SearchResultListener}
138     *       object, then that listener will be used to provide access to the
139     *       entries and references, and they will not be present in the
140     *       {@code SearchResult} object (although the number of entries and
141     *       references returned will still be available).</LI>
142     *   <LI>The {@code LDAPEntrySource} object may be used to access the entries
143     *        and references returned from the search.  It uses an
144     *        {@code Iterator}-like API to provide access to the entries that are
145     *        returned, and any references returned will be included in the
146     *        {@code EntrySourceException} thrown on the appropriate call to
147     *        {@code LDAPEntrySource#nextEntry()}.</LI>
148     * </UL>
149     * <BR><BR>
150     * {@code SearchRequest} objects are mutable and therefore can be altered and
151     * re-used for multiple requests.  Note, however, that {@code SearchRequest}
152     * objects are not threadsafe and therefore a single {@code SearchRequest}
153     * object instance should not be used to process multiple requests at the same
154     * time.
155     * <BR><BR>
156     * <H2>Example</H2>
157     * The following example demonstrates a simple search operation in which the
158     * client performs a search to find all users in the "Sales" department and then
159     * retrieves the name and e-mail address for each matching user:
160     * <PRE>
161     * // Construct a filter that can be used to find everyone in the Sales
162     * // department, and then create a search request to find all such users
163     * // in the directory.
164     * Filter filter = Filter.createEqualityFilter("ou", "Sales");
165     * SearchRequest searchRequest =
166     *      new SearchRequest("dc=example,dc=com", SearchScope.SUB, filter,
167     *           "cn", "mail");
168     * SearchResult searchResult;
169     *
170     * try
171     * {
172     *   searchResult = connection.search(searchRequest);
173     *
174     *   for (SearchResultEntry entry : searchResult.getSearchEntries())
175     *   {
176     *     String name = entry.getAttributeValue("cn");
177     *     String mail = entry.getAttributeValue("mail");
178     *   }
179     * }
180     * catch (LDAPSearchException lse)
181     * {
182     *   // The search failed for some reason.
183     *   searchResult = lse.getSearchResult();
184     *   ResultCode resultCode = lse.getResultCode();
185     *   String errorMessageFromServer = lse.getDiagnosticMessage();
186     * }
187     * </PRE>
188     */
189    public final class SearchRequest
190           extends UpdatableLDAPRequest
191           implements ReadOnlySearchRequest, ResponseAcceptor, ProtocolOp
192    {
193      /**
194       * The special value "*" that can be included in the set of requested
195       * attributes to indicate that all user attributes should be returned.
196       */
197      public static final String ALL_USER_ATTRIBUTES = "*";
198    
199    
200    
201      /**
202       * The special value "+" that can be included in the set of requested
203       * attributes to indicate that all operational attributes should be returned.
204       */
205      public static final String ALL_OPERATIONAL_ATTRIBUTES = "+";
206    
207    
208    
209      /**
210       * The special value "1.1" that can be included in the set of requested
211       * attributes to indicate that no attributes should be returned, with the
212       * exception of any other attributes explicitly named in the set of requested
213       * attributes.
214       */
215      public static final String NO_ATTRIBUTES = "1.1";
216    
217    
218    
219      /**
220       * The default set of requested attributes that will be used, which will
221       * return all user attributes but no operational attributes.
222       */
223      public static final String[] REQUEST_ATTRS_DEFAULT = NO_STRINGS;
224    
225    
226    
227      /**
228       * The serial version UID for this serializable class.
229       */
230      private static final long serialVersionUID = 1500219434086474893L;
231    
232    
233    
234      // The set of requested attributes.
235      private String[] attributes;
236    
237      // Indicates whether to retrieve attribute types only or both types and
238      // values.
239      private boolean typesOnly;
240    
241      // The behavior to use when aliases are encountered.
242      private DereferencePolicy derefPolicy;
243    
244      // The message ID from the last LDAP message sent from this request.
245      private int messageID = -1;
246    
247      // The size limit for this search request.
248      private int sizeLimit;
249    
250      // The time limit for this search request.
251      private int timeLimit;
252    
253      // The parsed filter for this search request.
254      private Filter filter;
255    
256      // The queue that will be used to receive response messages from the server.
257      private final LinkedBlockingQueue<LDAPResponse> responseQueue =
258           new LinkedBlockingQueue<LDAPResponse>(50);
259    
260      // The search result listener that should be used to return results
261      // interactively to the requester.
262      private final SearchResultListener searchResultListener;
263    
264      // The scope for this search request.
265      private SearchScope scope;
266    
267      // The base DN for this search request.
268      private String baseDN;
269    
270    
271    
272      /**
273       * Creates a new search request with the provided information.  Search result
274       * entries and references will be collected internally and included in the
275       * {@code SearchResult} object returned when search processing is completed.
276       *
277       * @param  baseDN      The base DN for the search request.  It must not be
278       *                     {@code null}.
279       * @param  scope       The scope that specifies the range of entries that
280       *                     should be examined for the search.
281       * @param  filter      The string representation of the filter to use to
282       *                     identify matching entries.  It must not be
283       *                     {@code null}.
284       * @param  attributes  The set of attributes that should be returned in
285       *                     matching entries.  It may be {@code null} or empty if
286       *                     the default attribute set (all user attributes) is to
287       *                     be requested.
288       *
289       * @throws  LDAPException  If the provided filter string cannot be parsed as
290       *                         an LDAP filter.
291       */
292      public SearchRequest(final String baseDN, final SearchScope scope,
293                           final String filter, final String... attributes)
294             throws LDAPException
295      {
296        this(null, null, baseDN, scope, DereferencePolicy.NEVER, 0, 0, false,
297             Filter.create(filter), attributes);
298      }
299    
300    
301    
302      /**
303       * Creates a new search request with the provided information.  Search result
304       * entries and references will be collected internally and included in the
305       * {@code SearchResult} object returned when search processing is completed.
306       *
307       * @param  baseDN      The base DN for the search request.  It must not be
308       *                     {@code null}.
309       * @param  scope       The scope that specifies the range of entries that
310       *                     should be examined for the search.
311       * @param  filter      The string representation of the filter to use to
312       *                     identify matching entries.  It must not be
313       *                     {@code null}.
314       * @param  attributes  The set of attributes that should be returned in
315       *                     matching entries.  It may be {@code null} or empty if
316       *                     the default attribute set (all user attributes) is to
317       *                     be requested.
318       */
319      public SearchRequest(final String baseDN, final SearchScope scope,
320                           final Filter filter, final String... attributes)
321      {
322        this(null, null, baseDN, scope, DereferencePolicy.NEVER, 0, 0, false,
323             filter, attributes);
324      }
325    
326    
327    
328      /**
329       * Creates a new search request with the provided information.
330       *
331       * @param  searchResultListener  The search result listener that should be
332       *                               used to return results to the client.  It may
333       *                               be {@code null} if the search results should
334       *                               be collected internally and returned in the
335       *                               {@code SearchResult} object.
336       * @param  baseDN                The base DN for the search request.  It must
337       *                               not be {@code null}.
338       * @param  scope                 The scope that specifies the range of entries
339       *                               that should be examined for the search.
340       * @param  filter                The string representation of the filter to
341       *                               use to identify matching entries.  It must
342       *                               not be {@code null}.
343       * @param  attributes            The set of attributes that should be returned
344       *                               in matching entries.  It may be {@code null}
345       *                               or empty if the default attribute set (all
346       *                               user attributes) is to be requested.
347       *
348       * @throws  LDAPException  If the provided filter string cannot be parsed as
349       *                         an LDAP filter.
350       */
351      public SearchRequest(final SearchResultListener searchResultListener,
352                           final String baseDN, final SearchScope scope,
353                           final String filter, final String... attributes)
354             throws LDAPException
355      {
356        this(searchResultListener, null, baseDN, scope, DereferencePolicy.NEVER, 0,
357             0, false, Filter.create(filter), attributes);
358      }
359    
360    
361    
362      /**
363       * Creates a new search request with the provided information.
364       *
365       * @param  searchResultListener  The search result listener that should be
366       *                               used to return results to the client.  It may
367       *                               be {@code null} if the search results should
368       *                               be collected internally and returned in the
369       *                               {@code SearchResult} object.
370       * @param  baseDN                The base DN for the search request.  It must
371       *                               not be {@code null}.
372       * @param  scope                 The scope that specifies the range of entries
373       *                               that should be examined for the search.
374       * @param  filter                The string representation of the filter to
375       *                               use to identify matching entries.  It must
376       *                               not be {@code null}.
377       * @param  attributes            The set of attributes that should be returned
378       *                               in matching entries.  It may be {@code null}
379       *                               or empty if the default attribute set (all
380       *                               user attributes) is to be requested.
381       */
382      public SearchRequest(final SearchResultListener searchResultListener,
383                           final String baseDN, final SearchScope scope,
384                           final Filter filter, final String... attributes)
385      {
386        this(searchResultListener, null, baseDN, scope, DereferencePolicy.NEVER, 0,
387             0, false, filter, attributes);
388      }
389    
390    
391    
392      /**
393       * Creates a new search request with the provided information.  Search result
394       * entries and references will be collected internally and included in the
395       * {@code SearchResult} object returned when search processing is completed.
396       *
397       * @param  baseDN       The base DN for the search request.  It must not be
398       *                      {@code null}.
399       * @param  scope        The scope that specifies the range of entries that
400       *                      should be examined for the search.
401       * @param  derefPolicy  The dereference policy the server should use for any
402       *                      aliases encountered while processing the search.
403       * @param  sizeLimit    The maximum number of entries that the server should
404       *                      return for the search.  A value of zero indicates that
405       *                      there should be no limit.
406       * @param  timeLimit    The maximum length of time in seconds that the server
407       *                      should spend processing this search request.  A value
408       *                      of zero indicates that there should be no limit.
409       * @param  typesOnly    Indicates whether to return only attribute names in
410       *                      matching entries, or both attribute names and values.
411       * @param  filter       The filter to use to identify matching entries.  It
412       *                      must not be {@code null}.
413       * @param  attributes   The set of attributes that should be returned in
414       *                      matching entries.  It may be {@code null} or empty if
415       *                      the default attribute set (all user attributes) is to
416       *                      be requested.
417       *
418       * @throws  LDAPException  If the provided filter string cannot be parsed as
419       *                         an LDAP filter.
420       */
421      public SearchRequest(final String baseDN, final SearchScope scope,
422                           final DereferencePolicy derefPolicy, final int sizeLimit,
423                           final int timeLimit, final boolean typesOnly,
424                           final String filter, final String... attributes)
425             throws LDAPException
426      {
427        this(null, null, baseDN, scope, derefPolicy, sizeLimit, timeLimit,
428             typesOnly, Filter.create(filter), attributes);
429      }
430    
431    
432    
433      /**
434       * Creates a new search request with the provided information.  Search result
435       * entries and references will be collected internally and included in the
436       * {@code SearchResult} object returned when search processing is completed.
437       *
438       * @param  baseDN       The base DN for the search request.  It must not be
439       *                      {@code null}.
440       * @param  scope        The scope that specifies the range of entries that
441       *                      should be examined for the search.
442       * @param  derefPolicy  The dereference policy the server should use for any
443       *                      aliases encountered while processing the search.
444       * @param  sizeLimit    The maximum number of entries that the server should
445       *                      return for the search.  A value of zero indicates that
446       *                      there should be no limit.
447       * @param  timeLimit    The maximum length of time in seconds that the server
448       *                      should spend processing this search request.  A value
449       *                      of zero indicates that there should be no limit.
450       * @param  typesOnly    Indicates whether to return only attribute names in
451       *                      matching entries, or both attribute names and values.
452       * @param  filter       The filter to use to identify matching entries.  It
453       *                      must not be {@code null}.
454       * @param  attributes   The set of attributes that should be returned in
455       *                      matching entries.  It may be {@code null} or empty if
456       *                      the default attribute set (all user attributes) is to
457       *                      be requested.
458       */
459      public SearchRequest(final String baseDN, final SearchScope scope,
460                           final DereferencePolicy derefPolicy, final int sizeLimit,
461                           final int timeLimit, final boolean typesOnly,
462                           final Filter filter, final String... attributes)
463      {
464        this(null, null, baseDN, scope, derefPolicy, sizeLimit, timeLimit,
465             typesOnly, filter, attributes);
466      }
467    
468    
469    
470      /**
471       * Creates a new search request with the provided information.
472       *
473       * @param  searchResultListener  The search result listener that should be
474       *                               used to return results to the client.  It may
475       *                               be {@code null} if the search results should
476       *                               be collected internally and returned in the
477       *                               {@code SearchResult} object.
478       * @param  baseDN                The base DN for the search request.  It must
479       *                               not be {@code null}.
480       * @param  scope                 The scope that specifies the range of entries
481       *                               that should be examined for the search.
482       * @param  derefPolicy           The dereference policy the server should use
483       *                               for any aliases encountered while processing
484       *                               the search.
485       * @param  sizeLimit             The maximum number of entries that the server
486       *                               should return for the search.  A value of
487       *                               zero indicates that there should be no limit.
488       * @param  timeLimit             The maximum length of time in seconds that
489       *                               the server should spend processing this
490       *                               search request.  A value of zero indicates
491       *                               that there should be no limit.
492       * @param  typesOnly             Indicates whether to return only attribute
493       *                               names in matching entries, or both attribute
494       *                               names and values.
495       * @param  filter                The filter to use to identify matching
496       *                               entries.  It must not be {@code null}.
497       * @param  attributes            The set of attributes that should be returned
498       *                               in matching entries.  It may be {@code null}
499       *                               or empty if the default attribute set (all
500       *                               user attributes) is to be requested.
501       *
502       * @throws  LDAPException  If the provided filter string cannot be parsed as
503       *                         an LDAP filter.
504       */
505      public SearchRequest(final SearchResultListener searchResultListener,
506                           final String baseDN, final SearchScope scope,
507                           final DereferencePolicy derefPolicy, final int sizeLimit,
508                           final int timeLimit, final boolean typesOnly,
509                           final String filter, final String... attributes)
510             throws LDAPException
511      {
512        this(searchResultListener, null, baseDN, scope, derefPolicy, sizeLimit,
513             timeLimit, typesOnly, Filter.create(filter), attributes);
514      }
515    
516    
517    
518      /**
519       * Creates a new search request with the provided information.
520       *
521       * @param  searchResultListener  The search result listener that should be
522       *                               used to return results to the client.  It may
523       *                               be {@code null} if the search results should
524       *                               be collected internally and returned in the
525       *                               {@code SearchResult} object.
526       * @param  baseDN                The base DN for the search request.  It must
527       *                               not be {@code null}.
528       * @param  scope                 The scope that specifies the range of entries
529       *                               that should be examined for the search.
530       * @param  derefPolicy           The dereference policy the server should use
531       *                               for any aliases encountered while processing
532       *                               the search.
533       * @param  sizeLimit             The maximum number of entries that the server
534       *                               should return for the search.  A value of
535       *                               zero indicates that there should be no limit.
536       * @param  timeLimit             The maximum length of time in seconds that
537       *                               the server should spend processing this
538       *                               search request.  A value of zero indicates
539       *                               that there should be no limit.
540       * @param  typesOnly             Indicates whether to return only attribute
541       *                               names in matching entries, or both attribute
542       *                               names and values.
543       * @param  filter                The filter to use to identify matching
544       *                               entries.  It must not be {@code null}.
545       * @param  attributes            The set of attributes that should be returned
546       *                               in matching entries.  It may be {@code null}
547       *                               or empty if the default attribute set (all
548       *                               user attributes) is to be requested.
549       */
550      public SearchRequest(final SearchResultListener searchResultListener,
551                           final String baseDN, final SearchScope scope,
552                           final DereferencePolicy derefPolicy, final int sizeLimit,
553                           final int timeLimit, final boolean typesOnly,
554                           final Filter filter, final String... attributes)
555      {
556        this(searchResultListener, null, baseDN, scope, derefPolicy, sizeLimit,
557             timeLimit, typesOnly, filter, attributes);
558      }
559    
560    
561    
562      /**
563       * Creates a new search request with the provided information.
564       *
565       * @param  searchResultListener  The search result listener that should be
566       *                               used to return results to the client.  It may
567       *                               be {@code null} if the search results should
568       *                               be collected internally and returned in the
569       *                               {@code SearchResult} object.
570       * @param  controls              The set of controls to include in the
571       *                               request.  It may be {@code null} or empty if
572       *                               no controls should be included in the
573       *                               request.
574       * @param  baseDN                The base DN for the search request.  It must
575       *                               not be {@code null}.
576       * @param  scope                 The scope that specifies the range of entries
577       *                               that should be examined for the search.
578       * @param  derefPolicy           The dereference policy the server should use
579       *                               for any aliases encountered while processing
580       *                               the search.
581       * @param  sizeLimit             The maximum number of entries that the server
582       *                               should return for the search.  A value of
583       *                               zero indicates that there should be no limit.
584       * @param  timeLimit             The maximum length of time in seconds that
585       *                               the server should spend processing this
586       *                               search request.  A value of zero indicates
587       *                               that there should be no limit.
588       * @param  typesOnly             Indicates whether to return only attribute
589       *                               names in matching entries, or both attribute
590       *                               names and values.
591       * @param  filter                The filter to use to identify matching
592       *                               entries.  It must not be {@code null}.
593       * @param  attributes            The set of attributes that should be returned
594       *                               in matching entries.  It may be {@code null}
595       *                               or empty if the default attribute set (all
596       *                               user attributes) is to be requested.
597       *
598       * @throws  LDAPException  If the provided filter string cannot be parsed as
599       *                         an LDAP filter.
600       */
601      public SearchRequest(final SearchResultListener searchResultListener,
602                           final Control[] controls, final String baseDN,
603                           final SearchScope scope,
604                           final DereferencePolicy derefPolicy, final int sizeLimit,
605                           final int timeLimit, final boolean typesOnly,
606                           final String filter, final String... attributes)
607             throws LDAPException
608      {
609        this(searchResultListener, controls, baseDN, scope, derefPolicy, sizeLimit,
610             timeLimit, typesOnly, Filter.create(filter), attributes);
611      }
612    
613    
614    
615      /**
616       * Creates a new search request with the provided information.
617       *
618       * @param  searchResultListener  The search result listener that should be
619       *                               used to return results to the client.  It may
620       *                               be {@code null} if the search results should
621       *                               be collected internally and returned in the
622       *                               {@code SearchResult} object.
623       * @param  controls              The set of controls to include in the
624       *                               request.  It may be {@code null} or empty if
625       *                               no controls should be included in the
626       *                               request.
627       * @param  baseDN                The base DN for the search request.  It must
628       *                               not be {@code null}.
629       * @param  scope                 The scope that specifies the range of entries
630       *                               that should be examined for the search.
631       * @param  derefPolicy           The dereference policy the server should use
632       *                               for any aliases encountered while processing
633       *                               the search.
634       * @param  sizeLimit             The maximum number of entries that the server
635       *                               should return for the search.  A value of
636       *                               zero indicates that there should be no limit.
637       * @param  timeLimit             The maximum length of time in seconds that
638       *                               the server should spend processing this
639       *                               search request.  A value of zero indicates
640       *                               that there should be no limit.
641       * @param  typesOnly             Indicates whether to return only attribute
642       *                               names in matching entries, or both attribute
643       *                               names and values.
644       * @param  filter                The filter to use to identify matching
645       *                               entries.  It must not be {@code null}.
646       * @param  attributes            The set of attributes that should be returned
647       *                               in matching entries.  It may be {@code null}
648       *                               or empty if the default attribute set (all
649       *                               user attributes) is to be requested.
650       */
651      public SearchRequest(final SearchResultListener searchResultListener,
652                           final Control[] controls, final String baseDN,
653                           final SearchScope scope,
654                           final DereferencePolicy derefPolicy, final int sizeLimit,
655                           final int timeLimit, final boolean typesOnly,
656                           final Filter filter, final String... attributes)
657      {
658        super(controls);
659    
660        ensureNotNull(baseDN, filter);
661    
662        this.baseDN               = baseDN;
663        this.scope                = scope;
664        this.derefPolicy          = derefPolicy;
665        this.typesOnly            = typesOnly;
666        this.filter               = filter;
667        this.searchResultListener = searchResultListener;
668    
669        if (sizeLimit < 0)
670        {
671          this.sizeLimit = 0;
672        }
673        else
674        {
675          this.sizeLimit = sizeLimit;
676        }
677    
678        if (timeLimit < 0)
679        {
680          this.timeLimit = 0;
681        }
682        else
683        {
684          this.timeLimit = timeLimit;
685        }
686    
687        if (attributes == null)
688        {
689          this.attributes = REQUEST_ATTRS_DEFAULT;
690        }
691        else
692        {
693          this.attributes = attributes;
694        }
695      }
696    
697    
698    
699      /**
700       * {@inheritDoc}
701       */
702      public String getBaseDN()
703      {
704        return baseDN;
705      }
706    
707    
708    
709      /**
710       * Specifies the base DN for this search request.
711       *
712       * @param  baseDN  The base DN for this search request.  It must not be
713       *                 {@code null}.
714       */
715      public void setBaseDN(final String baseDN)
716      {
717        ensureNotNull(baseDN);
718    
719        this.baseDN = baseDN;
720      }
721    
722    
723    
724      /**
725       * Specifies the base DN for this search request.
726       *
727       * @param  baseDN  The base DN for this search request.  It must not be
728       *                 {@code null}.
729       */
730      public void setBaseDN(final DN baseDN)
731      {
732        ensureNotNull(baseDN);
733    
734        this.baseDN = baseDN.toString();
735      }
736    
737    
738    
739      /**
740       * {@inheritDoc}
741       */
742      public SearchScope getScope()
743      {
744        return scope;
745      }
746    
747    
748    
749      /**
750       * Specifies the scope for this search request.
751       *
752       * @param  scope  The scope for this search request.
753       */
754      public void setScope(final SearchScope scope)
755      {
756        this.scope = scope;
757      }
758    
759    
760    
761      /**
762       * {@inheritDoc}
763       */
764      public DereferencePolicy getDereferencePolicy()
765      {
766        return derefPolicy;
767      }
768    
769    
770    
771      /**
772       * Specifies the dereference policy that should be used by the server for any
773       * aliases encountered during search processing.
774       *
775       * @param  derefPolicy  The dereference policy that should be used by the
776       *                      server for any aliases encountered during search
777       *                      processing.
778       */
779      public void setDerefPolicy(final DereferencePolicy derefPolicy)
780      {
781        this.derefPolicy = derefPolicy;
782      }
783    
784    
785    
786      /**
787       * {@inheritDoc}
788       */
789      public int getSizeLimit()
790      {
791        return sizeLimit;
792      }
793    
794    
795    
796      /**
797       * Specifies the maximum number of entries that should be returned by the
798       * server when processing this search request.  A value of zero indicates that
799       * there should be no limit.
800       * <BR><BR>
801       * Note that if an attempt to process a search operation fails because the
802       * size limit has been exceeded, an {@code LDAPSearchException} will be
803       * thrown.  If one or more entries or references have already been returned
804       * for the search, then the {@code LDAPSearchException} methods like
805       * {@code getEntryCount}, {@code getSearchEntries}, {@code getReferenceCount},
806       * and {@code getSearchReferences} may be used to obtain information about
807       * those entries and references (although if a search result listener was
808       * provided, then it will have been used to make any entries and references
809       * available, and they will not be available through the
810       * {@code getSearchEntries} and {@code getSearchReferences} methods).
811       *
812       * @param  sizeLimit  The maximum number of entries that should be returned by
813       *                    the server when processing this search request.
814       */
815      public void setSizeLimit(final int sizeLimit)
816      {
817        if (sizeLimit < 0)
818        {
819          this.sizeLimit = 0;
820        }
821        else
822        {
823          this.sizeLimit = sizeLimit;
824        }
825      }
826    
827    
828    
829      /**
830       * {@inheritDoc}
831       */
832      public int getTimeLimitSeconds()
833      {
834        return timeLimit;
835      }
836    
837    
838    
839      /**
840       * Specifies the maximum length of time in seconds that the server should
841       * spend processing this search request.  A value of zero indicates that there
842       * should be no limit.
843       * <BR><BR>
844       * Note that if an attempt to process a search operation fails because the
845       * time limit has been exceeded, an {@code LDAPSearchException} will be
846       * thrown.  If one or more entries or references have already been returned
847       * for the search, then the {@code LDAPSearchException} methods like
848       * {@code getEntryCount}, {@code getSearchEntries}, {@code getReferenceCount},
849       * and {@code getSearchReferences} may be used to obtain information about
850       * those entries and references (although if a search result listener was
851       * provided, then it will have been used to make any entries and references
852       * available, and they will not be available through the
853       * {@code getSearchEntries} and {@code getSearchReferences} methods).
854       *
855       * @param  timeLimit  The maximum length of time in seconds that the server
856       *                    should spend processing this search request.
857       */
858      public void setTimeLimitSeconds(final int timeLimit)
859      {
860        if (timeLimit < 0)
861        {
862          this.timeLimit = 0;
863        }
864        else
865        {
866          this.timeLimit = timeLimit;
867        }
868      }
869    
870    
871    
872      /**
873       * {@inheritDoc}
874       */
875      public boolean typesOnly()
876      {
877        return typesOnly;
878      }
879    
880    
881    
882      /**
883       * Specifies whether the server should return only attribute names in matching
884       * entries, rather than both names and values.
885       *
886       * @param  typesOnly  Specifies whether the server should return only
887       *                    attribute names in matching entries, rather than both
888       *                    names and values.
889       */
890      public void setTypesOnly(final boolean typesOnly)
891      {
892        this.typesOnly = typesOnly;
893      }
894    
895    
896    
897      /**
898       * {@inheritDoc}
899       */
900      public Filter getFilter()
901      {
902        return filter;
903      }
904    
905    
906    
907      /**
908       * Specifies the filter that should be used to identify matching entries.
909       *
910       * @param  filter  The string representation for the filter that should be
911       *                 used to identify matching entries.  It must not be
912       *                 {@code null}.
913       *
914       * @throws  LDAPException  If the provided filter string cannot be parsed as a
915       *                         search filter.
916       */
917      public void setFilter(final String filter)
918             throws LDAPException
919      {
920        ensureNotNull(filter);
921    
922        this.filter = Filter.create(filter);
923      }
924    
925    
926    
927      /**
928       * Specifies the filter that should be used to identify matching entries.
929       *
930       * @param  filter  The filter that should be used to identify matching
931       *                 entries.  It must not be {@code null}.
932       */
933      public void setFilter(final Filter filter)
934      {
935        ensureNotNull(filter);
936    
937        this.filter = filter;
938      }
939    
940    
941    
942      /**
943       * Retrieves the set of requested attributes to include in matching entries.
944       * The caller must not attempt to alter the contents of the array.
945       *
946       * @return  The set of requested attributes to include in matching entries, or
947       *          an empty array if the default set of attributes (all user
948       *          attributes but no operational attributes) should be requested.
949       */
950      public String[] getAttributes()
951      {
952        return attributes;
953      }
954    
955    
956    
957      /**
958       * {@inheritDoc}
959       */
960      public List<String> getAttributeList()
961      {
962        return Collections.unmodifiableList(Arrays.asList(attributes));
963      }
964    
965    
966    
967      /**
968       * Specifies the set of requested attributes to include in matching entries.
969       *
970       * @param  attributes  The set of requested attributes to include in matching
971       *                     entries.  It may be {@code null} if the default set of
972       *                     attributes (all user attributes but no operational
973       *                     attributes) should be requested.
974       */
975      public void setAttributes(final String... attributes)
976      {
977        if (attributes == null)
978        {
979          this.attributes = REQUEST_ATTRS_DEFAULT;
980        }
981        else
982        {
983          this.attributes = attributes;
984        }
985      }
986    
987    
988    
989      /**
990       * Specifies the set of requested attributes to include in matching entries.
991       *
992       * @param  attributes  The set of requested attributes to include in matching
993       *                     entries.  It may be {@code null} if the default set of
994       *                     attributes (all user attributes but no operational
995       *                     attributes) should be requested.
996       */
997      public void setAttributes(final List<String> attributes)
998      {
999        if (attributes == null)
1000        {
1001          this.attributes = REQUEST_ATTRS_DEFAULT;
1002        }
1003        else
1004        {
1005          this.attributes = new String[attributes.size()];
1006          for (int i=0; i < this.attributes.length; i++)
1007          {
1008            this.attributes[i] = attributes.get(i);
1009          }
1010        }
1011      }
1012    
1013    
1014    
1015      /**
1016       * Retrieves the search result listener for this search request, if available.
1017       *
1018       * @return  The search result listener for this search request, or
1019       *          {@code null} if none has been configured.
1020       */
1021      public SearchResultListener getSearchResultListener()
1022      {
1023        return searchResultListener;
1024      }
1025    
1026    
1027    
1028      /**
1029       * {@inheritDoc}
1030       */
1031      public byte getProtocolOpType()
1032      {
1033        return LDAPMessage.PROTOCOL_OP_TYPE_SEARCH_REQUEST;
1034      }
1035    
1036    
1037    
1038      /**
1039       * {@inheritDoc}
1040       */
1041      public void writeTo(final ASN1Buffer writer)
1042      {
1043        final ASN1BufferSequence requestSequence =
1044             writer.beginSequence(LDAPMessage.PROTOCOL_OP_TYPE_SEARCH_REQUEST);
1045        writer.addOctetString(baseDN);
1046        writer.addEnumerated(scope.intValue());
1047        writer.addEnumerated(derefPolicy.intValue());
1048        writer.addInteger(sizeLimit);
1049        writer.addInteger(timeLimit);
1050        writer.addBoolean(typesOnly);
1051        filter.writeTo(writer);
1052    
1053        final ASN1BufferSequence attrSequence = writer.beginSequence();
1054        for (final String s : attributes)
1055        {
1056          writer.addOctetString(s);
1057        }
1058        attrSequence.end();
1059        requestSequence.end();
1060      }
1061    
1062    
1063    
1064      /**
1065       * Encodes the search request protocol op to an ASN.1 element.
1066       *
1067       * @return  The ASN.1 element with the encoded search request protocol op.
1068       */
1069      public ASN1Element encodeProtocolOp()
1070      {
1071        // Create the search request protocol op.
1072        final ASN1Element[] attrElements = new ASN1Element[attributes.length];
1073        for (int i=0; i < attrElements.length; i++)
1074        {
1075          attrElements[i] = new ASN1OctetString(attributes[i]);
1076        }
1077    
1078        final ASN1Element[] protocolOpElements =
1079        {
1080          new ASN1OctetString(baseDN),
1081          new ASN1Enumerated(scope.intValue()),
1082          new ASN1Enumerated(derefPolicy.intValue()),
1083          new ASN1Integer(sizeLimit),
1084          new ASN1Integer(timeLimit),
1085          new ASN1Boolean(typesOnly),
1086          filter.encode(),
1087          new ASN1Sequence(attrElements)
1088        };
1089    
1090        return new ASN1Sequence(LDAPMessage.PROTOCOL_OP_TYPE_SEARCH_REQUEST,
1091                                protocolOpElements);
1092      }
1093    
1094    
1095    
1096      /**
1097       * Sends this search request to the directory server over the provided
1098       * connection and returns the associated response.  The search result entries
1099       * and references will either be collected and returned in the
1100       * {@code SearchResult} object that is returned, or will be interactively
1101       * returned via the {@code SearchResultListener} interface.
1102       *
1103       * @param  connection  The connection to use to communicate with the directory
1104       *                     server.
1105       * @param  depth       The current referral depth for this request.  It should
1106       *                     always be one for the initial request, and should only
1107       *                     be incremented when following referrals.
1108       *
1109       * @return  An object that provides information about the result of the
1110       *          search processing, potentially including the sets of matching
1111       *          entries and/or search references.
1112       *
1113       * @throws  LDAPException  If a problem occurs while sending the request or
1114       *                         reading the response.
1115       */
1116      @Override()
1117      protected SearchResult process(final LDAPConnection connection,
1118                                     final int depth)
1119                throws LDAPException
1120      {
1121        if (connection.synchronousMode())
1122        {
1123          return processSync(connection, depth,
1124               connection.getConnectionOptions().autoReconnect());
1125        }
1126    
1127        final long requestTime = System.nanoTime();
1128        processAsync(connection, null);
1129    
1130        try
1131        {
1132          // Wait for and process the response.
1133          final ArrayList<SearchResultEntry> entryList;
1134          final ArrayList<SearchResultReference> referenceList;
1135          if (searchResultListener == null)
1136          {
1137            entryList     = new ArrayList<SearchResultEntry>(5);
1138            referenceList = new ArrayList<SearchResultReference>(5);
1139          }
1140          else
1141          {
1142            entryList     = null;
1143            referenceList = null;
1144          }
1145    
1146          int numEntries    = 0;
1147          int numReferences = 0;
1148          ResultCode intermediateResultCode = ResultCode.SUCCESS;
1149          final long responseTimeout = getResponseTimeoutMillis(connection);
1150          while (true)
1151          {
1152            final LDAPResponse response;
1153            try
1154            {
1155              if (responseTimeout > 0)
1156              {
1157                response =
1158                     responseQueue.poll(responseTimeout, TimeUnit.MILLISECONDS);
1159              }
1160              else
1161              {
1162                response = responseQueue.take();
1163              }
1164            }
1165            catch (InterruptedException ie)
1166            {
1167              debugException(ie);
1168              throw new LDAPException(ResultCode.LOCAL_ERROR,
1169                   ERR_SEARCH_INTERRUPTED.get(connection.getHostPort()), ie);
1170            }
1171    
1172            if (response == null)
1173            {
1174              if (connection.getConnectionOptions().abandonOnTimeout())
1175              {
1176                connection.abandon(messageID);
1177              }
1178    
1179              final SearchResult searchResult =
1180                   new SearchResult(messageID, ResultCode.TIMEOUT,
1181                        ERR_SEARCH_CLIENT_TIMEOUT.get(responseTimeout, messageID,
1182                             baseDN, scope.getName(), filter.toString(),
1183                             connection.getHostPort()),
1184                        null, null, entryList, referenceList, numEntries,
1185                        numReferences, null);
1186              throw new LDAPSearchException(searchResult);
1187            }
1188    
1189            if (response instanceof ConnectionClosedResponse)
1190            {
1191              final ConnectionClosedResponse ccr =
1192                   (ConnectionClosedResponse) response;
1193              final String message = ccr.getMessage();
1194              if (message == null)
1195              {
1196                // The connection was closed while waiting for the response.
1197                final SearchResult searchResult =
1198                     new SearchResult(messageID, ccr.getResultCode(),
1199                          ERR_CONN_CLOSED_WAITING_FOR_SEARCH_RESPONSE.get(
1200                               connection.getHostPort(), toString()),
1201                          null, null, entryList, referenceList, numEntries,
1202                          numReferences, null);
1203                throw new LDAPSearchException(searchResult);
1204              }
1205              else
1206              {
1207                // The connection was closed while waiting for the response.
1208                final SearchResult searchResult =
1209                     new SearchResult(messageID, ccr.getResultCode(),
1210                          ERR_CONN_CLOSED_WAITING_FOR_SEARCH_RESPONSE_WITH_MESSAGE.
1211                               get(connection.getHostPort(), toString(), message),
1212                          null, null, entryList, referenceList, numEntries,
1213                          numReferences, null);
1214                throw new LDAPSearchException(searchResult);
1215              }
1216            }
1217            else if (response instanceof SearchResultEntry)
1218            {
1219              final SearchResultEntry searchEntry = (SearchResultEntry) response;
1220              numEntries++;
1221              if (searchResultListener == null)
1222              {
1223                entryList.add(searchEntry);
1224              }
1225              else
1226              {
1227                searchResultListener.searchEntryReturned(searchEntry);
1228              }
1229            }
1230            else if (response instanceof SearchResultReference)
1231            {
1232              final SearchResultReference searchReference =
1233                   (SearchResultReference) response;
1234              if (followReferrals(connection))
1235              {
1236                final LDAPResult result = followSearchReference(messageID,
1237                     searchReference, connection, depth);
1238                if (! result.getResultCode().equals(ResultCode.SUCCESS))
1239                {
1240                  // We couldn't follow the reference.  We don't want to fail the
1241                  // entire search because of this right now, so treat it as if
1242                  // referral following had not been enabled.  Also, set the
1243                  // intermediate result code to match that of the result.
1244                  numReferences++;
1245                  if (searchResultListener == null)
1246                  {
1247                    referenceList.add(searchReference);
1248                  }
1249                  else
1250                  {
1251                    searchResultListener.searchReferenceReturned(searchReference);
1252                  }
1253    
1254                  if (intermediateResultCode.equals(ResultCode.SUCCESS))
1255                  {
1256                    intermediateResultCode = result.getResultCode();
1257                  }
1258                }
1259                else if (result instanceof SearchResult)
1260                {
1261                  final SearchResult searchResult = (SearchResult) result;
1262                  numEntries += searchResult.getEntryCount();
1263                  if (searchResultListener == null)
1264                  {
1265                    entryList.addAll(searchResult.getSearchEntries());
1266                  }
1267                }
1268              }
1269              else
1270              {
1271                numReferences++;
1272                if (searchResultListener == null)
1273                {
1274                  referenceList.add(searchReference);
1275                }
1276                else
1277                {
1278                  searchResultListener.searchReferenceReturned(searchReference);
1279                }
1280              }
1281            }
1282            else
1283            {
1284              connection.getConnectionStatistics().incrementNumSearchResponses(
1285                   numEntries, numReferences,
1286                   (System.nanoTime() - requestTime));
1287              SearchResult result = (SearchResult) response;
1288              result.setCounts(numEntries, entryList, numReferences, referenceList);
1289    
1290              if ((result.getResultCode().equals(ResultCode.REFERRAL)) &&
1291                  followReferrals(connection))
1292              {
1293                if (depth >=
1294                    connection.getConnectionOptions().getReferralHopLimit())
1295                {
1296                  return new SearchResult(messageID,
1297                                          ResultCode.REFERRAL_LIMIT_EXCEEDED,
1298                                          ERR_TOO_MANY_REFERRALS.get(),
1299                                          result.getMatchedDN(),
1300                                          result.getReferralURLs(), entryList,
1301                                          referenceList, numEntries,
1302                                          numReferences,
1303                                          result.getResponseControls());
1304                }
1305    
1306                result = followReferral(result, connection, depth);
1307              }
1308    
1309              if ((result.getResultCode().equals(ResultCode.SUCCESS)) &&
1310                  (! intermediateResultCode.equals(ResultCode.SUCCESS)))
1311              {
1312                return new SearchResult(messageID, intermediateResultCode,
1313                                        result.getDiagnosticMessage(),
1314                                        result.getMatchedDN(),
1315                                        result.getReferralURLs(),
1316                                        entryList, referenceList, numEntries,
1317                                        numReferences,
1318                                        result.getResponseControls());
1319              }
1320    
1321              return result;
1322            }
1323          }
1324        }
1325        finally
1326        {
1327          connection.deregisterResponseAcceptor(messageID);
1328        }
1329      }
1330    
1331    
1332    
1333      /**
1334       * Sends this search request to the directory server over the provided
1335       * connection and returns the message ID for the request.
1336       *
1337       * @param  connection      The connection to use to communicate with the
1338       *                         directory server.
1339       * @param  resultListener  The async result listener that is to be notified
1340       *                         when the response is received.  It may be
1341       *                         {@code null} only if the result is to be processed
1342       *                         by this class.
1343       *
1344       * @return  The async request ID created for the operation, or {@code null} if
1345       *          the provided {@code resultListener} is {@code null} and the
1346       *          operation will not actually be processed asynchronously.
1347       *
1348       * @throws  LDAPException  If a problem occurs while sending the request.
1349       */
1350      AsyncRequestID processAsync(final LDAPConnection connection,
1351                                  final AsyncSearchResultListener resultListener)
1352                     throws LDAPException
1353      {
1354        // Create the LDAP message.
1355        messageID = connection.nextMessageID();
1356        final LDAPMessage message = new LDAPMessage(messageID, this, getControls());
1357    
1358    
1359        // If the provided async result listener is {@code null}, then we'll use
1360        // this class as the message acceptor.  Otherwise, create an async helper
1361        // and use it as the message acceptor.
1362        final AsyncRequestID asyncRequestID;
1363        if (resultListener == null)
1364        {
1365          asyncRequestID = null;
1366          connection.registerResponseAcceptor(messageID, this);
1367        }
1368        else
1369        {
1370          final AsyncSearchHelper helper = new AsyncSearchHelper(connection,
1371               messageID, resultListener, getIntermediateResponseListener());
1372          connection.registerResponseAcceptor(messageID, helper);
1373          asyncRequestID = helper.getAsyncRequestID();
1374    
1375          final long timeout = getResponseTimeoutMillis(connection);
1376          if (timeout > 0L)
1377          {
1378            final Timer timer = connection.getTimer();
1379            final AsyncTimeoutTimerTask timerTask =
1380                 new AsyncTimeoutTimerTask(helper);
1381            timer.schedule(timerTask, timeout);
1382            asyncRequestID.setTimerTask(timerTask);
1383          }
1384        }
1385    
1386    
1387        // Send the request to the server.
1388        try
1389        {
1390          debugLDAPRequest(this);
1391          connection.getConnectionStatistics().incrementNumSearchRequests();
1392          connection.sendMessage(message);
1393          return asyncRequestID;
1394        }
1395        catch (LDAPException le)
1396        {
1397          debugException(le);
1398    
1399          connection.deregisterResponseAcceptor(messageID);
1400          throw le;
1401        }
1402      }
1403    
1404    
1405    
1406      /**
1407       * Processes this search operation in synchronous mode, in which the same
1408       * thread will send the request and read the response.
1409       *
1410       * @param  connection  The connection to use to communicate with the directory
1411       *                     server.
1412       * @param  depth       The current referral depth for this request.  It should
1413       *                     always be one for the initial request, and should only
1414       *                     be incremented when following referrals.
1415       * @param  allowRetry  Indicates whether the request may be re-tried on a
1416       *                     re-established connection if the initial attempt fails
1417       *                     in a way that indicates the connection is no longer
1418       *                     valid and autoReconnect is true.
1419       *
1420       * @return  An LDAP result object that provides information about the result
1421       *          of the search processing.
1422       *
1423       * @throws  LDAPException  If a problem occurs while sending the request or
1424       *                         reading the response.
1425       */
1426      private SearchResult processSync(final LDAPConnection connection,
1427                                       final int depth, final boolean allowRetry)
1428              throws LDAPException
1429      {
1430        // Create the LDAP message.
1431        messageID = connection.nextMessageID();
1432        final LDAPMessage message =
1433             new LDAPMessage(messageID,  this, getControls());
1434    
1435    
1436        // Set the appropriate timeout on the socket.
1437        final long responseTimeout = getResponseTimeoutMillis(connection);
1438        try
1439        {
1440          connection.getConnectionInternals(true).getSocket().setSoTimeout(
1441               (int) responseTimeout);
1442        }
1443        catch (Exception e)
1444        {
1445          debugException(e);
1446        }
1447    
1448    
1449        // Send the request to the server.
1450        final long requestTime = System.nanoTime();
1451        debugLDAPRequest(this);
1452        connection.getConnectionStatistics().incrementNumSearchRequests();
1453        try
1454        {
1455          connection.sendMessage(message);
1456        }
1457        catch (final LDAPException le)
1458        {
1459          debugException(le);
1460    
1461          if (allowRetry)
1462          {
1463            final SearchResult retryResult = reconnectAndRetry(connection, depth,
1464                 le.getResultCode(), 0, 0);
1465            if (retryResult != null)
1466            {
1467              return retryResult;
1468            }
1469          }
1470    
1471          throw le;
1472        }
1473    
1474        final ArrayList<SearchResultEntry> entryList;
1475        final ArrayList<SearchResultReference> referenceList;
1476        if (searchResultListener == null)
1477        {
1478          entryList     = new ArrayList<SearchResultEntry>(5);
1479          referenceList = new ArrayList<SearchResultReference>(5);
1480        }
1481        else
1482        {
1483          entryList     = null;
1484          referenceList = null;
1485        }
1486    
1487        int numEntries    = 0;
1488        int numReferences = 0;
1489        ResultCode intermediateResultCode = ResultCode.SUCCESS;
1490        while (true)
1491        {
1492          final LDAPResponse response;
1493          try
1494          {
1495            response = connection.readResponse(messageID);
1496          }
1497          catch (final LDAPException le)
1498          {
1499            debugException(le);
1500    
1501            if ((le.getResultCode() == ResultCode.TIMEOUT) &&
1502                connection.getConnectionOptions().abandonOnTimeout())
1503            {
1504              connection.abandon(messageID);
1505            }
1506    
1507            if (allowRetry)
1508            {
1509              final SearchResult retryResult = reconnectAndRetry(connection, depth,
1510                   le.getResultCode(), numEntries, numReferences);
1511              if (retryResult != null)
1512              {
1513                return retryResult;
1514              }
1515            }
1516    
1517            throw le;
1518          }
1519    
1520          if (response == null)
1521          {
1522            if (connection.getConnectionOptions().abandonOnTimeout())
1523            {
1524              connection.abandon(messageID);
1525            }
1526    
1527            throw new LDAPException(ResultCode.TIMEOUT,
1528                 ERR_SEARCH_CLIENT_TIMEOUT.get(responseTimeout, messageID, baseDN,
1529                      scope.getName(), filter.toString(),
1530                      connection.getHostPort()));
1531          }
1532          else if (response instanceof ConnectionClosedResponse)
1533          {
1534    
1535            if (allowRetry)
1536            {
1537              final SearchResult retryResult = reconnectAndRetry(connection, depth,
1538                   ResultCode.SERVER_DOWN, numEntries, numReferences);
1539              if (retryResult != null)
1540              {
1541                return retryResult;
1542              }
1543            }
1544    
1545            final ConnectionClosedResponse ccr =
1546                 (ConnectionClosedResponse) response;
1547            final String msg = ccr.getMessage();
1548            if (msg == null)
1549            {
1550              // The connection was closed while waiting for the response.
1551              final SearchResult searchResult =
1552                   new SearchResult(messageID, ccr.getResultCode(),
1553                        ERR_CONN_CLOSED_WAITING_FOR_SEARCH_RESPONSE.get(
1554                             connection.getHostPort(), toString()),
1555                        null, null, entryList, referenceList, numEntries,
1556                        numReferences, null);
1557              throw new LDAPSearchException(searchResult);
1558            }
1559            else
1560            {
1561              // The connection was closed while waiting for the response.
1562              final SearchResult searchResult =
1563                   new SearchResult(messageID, ccr.getResultCode(),
1564                        ERR_CONN_CLOSED_WAITING_FOR_SEARCH_RESPONSE_WITH_MESSAGE.
1565                             get(connection.getHostPort(), toString(), msg),
1566                        null, null, entryList, referenceList, numEntries,
1567                        numReferences, null);
1568              throw new LDAPSearchException(searchResult);
1569            }
1570          }
1571          else if (response instanceof IntermediateResponse)
1572          {
1573            final IntermediateResponseListener listener =
1574                 getIntermediateResponseListener();
1575            if (listener != null)
1576            {
1577              listener.intermediateResponseReturned(
1578                   (IntermediateResponse) response);
1579            }
1580          }
1581          else if (response instanceof SearchResultEntry)
1582          {
1583            final SearchResultEntry searchEntry = (SearchResultEntry) response;
1584            numEntries++;
1585            if (searchResultListener == null)
1586            {
1587              entryList.add(searchEntry);
1588            }
1589            else
1590            {
1591              searchResultListener.searchEntryReturned(searchEntry);
1592            }
1593          }
1594          else if (response instanceof SearchResultReference)
1595          {
1596            final SearchResultReference searchReference =
1597                 (SearchResultReference) response;
1598            if (followReferrals(connection))
1599            {
1600              final LDAPResult result = followSearchReference(messageID,
1601                   searchReference, connection, depth);
1602              if (! result.getResultCode().equals(ResultCode.SUCCESS))
1603              {
1604                // We couldn't follow the reference.  We don't want to fail the
1605                // entire search because of this right now, so treat it as if
1606                // referral following had not been enabled.  Also, set the
1607                // intermediate result code to match that of the result.
1608                numReferences++;
1609                if (searchResultListener == null)
1610                {
1611                  referenceList.add(searchReference);
1612                }
1613                else
1614                {
1615                  searchResultListener.searchReferenceReturned(searchReference);
1616                }
1617    
1618                if (intermediateResultCode.equals(ResultCode.SUCCESS))
1619                {
1620                  intermediateResultCode = result.getResultCode();
1621                }
1622              }
1623              else if (result instanceof SearchResult)
1624              {
1625                final SearchResult searchResult = (SearchResult) result;
1626                numEntries += searchResult.getEntryCount();
1627                if (searchResultListener == null)
1628                {
1629                  entryList.addAll(searchResult.getSearchEntries());
1630                }
1631              }
1632            }
1633            else
1634            {
1635              numReferences++;
1636              if (searchResultListener == null)
1637              {
1638                referenceList.add(searchReference);
1639              }
1640              else
1641              {
1642                searchResultListener.searchReferenceReturned(searchReference);
1643              }
1644            }
1645          }
1646          else
1647          {
1648            final SearchResult result = (SearchResult) response;
1649            if (allowRetry)
1650            {
1651              final SearchResult retryResult = reconnectAndRetry(connection,
1652                   depth, result.getResultCode(), numEntries, numReferences);
1653              if (retryResult != null)
1654              {
1655                return retryResult;
1656              }
1657            }
1658    
1659            return handleResponse(connection, response, requestTime, depth,
1660                                  numEntries, numReferences, entryList,
1661                                  referenceList, intermediateResultCode);
1662          }
1663        }
1664      }
1665    
1666    
1667    
1668      /**
1669       * Attempts to re-establish the connection and retry processing this request
1670       * on it.
1671       *
1672       * @param  connection     The connection to be re-established.
1673       * @param  depth          The current referral depth for this request.  It
1674       *                        should always be one for the initial request, and
1675       *                        should only be incremented when following referrals.
1676       * @param  resultCode     The result code for the previous operation attempt.
1677       * @param  numEntries     The number of search result entries already sent for
1678       *                        the search operation.
1679       * @param  numReferences  The number of search result references already sent
1680       *                        for the search operation.
1681       *
1682       * @return  The result from re-trying the search, or {@code null} if it could
1683       *          not be re-tried.
1684       */
1685      private SearchResult reconnectAndRetry(final LDAPConnection connection,
1686                                             final int depth,
1687                                             final ResultCode resultCode,
1688                                             final int numEntries,
1689                                             final int numReferences)
1690      {
1691        try
1692        {
1693          // We will only want to retry for certain result codes that indicate a
1694          // connection problem.
1695          switch (resultCode.intValue())
1696          {
1697            case ResultCode.SERVER_DOWN_INT_VALUE:
1698            case ResultCode.DECODING_ERROR_INT_VALUE:
1699            case ResultCode.CONNECT_ERROR_INT_VALUE:
1700              // We want to try to re-establish the connection no matter what, but
1701              // we only want to retry the search if we haven't yet sent any
1702              // results.
1703              connection.reconnect();
1704              if ((numEntries == 0) && (numReferences == 0))
1705              {
1706                return processSync(connection, depth, false);
1707              }
1708              break;
1709          }
1710        }
1711        catch (final Exception e)
1712        {
1713          debugException(e);
1714        }
1715    
1716        return null;
1717      }
1718    
1719    
1720    
1721      /**
1722       * Performs the necessary processing for handling a response.
1723       *
1724       * @param  connection              The connection used to read the response.
1725       * @param  response                The response to be processed.
1726       * @param  requestTime             The time the request was sent to the
1727       *                                 server.
1728       * @param  depth                   The current referral depth for this
1729       *                                 request.  It should always be one for the
1730       *                                 initial request, and should only be
1731       *                                 incremented when following referrals.
1732       * @param  numEntries              The number of entries received from the
1733       *                                 server.
1734       * @param  numReferences           The number of references received from
1735       *                                 the server.
1736       * @param  entryList               The list of search result entries received
1737       *                                 from the server, if applicable.
1738       * @param  referenceList           The list of search result references
1739       *                                 received from the server, if applicable.
1740       * @param  intermediateResultCode  The intermediate result code so far for the
1741       *                                 search operation.
1742       *
1743       * @return  The search result.
1744       *
1745       * @throws  LDAPException  If a problem occurs.
1746       */
1747      private SearchResult handleResponse(final LDAPConnection connection,
1748                   final LDAPResponse response, final long requestTime,
1749                   final int depth, final int numEntries, final int numReferences,
1750                   final List<SearchResultEntry> entryList,
1751                   final List<SearchResultReference> referenceList,
1752                   final ResultCode intermediateResultCode)
1753              throws LDAPException
1754      {
1755        connection.getConnectionStatistics().incrementNumSearchResponses(
1756             numEntries, numReferences,
1757             (System.nanoTime() - requestTime));
1758        SearchResult result = (SearchResult) response;
1759        result.setCounts(numEntries, entryList, numReferences, referenceList);
1760    
1761        if ((result.getResultCode().equals(ResultCode.REFERRAL)) &&
1762            followReferrals(connection))
1763        {
1764          if (depth >=
1765              connection.getConnectionOptions().getReferralHopLimit())
1766          {
1767            return new SearchResult(messageID,
1768                                    ResultCode.REFERRAL_LIMIT_EXCEEDED,
1769                                    ERR_TOO_MANY_REFERRALS.get(),
1770                                    result.getMatchedDN(),
1771                                    result.getReferralURLs(), entryList,
1772                                    referenceList, numEntries,
1773                                    numReferences,
1774                                    result.getResponseControls());
1775          }
1776    
1777          result = followReferral(result, connection, depth);
1778        }
1779    
1780        if ((result.getResultCode().equals(ResultCode.SUCCESS)) &&
1781            (! intermediateResultCode.equals(ResultCode.SUCCESS)))
1782        {
1783          return new SearchResult(messageID, intermediateResultCode,
1784                                  result.getDiagnosticMessage(),
1785                                  result.getMatchedDN(),
1786                                  result.getReferralURLs(),
1787                                  entryList, referenceList, numEntries,
1788                                  numReferences,
1789                                  result.getResponseControls());
1790        }
1791    
1792        return result;
1793      }
1794    
1795    
1796    
1797      /**
1798       * Attempts to follow a search result reference to continue a search in a
1799       * remote server.
1800       *
1801       * @param  messageID        The message ID for the LDAP message that is
1802       *                          associated with this result.
1803       * @param  searchReference  The search result reference to follow.
1804       * @param  connection       The connection on which the reference was
1805       *                          received.
1806       * @param  depth            The number of referrals followed in the course of
1807       *                          processing this request.
1808       *
1809       * @return  The result of attempting to follow the search result reference.
1810       *
1811       * @throws  LDAPException  If a problem occurs while attempting to establish
1812       *                         the referral connection, sending the request, or
1813       *                         reading the result.
1814       */
1815      private LDAPResult followSearchReference(final int messageID,
1816                              final SearchResultReference searchReference,
1817                              final LDAPConnection connection, final int depth)
1818              throws LDAPException
1819      {
1820        for (final String urlString : searchReference.getReferralURLs())
1821        {
1822          try
1823          {
1824            final LDAPURL referralURL = new LDAPURL(urlString);
1825            final String host = referralURL.getHost();
1826    
1827            if (host == null)
1828            {
1829              // We can't handle a referral in which there is no host.
1830              continue;
1831            }
1832    
1833            final String requestBaseDN;
1834            if (referralURL.baseDNProvided())
1835            {
1836              requestBaseDN = referralURL.getBaseDN().toString();
1837            }
1838            else
1839            {
1840              requestBaseDN = baseDN;
1841            }
1842    
1843            final SearchScope requestScope;
1844            if (referralURL.scopeProvided())
1845            {
1846              requestScope = referralURL.getScope();
1847            }
1848            else
1849            {
1850              requestScope = scope;
1851            }
1852    
1853            final Filter requestFilter;
1854            if (referralURL.filterProvided())
1855            {
1856              requestFilter = referralURL.getFilter();
1857            }
1858            else
1859            {
1860              requestFilter = filter;
1861            }
1862    
1863    
1864            final SearchRequest searchRequest =
1865                 new SearchRequest(searchResultListener, getControls(),
1866                                   requestBaseDN, requestScope, derefPolicy,
1867                                   sizeLimit, timeLimit, typesOnly, requestFilter,
1868                                   attributes);
1869    
1870            final LDAPConnection referralConn = connection.getReferralConnector().
1871                 getReferralConnection(referralURL, connection);
1872    
1873            try
1874            {
1875              return searchRequest.process(referralConn, depth+1);
1876            }
1877            finally
1878            {
1879              referralConn.setDisconnectInfo(DisconnectType.REFERRAL, null, null);
1880              referralConn.close();
1881            }
1882          }
1883          catch (LDAPException le)
1884          {
1885            debugException(le);
1886    
1887            if (le.getResultCode().equals(ResultCode.REFERRAL_LIMIT_EXCEEDED))
1888            {
1889              throw le;
1890            }
1891          }
1892        }
1893    
1894        // If we've gotten here, then we could not follow any of the referral URLs,
1895        // so we'll create a failure result.
1896        return new SearchResult(messageID, ResultCode.REFERRAL, null, null,
1897                                searchReference.getReferralURLs(), 0, 0, null);
1898      }
1899    
1900    
1901    
1902      /**
1903       * Attempts to follow a referral to perform an add operation in the target
1904       * server.
1905       *
1906       * @param  referralResult  The LDAP result object containing information about
1907       *                         the referral to follow.
1908       * @param  connection      The connection on which the referral was received.
1909       * @param  depth           The number of referrals followed in the course of
1910       *                         processing this request.
1911       *
1912       * @return  The result of attempting to process the add operation by following
1913       *          the referral.
1914       *
1915       * @throws  LDAPException  If a problem occurs while attempting to establish
1916       *                         the referral connection, sending the request, or
1917       *                         reading the result.
1918       */
1919      private SearchResult followReferral(final SearchResult referralResult,
1920                                          final LDAPConnection connection,
1921                                          final int depth)
1922              throws LDAPException
1923      {
1924        for (final String urlString : referralResult.getReferralURLs())
1925        {
1926          try
1927          {
1928            final LDAPURL referralURL = new LDAPURL(urlString);
1929            final String host = referralURL.getHost();
1930    
1931            if (host == null)
1932            {
1933              // We can't handle a referral in which there is no host.
1934              continue;
1935            }
1936    
1937            final String requestBaseDN;
1938            if (referralURL.baseDNProvided())
1939            {
1940              requestBaseDN = referralURL.getBaseDN().toString();
1941            }
1942            else
1943            {
1944              requestBaseDN = baseDN;
1945            }
1946    
1947            final SearchScope requestScope;
1948            if (referralURL.scopeProvided())
1949            {
1950              requestScope = referralURL.getScope();
1951            }
1952            else
1953            {
1954              requestScope = scope;
1955            }
1956    
1957            final Filter requestFilter;
1958            if (referralURL.filterProvided())
1959            {
1960              requestFilter = referralURL.getFilter();
1961            }
1962            else
1963            {
1964              requestFilter = filter;
1965            }
1966    
1967    
1968            final SearchRequest searchRequest =
1969                 new SearchRequest(searchResultListener, getControls(),
1970                                   requestBaseDN, requestScope, derefPolicy,
1971                                   sizeLimit, timeLimit, typesOnly, requestFilter,
1972                                   attributes);
1973    
1974            final LDAPConnection referralConn = connection.getReferralConnector().
1975                 getReferralConnection(referralURL, connection);
1976            try
1977            {
1978              return searchRequest.process(referralConn, depth+1);
1979            }
1980            finally
1981            {
1982              referralConn.setDisconnectInfo(DisconnectType.REFERRAL, null, null);
1983              referralConn.close();
1984            }
1985          }
1986          catch (LDAPException le)
1987          {
1988            debugException(le);
1989    
1990            if (le.getResultCode().equals(ResultCode.REFERRAL_LIMIT_EXCEEDED))
1991            {
1992              throw le;
1993            }
1994          }
1995        }
1996    
1997        // If we've gotten here, then we could not follow any of the referral URLs,
1998        // so we'll just return the original referral result.
1999        return referralResult;
2000      }
2001    
2002    
2003    
2004      /**
2005       * {@inheritDoc}
2006       */
2007      @InternalUseOnly()
2008      public void responseReceived(final LDAPResponse response)
2009             throws LDAPException
2010      {
2011        try
2012        {
2013          responseQueue.put(response);
2014        }
2015        catch (Exception e)
2016        {
2017          debugException(e);
2018          throw new LDAPException(ResultCode.LOCAL_ERROR,
2019               ERR_EXCEPTION_HANDLING_RESPONSE.get(getExceptionMessage(e)), e);
2020        }
2021      }
2022    
2023    
2024    
2025      /**
2026       * {@inheritDoc}
2027       */
2028      @Override()
2029      public int getLastMessageID()
2030      {
2031        return messageID;
2032      }
2033    
2034    
2035    
2036      /**
2037       * {@inheritDoc}
2038       */
2039      @Override()
2040      public OperationType getOperationType()
2041      {
2042        return OperationType.SEARCH;
2043      }
2044    
2045    
2046    
2047      /**
2048       * {@inheritDoc}
2049       */
2050      public SearchRequest duplicate()
2051      {
2052        return duplicate(getControls());
2053      }
2054    
2055    
2056    
2057      /**
2058       * {@inheritDoc}
2059       */
2060      public SearchRequest duplicate(final Control[] controls)
2061      {
2062        final SearchRequest r = new SearchRequest(searchResultListener, controls,
2063             baseDN, scope, derefPolicy, sizeLimit, timeLimit, typesOnly, filter,
2064             attributes);
2065        if (followReferralsInternal() != null)
2066        {
2067          r.setFollowReferrals(followReferralsInternal());
2068        }
2069    
2070        r.setResponseTimeoutMillis(getResponseTimeoutMillis(null));
2071    
2072        return r;
2073      }
2074    
2075    
2076    
2077      /**
2078       * {@inheritDoc}
2079       */
2080      @Override()
2081      public void toString(final StringBuilder buffer)
2082      {
2083        buffer.append("SearchRequest(baseDN='");
2084        buffer.append(baseDN);
2085        buffer.append("', scope=");
2086        buffer.append(scope);
2087        buffer.append(", deref=");
2088        buffer.append(derefPolicy);
2089        buffer.append(", sizeLimit=");
2090        buffer.append(sizeLimit);
2091        buffer.append(", timeLimit=");
2092        buffer.append(timeLimit);
2093        buffer.append(", filter='");
2094        buffer.append(filter);
2095        buffer.append("', attrs={");
2096    
2097        for (int i=0; i < attributes.length; i++)
2098        {
2099          if (i > 0)
2100          {
2101            buffer.append(", ");
2102          }
2103    
2104          buffer.append(attributes[i]);
2105        }
2106        buffer.append('}');
2107    
2108        final Control[] controls = getControls();
2109        if (controls.length > 0)
2110        {
2111          buffer.append(", controls={");
2112          for (int i=0; i < controls.length; i++)
2113          {
2114            if (i > 0)
2115            {
2116              buffer.append(", ");
2117            }
2118    
2119            buffer.append(controls[i]);
2120          }
2121          buffer.append('}');
2122        }
2123    
2124        buffer.append(')');
2125      }
2126    }