|
Provides support for event notification when accessing naming and
directory services.
This package defines the event notification operations of the Java Naming
and Directory InterfaceTM (JNDI).
JNDI provides naming and directory functionality to applications
written in the Java programming language. It is designed to be
independent of any specific naming or directory service
implementation. Thus a variety of services--new, emerging, and
already deployed ones--can be accessed in a common way.
Naming Events
This package defines a NamingEvent class to represent an event
that is generated by a naming/directory service.
It also defines subinterfaces of Context and DirContext,
called EventContext and EventDirContext,
through which applications can register their interest in events
fired by the context.
NamingEvent represents an event that occurs in a
naming or directory service. There are two categories of naming events:
- Those that affect the namespace (add/remove/rename an object)
- Those that affect the objects' contents.
Each category of events is handled by a corresponding listener:
NamespaceChangeListener, ObjectChangeListener.
An application, for example, can register its interest in changes to
objects in a context as follows:
EventContext src =
(EventContext)(new InitialContext()).lookup("o=wiz,c=us");
src.addNamingListener("ou=users", EventContext.ONELEVEL_SCOPE,
new ChangeHandler());
...
class ChangeHandler implements ObjectChangeListener {
public void objectChanged(NamingEvent evt) {
System.out.println(evt.getNewBinding());
}
public void namingExceptionThrown(NamingExceptionEvent evt) {
System.out.println(evt.getException());
}
}
Threading Issues
When an event is dispatched to a listener, the listener method (such
as objectChanged()) may be executed in a thread other than the
one in which the call to addNamingListener() was executed.
The choice of which thread to use is made by the service provider.
When an event is dispatched to multiple listeners, the service provider
may choose (and is generally encouraged) to execute the listener methods
concurrently in separate threads.
When a listener instance invokes NamingEvent.getEventContext(),
it must take into account the possibility that other threads will be
working with that context concurrently. Likewise, when a listener is
registered via addNamingListener(), the registering thread
must take into account the likely possibility that the service provider
will later invoke the listeners in newly-created threads. As Context
instances are not guaranteed to be thread-safe in general, all context
operations must be synchronized as needed.
Exception Handling
When a listener registers for events with a context, the context might
need to do some internal processing in order to collect information
required to generate the events. The context, for example, might need
to make a request to the server to register interest in changes
on the server that will eventually be translated into events.
If an exception occurs that prevents information about the events from
being collected, the listener will never be notified of the events.
When such an exception occurs, a NamingExceptionEvent is
fired to notify the listener. The listener's
namingExceptionThrown() method is invoked, as shown in the
sample code above,
and the listener is automatically deregistered.
Package Specification
The JNDI API Specification and related documents can be found in the
JNDI documentation.
@since 1.3
|