JavaTM Platform
Standard Ed. 6

javax.naming
接口 NamingEnumeration<T>

所有超级接口:
Enumeration<T>

public interface NamingEnumeration<T>
extends Enumeration<T>

此接口用于枚举 javax.naming 和 javax.naming.directory 包中的方法所返回的列表。它扩展了 Enumeration,允许在枚举期间抛出异常。

当某一方法(比如 list()、listBindings() 或 search())返回 NamingEnumeration 时,在返回所有结果之前,将保留所遇到的所有异常。在枚举结束时抛出异常(由 hasMore() 完成)。

例如,如果 list() 只返回一部分内容,则相应的异常将是 PartialResultException。list() 将先返回一个 NamingEnumeration。当已由 NamingEnumeration 的 next() 返回最后结果时,调用 hasMore() 将导致抛出 PartialResultException。

在另一个示例中,在指定大小限制为 'n' 的情况下调用 search() 方法。如果结果由 'n' 个以上的结果组成,则 search() 将首先返回一个 NamingEnumeration。当已经通过对 NamingEnumeration 调用 next() 返回了第 n 个结果时,将在调用 hasMore() 时抛出 SizeLimitExceedException。

注意,如果程序使用 hasMoreElements() 和 nextElement() 而不是在 NamingEnumeration 上迭代,那么因为这些方法无法抛出异常,所以不会抛出异常。此外,在前面的示例中,在 nextElement() 已返回第 n 个结果后,调用 hasMoreElements() 将返回 false。

还要注意的是,如果在枚举中没有剩余元素时该程序调用 next() 或 nextElement(),则将抛出 NoSuchElementException。通过使用 hasMore() 和 hasMoreElements() 检查是否已经到达枚举末尾,程序总是可以避免此异常。

如果枚举期间抛出异常,则该枚举变得无效。对该枚举后续调用任何方法都将产生不确定的结果。

从以下版本开始:
1.3
另请参见:
Context.list(javax.naming.Name), Context.listBindings(javax.naming.Name), DirContext.search(javax.naming.Name, javax.naming.directory.Attributes, java.lang.String[]), Attributes.getAll(), Attributes.getIDs(), Attribute.getAll()

方法摘要
 void close()
          关闭此枚举。
 boolean hasMore()
          确定枚举中是否还有元素。
 T next()
          检索枚举中的下一个元素。
 
从接口 java.util.Enumeration 继承的方法
hasMoreElements, nextElement
 

方法详细信息

next

T next()
       throws NamingException
检索枚举中的下一个元素。此方法允许应用程序捕获并处理在检索下一个元素时遇到的命名异常。

注意,next() 还可以抛出运行时异常 NoSuchElementException,指示调用者试图超出枚举的尾部进行枚举。此异常不同于 NamingException,后者指示在获得下一个元素时存在问题,比如说,因为某一项引用或者服务器不可用等等。

返回:
枚举中的元素(可能为 null)。只有对于可以返回 null 的枚举而言,null 才是有效值(例如,Attribute.getAll() 返回一个属性值所组成的枚举,属性值可以为 null)。
抛出:
NamingException - 如果在试图检索下一个元素时遇到命名异常。有关可能的命名异常,请参见 NamingException 及其子类。
NoSuchElementException - 如果试图在没有元素可用时获得下一个元素。
另请参见:
Enumeration.nextElement()

hasMore

boolean hasMore()
                throws NamingException
确定枚举中是否还有元素。此方法允许应用程序捕获并处理在确定是否还有元素时遇到的命名异常。

返回:
如果枚举中还有元素,则返回 true;否则返回 false。
抛出:
NamingException - 如果在试图确定枚举中是否还有另一个元素时遇到命名异常。有关可能的命名异常,请参见 NamingException 及其子类。
另请参见:
Enumeration.hasMoreElements()

close

void close()
           throws NamingException
关闭此枚举。 当已对此枚举调用此方法之后,枚举变得无效,并且对其方法的任何后续调用都将产生不确定的结果。此方法主要用于终止枚举,释放资源。如果枚举进行到结尾处(也就是说,一直到 hasMoreElements()hasMore() 返回 false),则资源将被自动释放,无需显式调用 close()

此方法指示服务提供者随意释放与该枚举关联的资源,并且可以通知服务器取消任何未处理的请求。close() 方法是实现管理其资源的一个提示。当客户端忽略 close() 调用时,建议实现使用适当的算法管理其资源。

抛出:
NamingException - 如果关闭枚举时遇到命名异常。
从以下版本开始:
1.3

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策