001/* 002 * Copyright 2009-2020 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright 2009-2020 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) 2009-2020 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.io.Closeable; 041 042import com.unboundid.util.NotExtensible; 043import com.unboundid.util.ThreadSafety; 044import com.unboundid.util.ThreadSafetyLevel; 045 046 047 048/** 049 * This class defines an API that may be implemented by a class that provides 050 * access to a sequence of entries, one entry at a time (e.g., entries read from 051 * an LDIF file, or returned as part of an LDAP search). It provides a 052 * convenient way to operate on a set of entries without regard for the source 053 * of those entries. Implementations currently available include the 054 * {@link LDAPEntrySource} class, which can be used to iterate across entries 055 * returned from a directory server in response to a search request, and the 056 * {@link com.unboundid.ldif.LDIFEntrySource} class, which can be used to 057 * iterate across entries in an LDIF file. 058 * <BR><BR> 059 * Note that the {@link #close} method MUST be called if the entry source is to 060 * be discarded before guaranteeing that all entries have been read. The 061 * {@code close} method may be called after all entries have been read, but it 062 * is not required. All entry source implementations MUST ensure that all 063 * resources are properly released if the caller has read through all entries, 064 * or if an error occurs that prevents the caller from continuing to read 065 * through the entries (i.e., if {@link #nextEntry} throws an 066 * {@link EntrySourceException} and the 067 * {@link EntrySourceException#mayContinueReading()} method returns 068 * {@code false}). 069 * <BR><BR> 070 * <H2>Example</H2> 071 * The following example demonstrates the process that may be used for iterating 072 * across the entries provided by an entry source: 073 * <PRE> 074 * LDIFReader ldifReader = new LDIFReader(ldifFilePath); 075 * EntrySource entrySource = new LDIFEntrySource(ldifReader); 076 * 077 * int entriesRead = 0; 078 * int exceptionsCaught = 0; 079 * try 080 * { 081 * while (true) 082 * { 083 * try 084 * { 085 * Entry entry = entrySource.nextEntry(); 086 * if (entry == null) 087 * { 088 * // There are no more entries to be read. 089 * break; 090 * } 091 * else 092 * { 093 * // Do something with the entry here. 094 * entriesRead++; 095 * } 096 * } 097 * catch (EntrySourceException e) 098 * { 099 * // Some kind of problem was encountered (e.g., a malformed entry 100 * // found in an LDIF file, or a referral returned from a directory). 101 * // See if we can continue reading entries. 102 * exceptionsCaught++; 103 * if (! e.mayContinueReading()) 104 * { 105 * break; 106 * } 107 * } 108 * } 109 * } 110 * finally 111 * { 112 * entrySource.close(); 113 * } 114 * </PRE> 115 */ 116@NotExtensible() 117@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE) 118public abstract class EntrySource 119 implements Closeable 120{ 121 /** 122 * Retrieves the next entry from the entry source, if there is at least one 123 * remaining entry. This method may block if no entries are immediately 124 * available. 125 * 126 * @return The next entry from the entry source, or {@code null} if there are 127 * no more entries to retrieve.. 128 * 129 * @throws EntrySourceException If a problem occurs while attempting to read 130 * the next entry from the entry source. 131 */ 132 public abstract Entry nextEntry() 133 throws EntrySourceException; 134 135 136 137 /** 138 * Indicates that this entry source will no longer be needed and any resources 139 * associated with it may be closed. This method MUST be called if the entry 140 * source is no longer needed before all entries have been read. It MAY be 141 * called after all entries have been read with no ill effects, but this is 142 * not necessary as the entry source will have already been closed after all 143 * entries have been read. 144 */ 145 @Override() 146 public abstract void close(); 147}