com.unboundid.ldap.sdk.LDAPEntrySource Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of unboundid-ldapsdk Show documentation
Show all versions of unboundid-ldapsdk Show documentation
The UnboundID LDAP SDK for Java is a fast, comprehensive, and easy-to-use
Java API for communicating with LDAP directory servers and performing
related tasks like reading and writing LDIF, encoding and decoding data
using base64 and ASN.1 BER, and performing secure communication. This
package contains the Standard Edition of the LDAP SDK, which is a
complete, general-purpose library for communicating with LDAPv3 directory
servers.
/*
* Copyright 2009-2022 Ping Identity Corporation
* All Rights Reserved.
*/
/*
* Copyright 2009-2022 Ping Identity Corporation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/*
* Copyright (C) 2009-2022 Ping Identity Corporation
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License (GPLv2 only)
* or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
* as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see .
*/
package com.unboundid.ldap.sdk;
import java.util.concurrent.LinkedBlockingQueue;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.concurrent.atomic.AtomicReference;
import com.unboundid.util.Debug;
import com.unboundid.util.InternalUseOnly;
import com.unboundid.util.NotNull;
import com.unboundid.util.Nullable;
import com.unboundid.util.ThreadSafety;
import com.unboundid.util.ThreadSafetyLevel;
import com.unboundid.util.Validator;
import static com.unboundid.ldap.sdk.LDAPMessages.*;
/**
* This class provides an {@link EntrySource} that will read entries matching a
* given set of search criteria from an LDAP directory server. It may
* optionally close the associated connection after all entries have been read.
*
* This implementation processes the search asynchronously, which provides two
* benefits:
*
* - It makes it easier to provide a throttling mechanism to prevent the
* entries from piling up and causing the client to run out of memory if
* the server returns them faster than the client can process them. If
* this occurs, then the client will queue up a small number of entries
* but will then push back against the server to block it from sending
* additional entries until the client can catch up. In this case, no
* entries should be lost, although some servers may impose limits on how
* long a search may be active or other forms of constraints.
* - It makes it possible to abandon the search if the entry source is no
* longer needed (as signified by calling the {@link #close} method) and
* the caller intends to stop iterating through the results.
*
* Example
* The following example demonstrates the process that may be used for iterating
* across all entries containing the {@code person} object class using the LDAP
* entry source API:
*
* SearchRequest searchRequest = new SearchRequest("dc=example,dc=com",
* SearchScope.SUB, Filter.createEqualityFilter("objectClass", "person"));
* LDAPEntrySource entrySource = new LDAPEntrySource(connection,
* searchRequest, false);
*
* int entriesRead = 0;
* int referencesRead = 0;
* int exceptionsCaught = 0;
* try
* {
* while (true)
* {
* try
* {
* Entry entry = entrySource.nextEntry();
* if (entry == null)
* {
* // There are no more entries to be read.
* break;
* }
* else
* {
* // Do something with the entry here.
* entriesRead++;
* }
* }
* catch (SearchResultReferenceEntrySourceException e)
* {
* // The directory server returned a search result reference.
* SearchResultReference searchReference = e.getSearchReference();
* referencesRead++;
* }
* catch (EntrySourceException e)
* {
* // Some kind of problem was encountered (e.g., the connection is no
* // longer valid). See if we can continue reading entries.
* exceptionsCaught++;
* if (! e.mayContinueReading())
* {
* break;
* }
* }
* }
* }
* finally
* {
* entrySource.close();
* }
*
*/
@ThreadSafety(level=ThreadSafetyLevel.NOT_THREADSAFE)
public final class LDAPEntrySource
extends EntrySource
implements AsyncSearchResultListener
{
/**
* The bogus entry that will be used to signify the end of the results.
*/
@NotNull private static final String END_OF_RESULTS = "END OF RESULTS";
/**
* The serial version UID for this serializable class.
*/
private static final long serialVersionUID = 1080386705549149135L;
// The request ID associated with the asynchronous search.
@NotNull private final AsyncRequestID asyncRequestID;
// Indicates whether this entry source has been closed.
@NotNull private final AtomicBoolean closed;
// The search result for the search operation.
@NotNull private final AtomicReference searchResult;
// Indicates whether to close the connection when this entry source is closed.
private final boolean closeConnection;
// The connection that will be used to read the entries.
@NotNull private final LDAPConnection connection;
// The queue from which entries will be read.
@NotNull private final LinkedBlockingQueue