List the Context

Instead of getting a single object at a time, as with Context.lookup() , you can list an entire context by using a single operation. There are two methods for listing a context: one that returns the bindings and one that returns only the name-to-object class name pairs.

The Context.List() Method

Context.list() returns an enumeration of NameClassPair . Each NameClassPair consists of the object's name and its class name. The following code fragment lists the contents of the "ou=People" directory (i.e., the files and directories found in "ou=People" directory).

NamingEnumeration list = ctx.list("ou=People");

while (list.hasMore()) {
    NameClassPair nc = (NameClassPair)list.next();
    System.out.println(nc);
}

Running this example yields the following output.

# java List
cn=Jon Ruiz: javax.naming.directory.DirContext
cn=Scott Seligman: javax.naming.directory.DirContext
cn=Samuel Clemens: javax.naming.directory.DirContext
cn=Rosanna Lee: javax.naming.directory.DirContext
cn=Maxine Erlund: javax.naming.directory.DirContext
cn=Niels Bohr: javax.naming.directory.DirContext
cn=Uri Geller: javax.naming.directory.DirContext
cn=Colleen Sullivan: javax.naming.directory.DirContext
cn=Vinnie Ryan: javax.naming.directory.DirContext
cn=Rod Serling: javax.naming.directory.DirContext
cn=Jonathan Wood: javax.naming.directory.DirContext
cn=Aravindan Ranganathan: javax.naming.directory.DirContext
cn=Ian Anderson: javax.naming.directory.DirContext
cn=Lao Tzu: javax.naming.directory.DirContext
cn=Don Knuth: javax.naming.directory.DirContext
cn=Roger Waters: javax.naming.directory.DirContext
cn=Ben Dubin: javax.naming.directory.DirContext
cn=Spuds Mackenzie: javax.naming.directory.DirContext
cn=John Fowler: javax.naming.directory.DirContext
cn=Londo Mollari: javax.naming.directory.DirContext
cn=Ted Geisel: javax.naming.directory.DirContext

The Context.listBindings() Method

Context.listBindings() returns an enumeration of Binding . Binding is a subclass of NameClassPair. A binding contains not only the object's name and class name, but also the object. The following code enumerates the "ou=People" context, printing out each binding's name and object.

NamingEnumeration bindings = ctx.listBindings("ou=People");

while (bindings.hasMore()) {
    Binding bd = (Binding)bindings.next();
    System.out.println(bd.getName() + ": " + bd.getObject());
}

Running this example yields the following output.

# java ListBindings
cn=Jon Ruiz: [email protected]
cn=Scott Seligman: [email protected]
cn=Samuel Clemens: [email protected]
cn=Rosanna Lee: [email protected]
cn=Maxine Erlund: [email protected]
cn=Niels Bohr: [email protected]
cn=Uri Geller: [email protected]
cn=Colleen Sullivan: [email protected]
cn=Vinnie Ryan: [email protected]
cn=Rod Serling: [email protected]
cn=Jonathan Wood: [email protected]
cn=Aravindan Ranganathan: [email protected]
cn=Ian Anderson: [email protected]
cn=Lao Tzu: [email protected]
cn=Don Knuth: [email protected]
cn=Roger Waters: [email protected]
cn=Ben Dubin: [email protected]
cn=Spuds Mackenzie: [email protected]
cn=John Fowler: [email protected]
cn=Londo Mollari: [email protected]
cn=Ted Geisel: [email protected]

Terminating a NamingEnumeration

A NamingEnumeration can be terminated in one of three ways: naturally, explicitly, or unexpectedly.

  • When NamingEnumeration.hasMore() returns false, the enumeration is complete and effectively terminated.
  • You can terminate an enumeration explicitly before it has completed by invoking NamingEnumeration.close() . Doing this provides a hint to the underlying implementation to free up any resources associated with the enumeration.
  • If either hasMore() or next() throws a NamingException , then the enumeration is effectively terminated.

Regardless of how an enumeration has been terminated, once terminated it can no longer be used. Invoking a method on a terminated enumeration yields an undefined result.

Why Two Different List Methods?

list() is intended for browser-style applications that just want to display the names of objects in a context. For example, a browser might list the names in a context and wait for the user to select one or a few of the names displayed to perform further operations. Such applications typically do not need access to all of the objects in a context.

listBindings() is intended for applications that need to perform operations on the objects in a context en masse. For example, a backup application might need to perform "file stats" operations on all of the objects in a file directory. Or a printer administration program might want to restart all of the printers in a building. To perform such operations, these applications need to obtain all of the objects bound in a context. Thus it is more expedient to have the objects returned as part of the enumeration.

The application can use either list() or the potentially more expensive listBindings(), depending on the type of information it needs.