Previous | Next | Trail Map | Beyond the Basics | Event Notification

Naming Events

After a NamespaceChangeListener(in the API reference documentation) or ObjectChangeListener(in the API reference documentation) has been registered with an event source, it will get event notifications in the form of NamingEvents(in the API reference documentation). 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. The event type is obtained using getType()(in the API reference documentation).

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(in the API reference documentation) or EventDirContext(in the API reference documentation). See the Listener Registration section for more information about these two interfaces.

The event source is obtained by using getEventContext()(in the API reference documentation) or java.util.EventObject.getSource()(in the API reference documentation). 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(in the API reference documentation) 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()(in the API reference documentation) to obtain a Binding(in the API reference documentation) 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()(in the API reference documentation) 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()(in the API reference documentation) 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.

Previous | Next | Trail Map | Beyond the Basics | Event Notification