public interface NamingEnumeration<T> extends Enumeration<T>
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.
| Modifier and Type | Method and Description |
|---|---|
void |
close()
Closes this enumeration.
|
boolean |
hasMore()
Determines whether there are any more elements in the enumeration.
|
T |
next()
Retrieves the next element in the enumeration.
|
hasMoreElements, nextElementT next() throws NamingException
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.
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.Enumeration.nextElement()boolean hasMore()
throws NamingException
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.Enumeration.hasMoreElements()void close()
throws NamingException
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.
NamingException - If a naming exception is encountered
while closing the enumeration. Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.
DRAFT ea-b138