001 /*
002 * Copyright 2011-2013 UnboundID Corp.
003 * All Rights Reserved.
004 */
005 /*
006 * Copyright (C) 2011-2013 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 }