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}