KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > naming > NamingEnumeration


1 /*
2  * @(#)NamingEnumeration.java 1.8 04/05/05
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package javax.naming;
9
10 import java.util.Enumeration JavaDoc;
11
12 /**
13   * This interface is for enumerating lists returned by
14   * methods in the javax.naming and javax.naming.directory packages.
15   * It extends Enumeration to allow as exceptions to be thrown during
16   * the enumeration.
17   *<p>
18   * When a method such as list(), listBindings(), or search() returns
19   * a NamingEnumeration, any exceptions encountered are reserved until
20   * all results have been returned. At the end of the enumeration, the
21   * exception is thrown (by hasMore());
22   * <p>
23   * For example, if the list() is
24   * returning only a partial answer, the corresponding exception would
25   * be PartialResultException. list() would first return a NamingEnumeration.
26   * When the last of the results has been returned by the NamingEnumeration's
27   * next(), invoking hasMore() would result in PartialResultException being thrown.
28   *<p>
29   * In another example, if a search() method was invoked with a specified
30   * size limit of 'n'. If the answer consists of more than 'n' results,
31   * search() would first return a NamingEnumeration.
32   * When the n'th result has been returned by invoking next() on the
33   * NamingEnumeration, a SizeLimitExceedException would then thrown when
34   * hasMore() is invoked.
35   *<p>
36   * Note that if the program uses hasMoreElements() and nextElement() instead
37   * to iterate through the NamingEnumeration, because these methods
38   * cannot throw exceptions, no exception will be thrown. Instead,
39   * in the previous example, after the n'th result has been returned by
40   * nextElement(), invoking hasMoreElements() would return false.
41   *<p>
42   * Note also that NoSuchElementException is thrown if the program invokes
43   * next() or nextElement() when there are no elements left in the enumeration.
44   * The program can always avoid this exception by using hasMore() and
45   * hasMoreElements() to check whether the end of the enumeration has been reached.
46   *<p>
47   * If an exception is thrown during an enumeration,
48   * the enumeration becomes invalid.
49   * Subsequent invocation of any method on that enumeration
50   * will yield undefined results.
51   *
52   * @author Rosanna Lee
53   * @author Scott Seligman
54   * @version 1.8 04/05/05
55   *
56   * @see Context#list
57   * @see Context#listBindings
58   * @see javax.naming.directory.DirContext#search
59   * @see javax.naming.directory.Attributes#getAll
60   * @see javax.naming.directory.Attributes#getIDs
61   * @see javax.naming.directory.Attribute#getAll
62   * @since 1.3
63   */

64 public interface NamingEnumeration<T> extends Enumeration JavaDoc<T> {
65     /**
66       * Retrieves the next element in the enumeration.
67       * This method allows naming exceptions encountered while
68       * retrieving the next element to be caught and handled
69       * by the application.
70       * <p>
71       * Note that <tt>next()</tt> can also throw the runtime exception
72       * NoSuchElementException to indicate that the caller is
73       * attempting to enumerate beyond the end of the enumeration.
74       * This is different from a NamingException, which indicates
75       * that there was a problem in obtaining the next element,
76       * for example, due to a referral or server unavailability, etc.
77       *
78       * @return The possibly null element in the enumeration.
79       * null is only valid for enumerations that can return
80       * null (e.g. Attribute.getAll() returns an enumeration of
81       * attribute values, and an attribute value can be null).
82       * @exception NamingException If a naming exception is encountered while attempting
83       * to retrieve the next element. See NamingException
84       * and its subclasses for the possible naming exceptions.
85       * @exception java.util.NoSuchElementException If attempting to get the next element when none is available.
86       * @see java.util.Enumeration#nextElement
87       */

88     public T next() throws NamingException JavaDoc;
89
90     /**
91       * Determines whether there are any more elements in the enumeration.
92       * This method allows naming exceptions encountered while
93       * determining whether there are more elements to be caught and handled
94       * by the application.
95       *
96       * @return true if there is more in the enumeration ; false otherwise.
97       * @exception NamingException
98       * If a naming exception is encountered while attempting
99       * to determine whether there is another element
100       * in the enumeration. See NamingException
101       * and its subclasses for the possible naming exceptions.
102       * @see java.util.Enumeration#hasMoreElements
103       */

104     public boolean hasMore() throws NamingException JavaDoc;
105
106     /**
107      * Closes this enumeration.
108      *
109      * After this method has been invoked on this enumeration, the
110      * enumeration becomes invalid and subsequent invocation of any of
111      * its methods will yield undefined results.
112      * This method is intended for aborting an enumeration to free up resources.
113      * If an enumeration proceeds to the end--that is, until
114      * <tt>hasMoreElements()</tt> or <tt>hasMore()</tt> returns <tt>false</tt>--
115      * resources will be freed up automatically and there is no need to
116      * explicitly call <tt>close()</tt>.
117      *<p>
118      * This method indicates to the service provider that it is free
119      * to release resources associated with the enumeration, and can
120      * notify servers to cancel any outstanding requests. The <tt>close()</tt>
121      * method is a hint to implementations for managing their resources.
122      * Implementations are encouraged to use appropriate algorithms to
123      * manage their resources when client omits the <tt>close()</tt> calls.
124      *
125      * @exception NamingException If a naming exception is encountered
126      * while closing the enumeration.
127      * @since 1.3
128      */

129     public void close() throws NamingException JavaDoc;
130 }
131
Popular Tags