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<>(5); 084 referenceList = new ArrayList<>(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 * {@inheritDoc} 116 */ 117 @InternalUseOnly() 118 @Override() 119 public void searchResultReceived(final AsyncRequestID requestID, 120 final SearchResult searchResult) 121 { 122 this.searchResult = searchResult; 123 } 124 125 126 127 /** 128 * Retrieves the result that has been received for the associated asynchronous 129 * search operation, if it has been received. 130 * 131 * @return The result that has been received for the associated asynchronous 132 * search operation, or {@code null} if no response has been received 133 * yet. 134 */ 135 public SearchResult getSearchResult() 136 { 137 return searchResult; 138 } 139 140 141 142 /** 143 * Retrieves a list of the entries returned for the search operation. This 144 * should only be called after the operation has completed and a 145 * non-{@code null} search result object is available, because it may not be 146 * safe to access the contents of the list if it may be altered while the 147 * search is still in progress. 148 * 149 * @return A list of the entries returned for the search operation. 150 */ 151 public List<SearchResultEntry> getSearchEntries() 152 { 153 return Collections.unmodifiableList(entryList); 154 } 155 156 157 158 /** 159 * Retrieves a list of the references returned for the search operation. This 160 * should only be called after the operation has completed and a 161 * non-{@code null} search result object is available, because it may not be 162 * safe to access the contents of the list if it may be altered while the 163 * search is still in progress. 164 * 165 * @return A list of the references returned for the search operation. 166 */ 167 public List<SearchResultReference> getSearchReferences() 168 { 169 return Collections.unmodifiableList(referenceList); 170 } 171}