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 a NamingEvent. An instance of this class contains information about the event, such as its type, its 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. For example, an event type could be "object added" or "object changed." Event types are categorized into those that affect the namespace (such as "object added") and those that do not (such as "object changed"). Here are the event types defined in the NamingEvent class:

• NamingEvent.OBJECT_CHANGED: An object's content has changed. For instance, 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 generating "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 the getType()method.

Event Source

An event source is the entity that fired the event and the object with which the listener has registered. An event source 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 the getEventContext()or java.util.EventObject.getSource() method. The only difference between these two methods is that getEventContext() returns the result as an EventContext so you don't need to cast the result.

You can use the event source to obtain more information about the object or objects reachable from it. It you do use this method, you must synchronize access to it 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 event source
EventContext ctx = evt.getEventContext();

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

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

Other Information

In addition to the event's type and source, a NamingEvent contains the old and new bindings of the object that caused the event and any additional information. You use getNewBinding() to obtain a Binding instance that describes the state of the object after the event has 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 has occurred.

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

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

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

// Register 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