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