2362N/A * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * This interface is for enumerating lists returned by 0N/A * methods in the javax.naming and javax.naming.directory packages. 0N/A * It extends Enumeration to allow as exceptions to be thrown during 0N/A * When a method such as list(), listBindings(), or search() returns 0N/A * a NamingEnumeration, any exceptions encountered are reserved until 0N/A * all results have been returned. At the end of the enumeration, the 0N/A * exception is thrown (by hasMore()); 0N/A * For example, if the list() is 0N/A * returning only a partial answer, the corresponding exception would 0N/A * be PartialResultException. list() would first return a NamingEnumeration. 0N/A * When the last of the results has been returned by the NamingEnumeration's 0N/A * next(), invoking hasMore() would result in PartialResultException being thrown. 0N/A * In another example, if a search() method was invoked with a specified 0N/A * size limit of 'n'. If the answer consists of more than 'n' results, 0N/A * search() would first return a NamingEnumeration. 0N/A * When the n'th result has been returned by invoking next() on the 0N/A * NamingEnumeration, a SizeLimitExceedException would then thrown when 0N/A * hasMore() is invoked. 0N/A * Note that if the program uses hasMoreElements() and nextElement() instead 0N/A * to iterate through the NamingEnumeration, because these methods 0N/A * cannot throw exceptions, no exception will be thrown. Instead, 0N/A * in the previous example, after the n'th result has been returned by 0N/A * nextElement(), invoking hasMoreElements() would return false. 0N/A * Note also that NoSuchElementException is thrown if the program invokes 0N/A * next() or nextElement() when there are no elements left in the enumeration. 0N/A * The program can always avoid this exception by using hasMore() and 0N/A * hasMoreElements() to check whether the end of the enumeration has been reached. 0N/A * If an exception is thrown during an enumeration, 0N/A * the enumeration becomes invalid. 0N/A * Subsequent invocation of any method on that enumeration 0N/A * will yield undefined results. 0N/A * @author Rosanna Lee 0N/A * @author Scott Seligman 0N/A * @see Context#listBindings 0N/A * @see javax.naming.directory.DirContext#search 0N/A * @see javax.naming.directory.Attributes#getAll 0N/A * @see javax.naming.directory.Attributes#getIDs 0N/A * @see javax.naming.directory.Attribute#getAll 0N/A * Retrieves the next element in the enumeration. 0N/A * This method allows naming exceptions encountered while 0N/A * retrieving the next element to be caught and handled 0N/A * by the application. 0N/A * Note that <tt>next()</tt> can also throw the runtime exception 0N/A * NoSuchElementException to indicate that the caller is 0N/A * attempting to enumerate beyond the end of the enumeration. 0N/A * This is different from a NamingException, which indicates 0N/A * that there was a problem in obtaining the next element, 0N/A * for example, due to a referral or server unavailability, etc. 0N/A * @return The possibly null element in the enumeration. 0N/A * null is only valid for enumerations that can return 0N/A * null (e.g. Attribute.getAll() returns an enumeration of 0N/A * attribute values, and an attribute value can be null). 0N/A * @exception NamingException If a naming exception is encountered while attempting 0N/A * to retrieve the next element. See NamingException 0N/A * and its subclasses for the possible naming exceptions. 0N/A * @exception java.util.NoSuchElementException If attempting to get the next element when none is available. 0N/A * @see java.util.Enumeration#nextElement 0N/A * Determines whether there are any more elements in the enumeration. 0N/A * This method allows naming exceptions encountered while 0N/A * determining whether there are more elements to be caught and handled 0N/A * by the application. 0N/A * @return true if there is more in the enumeration ; false otherwise. 0N/A * @exception NamingException 0N/A * If a naming exception is encountered while attempting 0N/A * to determine whether there is another element 0N/A * in the enumeration. See NamingException 0N/A * and its subclasses for the possible naming exceptions. 0N/A * @see java.util.Enumeration#hasMoreElements 0N/A * Closes this enumeration. 0N/A * After this method has been invoked on this enumeration, the 0N/A * enumeration becomes invalid and subsequent invocation of any of 0N/A * its methods will yield undefined results. 0N/A * This method is intended for aborting an enumeration to free up resources. 0N/A * If an enumeration proceeds to the end--that is, until 0N/A * <tt>hasMoreElements()</tt> or <tt>hasMore()</tt> returns <tt>false</tt>-- 0N/A * resources will be freed up automatically and there is no need to 0N/A * explicitly call <tt>close()</tt>. 0N/A * This method indicates to the service provider that it is free 0N/A * to release resources associated with the enumeration, and can 0N/A * notify servers to cancel any outstanding requests. The <tt>close()</tt> 0N/A * method is a hint to implementations for managing their resources. 0N/A * Implementations are encouraged to use appropriate algorithms to 0N/A * manage their resources when client omits the <tt>close()</tt> calls. 0N/A * @exception NamingException If a naming exception is encountered 0N/A * while closing the enumeration.