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
26package javax.naming;
27
28import 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  */
81public 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      */
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      */
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     */
146    public void close() throws NamingException;
147}
148