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