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  ;
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  <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  ;
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  ;
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  ;
130 }
131
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags