001/*
002 * Copyright 2011-2014 UnboundID Corp.
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2011-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 */
021package com.unboundid.ldap.sdk;
022
023
024
025import java.util.ArrayList;
026import java.util.Collections;
027import java.util.List;
028
029import com.unboundid.util.InternalUseOnly;
030import com.unboundid.util.Mutable;
031import com.unboundid.util.ThreadSafety;
032import 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)
053public 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}