001 /*
002 * Copyright 1999-2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.naming;
027
028 import java.util.Enumeration;
029
030 /**
031 * This interface is for enumerating lists returned by
032 * methods in the javax.naming and javax.naming.directory packages.
033 * It extends Enumeration to allow as exceptions to be thrown during
034 * the enumeration.
035 *<p>
036 * When a method such as list(), listBindings(), or search() returns
037 * a NamingEnumeration, any exceptions encountered are reserved until
038 * all results have been returned. At the end of the enumeration, the
039 * exception is thrown (by hasMore());
040 * <p>
041 * For example, if the list() is
042 * returning only a partial answer, the corresponding exception would
043 * be PartialResultException. list() would first return a NamingEnumeration.
044 * When the last of the results has been returned by the NamingEnumeration's
045 * next(), invoking hasMore() would result in PartialResultException being thrown.
046 *<p>
047 * In another example, if a search() method was invoked with a specified
048 * size limit of 'n'. If the answer consists of more than 'n' results,
049 * search() would first return a NamingEnumeration.
050 * When the n'th result has been returned by invoking next() on the
051 * NamingEnumeration, a SizeLimitExceedException would then thrown when
052 * hasMore() is invoked.
053 *<p>
054 * Note that if the program uses hasMoreElements() and nextElement() instead
055 * to iterate through the NamingEnumeration, because these methods
056 * cannot throw exceptions, no exception will be thrown. Instead,
057 * in the previous example, after the n'th result has been returned by
058 * nextElement(), invoking hasMoreElements() would return false.
059 *<p>
060 * Note also that NoSuchElementException is thrown if the program invokes
061 * next() or nextElement() when there are no elements left in the enumeration.
062 * The program can always avoid this exception by using hasMore() and
063 * hasMoreElements() to check whether the end of the enumeration has been reached.
064 *<p>
065 * If an exception is thrown during an enumeration,
066 * the enumeration becomes invalid.
067 * Subsequent invocation of any method on that enumeration
068 * will yield undefined results.
069 *
070 * @author Rosanna Lee
071 * @author Scott Seligman
072 * @version 1.15 07/05/05
073 *
074 * @see Context#list
075 * @see Context#listBindings
076 * @see javax.naming.directory.DirContext#search
077 * @see javax.naming.directory.Attributes#getAll
078 * @see javax.naming.directory.Attributes#getIDs
079 * @see javax.naming.directory.Attribute#getAll
080 * @since 1.3
081 */
082 public interface NamingEnumeration<T> extends Enumeration<T> {
083 /**
084 * Retrieves the next element in the enumeration.
085 * This method allows naming exceptions encountered while
086 * retrieving the next element to be caught and handled
087 * by the application.
088 * <p>
089 * Note that <tt>next()</tt> can also throw the runtime exception
090 * NoSuchElementException to indicate that the caller is
091 * attempting to enumerate beyond the end of the enumeration.
092 * This is different from a NamingException, which indicates
093 * that there was a problem in obtaining the next element,
094 * for example, due to a referral or server unavailability, etc.
095 *
096 * @return The possibly null element in the enumeration.
097 * null is only valid for enumerations that can return
098 * null (e.g. Attribute.getAll() returns an enumeration of
099 * attribute values, and an attribute value can be null).
100 * @exception NamingException If a naming exception is encountered while attempting
101 * to retrieve the next element. See NamingException
102 * and its subclasses for the possible naming exceptions.
103 * @exception java.util.NoSuchElementException If attempting to get the next element when none is available.
104 * @see java.util.Enumeration#nextElement
105 */
106 public T next() throws NamingException;
107
108 /**
109 * Determines whether there are any more elements in the enumeration.
110 * This method allows naming exceptions encountered while
111 * determining whether there are more elements to be caught and handled
112 * by the application.
113 *
114 * @return true if there is more in the enumeration ; false otherwise.
115 * @exception NamingException
116 * If a naming exception is encountered while attempting
117 * to determine whether there is another element
118 * in the enumeration. See NamingException
119 * and its subclasses for the possible naming exceptions.
120 * @see java.util.Enumeration#hasMoreElements
121 */
122 public boolean hasMore() throws NamingException;
123
124 /**
125 * Closes this enumeration.
126 *
127 * After this method has been invoked on this enumeration, the
128 * enumeration becomes invalid and subsequent invocation of any of
129 * its methods will yield undefined results.
130 * This method is intended for aborting an enumeration to free up resources.
131 * If an enumeration proceeds to the end--that is, until
132 * <tt>hasMoreElements()</tt> or <tt>hasMore()</tt> returns <tt>false</tt>--
133 * resources will be freed up automatically and there is no need to
134 * explicitly call <tt>close()</tt>.
135 *<p>
136 * This method indicates to the service provider that it is free
137 * to release resources associated with the enumeration, and can
138 * notify servers to cancel any outstanding requests. The <tt>close()</tt>
139 * method is a hint to implementations for managing their resources.
140 * Implementations are encouraged to use appropriate algorithms to
141 * manage their resources when client omits the <tt>close()</tt> calls.
142 *
143 * @exception NamingException If a naming exception is encountered
144 * while closing the enumeration.
145 * @since 1.3
146 */
147 public void close() throws NamingException;
148 }
|