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 a NamingEvent(in the API reference documentation). 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: The event type is obtained using the getType()(in the API reference documentation)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(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 the getEventContext()(in the API reference documentation)or java.util.EventObject.getSource()(in the API reference documentation) 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(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 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()(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 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()(in the API reference documentation)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()(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