https://openjdk.java.net/ 
/*
 * 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.


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());


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.


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.


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.


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.


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, Scott Seligman
See Also:
Since:1.3
/**
  * 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.

 Note that next() 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. 
Throws:
  • NamingException – If a naming exception is encountered while attempting
                to retrieve the next element. See NamingException
                and its subclasses for the possible naming exceptions.
  • NoSuchElementException – If attempting to get the next element when none is available.
See Also:
Returns:        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).
/**
      * 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 {@code next()} 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.

Throws:
  • 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 Also:
Returns:        true if there is more in the enumeration ; false otherwise.
/**
      * 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 hasMoreElements() or hasMore() returns false-- resources will be freed up automatically and there is no need to explicitly call close(). 
 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 close() 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 close() calls. 
Throws:
  • NamingException – If a naming exception is encountered
while closing the enumeration.
Since:1.3
/**
     * 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
     * {@code hasMoreElements()} or {@code hasMore()} returns {@code false}--
     * resources will be freed up automatically and there is no need to
     * explicitly call {@code close()}.
     *<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 {@code close()}
     * 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 {@code close()} calls.
     *
     * @exception NamingException If a naming exception is encountered
     * while closing the enumeration.
     * @since 1.3
     */
    public void close() throws NamingException;
}