1 /* 2 * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.naming; 27 28 import java.util.Enumeration; 29 30 /** 31 * This interface is for enumerating lists returned by 32 * methods in the javax.naming and javax.naming.directory packages. 33 * It extends Enumeration to allow as exceptions to be thrown during 34 * the enumeration. 35 *<p> 36 * When a method such as list(), listBindings(), or search() returns 37 * a NamingEnumeration, any exceptions encountered are reserved until 38 * all results have been returned. At the end of the enumeration, the 39 * exception is thrown (by hasMore()); 40 * <p> 41 * For example, if the list() is 42 * returning only a partial answer, the corresponding exception would 43 * be PartialResultException. list() would first return a NamingEnumeration. 44 * When the last of the results has been returned by the NamingEnumeration's 45 * next(), invoking hasMore() would result in PartialResultException being thrown. 46 *<p> 47 * In another example, if a search() method was invoked with a specified 48 * size limit of 'n'. If the answer consists of more than 'n' results, 49 * search() would first return a NamingEnumeration. 50 * When the n'th result has been returned by invoking next() on the 51 * NamingEnumeration, a SizeLimitExceedException would then thrown when 52 * hasMore() is invoked. 53 *<p> 54 * Note that if the program uses hasMoreElements() and nextElement() instead 55 * to iterate through the NamingEnumeration, because these methods 56 * cannot throw exceptions, no exception will be thrown. Instead, 57 * in the previous example, after the n'th result has been returned by 58 * nextElement(), invoking hasMoreElements() would return false. 59 *<p> 60 * Note also that NoSuchElementException is thrown if the program invokes 61 * next() or nextElement() when there are no elements left in the enumeration. 62 * The program can always avoid this exception by using hasMore() and 63 * hasMoreElements() to check whether the end of the enumeration has been reached. 64 *<p> 65 * If an exception is thrown during an enumeration, 66 * the enumeration becomes invalid. 67 * Subsequent invocation of any method on that enumeration 68 * will yield undefined results. 69 * 70 * @author Rosanna Lee 71 * @author Scott Seligman 72 * 73 * @see Context#list 74 * @see Context#listBindings 75 * @see javax.naming.directory.DirContext#search 76 * @see javax.naming.directory.Attributes#getAll 77 * @see javax.naming.directory.Attributes#getIDs 78 * @see javax.naming.directory.Attribute#getAll 79 * @since 1.3 80 */ 81 public interface NamingEnumeration<T> extends Enumeration<T> { 82 /** 83 * Retrieves the next element in the enumeration. 84 * This method allows naming exceptions encountered while 85 * retrieving the next element to be caught and handled 86 * by the application. 87 * <p> 88 * Note that {@code next()} can also throw the runtime exception 89 * NoSuchElementException to indicate that the caller is 90 * attempting to enumerate beyond the end of the enumeration. 91 * This is different from a NamingException, which indicates 92 * that there was a problem in obtaining the next element, 93 * for example, due to a referral or server unavailability, etc. 94 * 95 * @return The possibly null element in the enumeration. 96 * null is only valid for enumerations that can return 97 * null (e.g. Attribute.getAll() returns an enumeration of 98 * attribute values, and an attribute value can be null). 99 * @exception NamingException If a naming exception is encountered while attempting 100 * to retrieve the next element. See NamingException 101 * and its subclasses for the possible naming exceptions. 102 * @exception java.util.NoSuchElementException If attempting to get the next element when none is available. 103 * @see java.util.Enumeration#nextElement 104 */ next()105 public T next() throws NamingException; 106 107 /** 108 * Determines whether there are any more elements in the enumeration. 109 * This method allows naming exceptions encountered while 110 * determining whether there are more elements to be caught and handled 111 * by the application. 112 * 113 * @return true if there is more in the enumeration ; false otherwise. 114 * @exception NamingException 115 * If a naming exception is encountered while attempting 116 * to determine whether there is another element 117 * in the enumeration. See NamingException 118 * and its subclasses for the possible naming exceptions. 119 * @see java.util.Enumeration#hasMoreElements 120 */ hasMore()121 public boolean hasMore() throws NamingException; 122 123 /** 124 * Closes this enumeration. 125 * 126 * After this method has been invoked on this enumeration, the 127 * enumeration becomes invalid and subsequent invocation of any of 128 * its methods will yield undefined results. 129 * This method is intended for aborting an enumeration to free up resources. 130 * If an enumeration proceeds to the end--that is, until 131 * {@code hasMoreElements()} or {@code hasMore()} returns {@code false}-- 132 * resources will be freed up automatically and there is no need to 133 * explicitly call {@code close()}. 134 *<p> 135 * This method indicates to the service provider that it is free 136 * to release resources associated with the enumeration, and can 137 * notify servers to cancel any outstanding requests. The {@code close()} 138 * method is a hint to implementations for managing their resources. 139 * Implementations are encouraged to use appropriate algorithms to 140 * manage their resources when client omits the {@code close()} calls. 141 * 142 * @exception NamingException If a naming exception is encountered 143 * while closing the enumeration. 144 * @since 1.3 145 */ close()146 public void close() throws NamingException; 147 } 148