001    /*
002     * Copyright 2011-2015 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2011-2015 UnboundID Corp.
007     *
008     * This program is free software; you can redistribute it and/or modify
009     * it under the terms of the GNU General Public License (GPLv2 only)
010     * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011     * as published by the Free Software Foundation.
012     *
013     * This program is distributed in the hope that it will be useful,
014     * but WITHOUT ANY WARRANTY; without even the implied warranty of
015     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016     * GNU General Public License for more details.
017     *
018     * You should have received a copy of the GNU General Public License
019     * along with this program; if not, see <http://www.gnu.org/licenses>.
020     */
021    package com.unboundid.ldap.sdk;
022    
023    
024    
025    import java.util.ArrayList;
026    import java.util.Collections;
027    import java.util.List;
028    
029    import com.unboundid.util.InternalUseOnly;
030    import com.unboundid.util.Mutable;
031    import com.unboundid.util.ThreadSafety;
032    import com.unboundid.util.ThreadSafetyLevel;
033    
034    
035    
036    /**
037     * This class provides a basic implementation of the
038     * {@link AsyncSearchResultListener} interface that will merely set the
039     * result object to a local variable that can be accessed through a getter
040     * method.  It provides a listener that may be easily used when processing
041     * an asynchronous search operation using the {@link AsyncRequestID} as a
042     * {@code java.util.concurrent.Future} object.
043     * <BR><BR>
044     * Note that this class stores all entries and references returned by the
045     * associated search in memory so that they can be retrieved in lists.  This may
046     * not be suitable for searches that have the potential return a large number
047     * of entries.  For such searches, an alternate
048     * {@link AsyncSearchResultListener} implementation may be needed, or it may be
049     * more appropriate to use an {@link LDAPEntrySource} object for the search.
050     */
051    @Mutable()
052    @ThreadSafety(level=ThreadSafetyLevel.NOT_THREADSAFE)
053    public final class BasicAsyncSearchResultListener
054           implements AsyncSearchResultListener
055    {
056      /**
057       * The serial version UID for this serializable class.
058       */
059      private static final long serialVersionUID = 2289128360755244209L;
060    
061    
062    
063      // The list of search result entries that have been returned.
064      private final List<SearchResultEntry> entryList;
065    
066      // The list of search result references that have been returned.
067      private final List<SearchResultReference> referenceList;
068    
069      // The search result that has been received for the associated search
070      // operation.
071      private volatile SearchResult searchResult;
072    
073    
074    
075      /**
076       * Creates a new instance of this class for use in processing a single search
077       * operation.  A single basic async search result listener object may not be
078       * used for multiple operations.
079       */
080      public BasicAsyncSearchResultListener()
081      {
082        searchResult  = null;
083        entryList     = new ArrayList<SearchResultEntry>(5);
084        referenceList = new ArrayList<SearchResultReference>(5);
085      }
086    
087    
088    
089      /**
090       * {@inheritDoc}
091       */
092      @InternalUseOnly()
093      public void searchEntryReturned(final SearchResultEntry searchEntry)
094      {
095        entryList.add(searchEntry);
096      }
097    
098    
099    
100      /**
101       * {@inheritDoc}
102       */
103      @InternalUseOnly()
104      public void searchReferenceReturned(
105                       final SearchResultReference searchReference)
106      {
107        referenceList.add(searchReference);
108      }
109    
110    
111    
112    
113      /**
114       * {@inheritDoc}
115       */
116      @InternalUseOnly()
117      public void searchResultReceived(final AsyncRequestID requestID,
118                                        final SearchResult searchResult)
119      {
120        this.searchResult = searchResult;
121      }
122    
123    
124    
125      /**
126       * Retrieves the result that has been received for the associated asynchronous
127       * search operation, if it has been received.
128       *
129       * @return  The result that has been received for the associated asynchronous
130       *          search operation, or {@code null} if no response has been received
131       *          yet.
132       */
133      public SearchResult getSearchResult()
134      {
135        return searchResult;
136      }
137    
138    
139    
140      /**
141       * Retrieves a list of the entries returned for the search operation.  This
142       * should only be called after the operation has completed and a
143       * non-{@code null} search result object is available, because it may not be
144       * safe to access the contents of the list if it may be altered while the
145       * search is still in progress.
146       *
147       * @return  A list of the entries returned for the search operation.
148       */
149      public List<SearchResultEntry> getSearchEntries()
150      {
151        return Collections.unmodifiableList(entryList);
152      }
153    
154    
155    
156      /**
157       * Retrieves a list of the references returned for the search operation.  This
158       * should only be called after the operation has completed and a
159       * non-{@code null} search result object is available, because it may not be
160       * safe to access the contents of the list if it may be altered while the
161       * search is still in progress.
162       *
163       * @return  A list of the references returned for the search operation.
164       */
165      public List<SearchResultReference> getSearchReferences()
166      {
167        return Collections.unmodifiableList(referenceList);
168      }
169    }