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