001/*
002 * Copyright 2011-2018 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2011-2018 Ping Identity Corporation
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  @Override()
094  public void searchEntryReturned(final SearchResultEntry searchEntry)
095  {
096    entryList.add(searchEntry);
097  }
098
099
100
101  /**
102   * {@inheritDoc}
103   */
104  @InternalUseOnly()
105  @Override()
106  public void searchReferenceReturned(
107                   final SearchResultReference searchReference)
108  {
109    referenceList.add(searchReference);
110  }
111
112
113
114
115  /**
116   * {@inheritDoc}
117   */
118  @InternalUseOnly()
119  @Override()
120  public void searchResultReceived(final AsyncRequestID requestID,
121                                    final SearchResult searchResult)
122  {
123    this.searchResult = searchResult;
124  }
125
126
127
128  /**
129   * Retrieves the result that has been received for the associated asynchronous
130   * search operation, if it has been received.
131   *
132   * @return  The result that has been received for the associated asynchronous
133   *          search operation, or {@code null} if no response has been received
134   *          yet.
135   */
136  public SearchResult getSearchResult()
137  {
138    return searchResult;
139  }
140
141
142
143  /**
144   * Retrieves a list of the entries returned for the search operation.  This
145   * should only be called after the operation has completed and a
146   * non-{@code null} search result object is available, because it may not be
147   * safe to access the contents of the list if it may be altered while the
148   * search is still in progress.
149   *
150   * @return  A list of the entries returned for the search operation.
151   */
152  public List<SearchResultEntry> getSearchEntries()
153  {
154    return Collections.unmodifiableList(entryList);
155  }
156
157
158
159  /**
160   * Retrieves a list of the references returned for the search operation.  This
161   * should only be called after the operation has completed and a
162   * non-{@code null} search result object is available, because it may not be
163   * safe to access the contents of the list if it may be altered while the
164   * search is still in progress.
165   *
166   * @return  A list of the references returned for the search operation.
167   */
168  public List<SearchResultReference> getSearchReferences()
169  {
170    return Collections.unmodifiableList(referenceList);
171  }
172}