| Naming Operations

## Listing a 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 `"awt"` directory (i.e., the files and directories found in `"awt"` directory).

> >     NamingEnumeration list = ctx.list("awt");

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

> Running this example yields the following output.

> >     # java List
> >     accessibility: javax.naming.Context
> >     color: javax.naming.Context
> >     datatransfer: javax.naming.Context
> >     dnd: javax.naming.Context
> >     event: javax.naming.Context
> >     font: javax.naming.Context
> >     geom: javax.naming.Context
> >     im: javax.naming.Context
> >     image: javax.naming.Context
> >     peer: javax.naming.Context
> >     print: javax.naming.Context
> >     swing: javax.naming.Context

> #### 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 `"awt"` context, printing out each binding's name and object.

> >     NamingEnumeration bindings = ctx.listBindings("awt");

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

> Running this example yields the following output.

> >     # java ListBindings
> >     accessibility: com.sun.jndi.fscontext.RefFSContext@1dacd52e
> >     color: com.sun.jndi.fscontext.RefFSContext@1dacd551
> >     datatransfer: com.sun.jndi.fscontext.RefFSContext@1dacd584
> >     dnd: com.sun.jndi.fscontext.RefFSContext@1dacd5b6
> >     event: com.sun.jndi.fscontext.RefFSContext@1dacd5e8
> >     font: com.sun.jndi.fscontext.RefFSContext@1dacd61b
> >     geom: com.sun.jndi.fscontext.RefFSContext@1dacd64d
> >     im: com.sun.jndi.fscontext.RefFSContext@1dacd62a
> >     image: com.sun.jndi.fscontext.RefFSContext@1dacd65c
> >     peer: com.sun.jndi.fscontext.RefFSContext@1dacd68f
> >     print: com.sun.jndi.fscontext.RefFSContext@1dacd6c1
> >     swing: com.sun.jndi.fscontext.RefFSContext@1dacd6f3

> #### 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.

| Naming Operations