| Event Notification

## Naming Events

> After a `NamespaceChangeListener` or `ObjectChangeListener` has been registered with an event source, it will get event notifications in the form of `NamingEvent`s. An instance of this class contains information about the event, such as its type and event source, and information about the object that caused the event to be fired. Typically, an event source creates an instance of `NamingEvent` and passes it to naming listeners. The naming listeners then can use the `NamingEvent` instance's access methods to obtain information about the event.

> #### Event Type

> A `NamingEvent` contains a type that identifies the type of event. An event type could be, for example object-added or object-changed. Event types are categorized into those that affect the namespace (such as an object-added type) and those that do not (such as an object-changed type). Here are the event types defined in the `NamingEvent` class.
> - `NamingEvent.OBJECT_CHANGED`: An object's content has changed. For example, one of its attribute has been removed or perhaps its binding has been replaced.
> - `NamingEvent.OBJECT_ADDED`: A new object has been added to the namespace.
> - `NamingEvent.OBJECT_REMOVED`: An existing object has been removed from the namespace.
> - `NamingEvent.OBJECT_RENAMED`: An existing object has been given another name. Note that not all naming services support the generation of rename events. For example, an object being renamed might be manifested as an object removal followed by an object addition.
> The event type is obtained using `getType()`.

> #### Event Source

> An event source is the entity that fired the event and the object with which the listener has registered. It is an instance of `EventContext` or `EventDirContext`. See the Listener Registration section for more information about these two interfaces.

> The event source is obtained by using `getEventContext()` or `java.util.EventObject.getSource()`. These methods differ only in that `getEventContext()` returns the result as an `EventContext` whereas `getSource()` returns the result as a `java.lang.Object`.

> You can use the event source to obtain more information about the object or objects reachable from it. If you do use this method, you must synchronize access to it. This is because implementations of `Context` are not guaranteed to be thread-safe (and `EventContext` is a subinterface of `Context`).

> Here is some listener code that uses the event source.

> >     Attributes attrs;

> >     // Get the event source
> >     EventContext ctx = evt.getEventContext();

> >     // Get the name of the object that changed
> >     // Should really check for null binding first.
> >     String which = evt.getNewBinding().getName();

> >     // Lock the event source
> >     synchronized(ctx) {
> >         attrs = ctx.getAttributes(which, new String[]{"objectclass"});
> >     }
> >     // Do something useful with attrs

> #### Other Information

> A `NamingEvent` contains, in addition to the event's type and source, the old and new bindings of the object that caused the event, as well as any additional information. You use `getNewBinding()` to obtain a `Binding` instance that describes the state of the object after the event occurred. The `Binding` contains the name of the object, the object itself, and its attributes. Any and all of this data might be missing if the server or service provider cannot provide it.

> You use `getOldBinding()` to get similar information about the object before the event occurred.

> Note that the name in the old and new bindings is relative to the event source. For example, suppose that your program uses the following code to register a listener.

> >     EventContext ctx = (EventContext)
> >         (new InitialContext(env).lookup("ou=People"));

> >     // Create the listener
> >     NamingListener listener = new SampleNCListener("nc1");

> >     // Register the listener for namespace change events
> >     ctx.addNamingListener("ou=Objects,cn=John Smith",
> >         EventContext.ONELEVEL_SCOPE, listener);

> When the object `"cn=String"` is added underneath `"ou=Objects"`, the name in the binding of the `NamingEvent` will have the name `"cn=String, ou=Objects, cn=John Smith"`.

> In addition, you can use `getChangeInfo()` to obtain any additional change information that the server or service provider has supplied. For example, the server might send an identifier that identifies the change.

| Event Notification