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