1583N/A<!
DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
1583N/ACopyright (c) 1999, 2006, Oracle and/or its affiliates. All rights reserved. 1583N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 1583N/AThis code is free software; you can redistribute it and/or modify it 1583N/Aunder the terms of the GNU General Public License version 2 only, as 1583N/Apublished by the Free Software Foundation. Oracle designates this 1583N/Aparticular file as subject to the "Classpath" exception as provided 1583N/Aby Oracle in the LICENSE file that accompanied this code. 1583N/AThis code is distributed in the hope that it will be useful, but WITHOUT 1583N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1583N/AFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1583N/Aversion 2 for more details (a copy is included in the LICENSE file that 1583N/AYou should have received a copy of the GNU General Public License version 1583N/A2 along with this work; if not, write to the Free Software Foundation, 1583N/AInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 1583N/APlease contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 1583N/AProvides support for event notification when accessing naming and
1583N/AThis package defines the event notification operations of the Java Naming
1583N/Aand Directory Interface<
font size=-
2><
sup>TM</
sup></
font> (JNDI).
1583N/AJNDI provides naming and directory functionality to applications
1583N/Awritten in the Java programming language. It is designed to be
1583N/Aindependent of any specific naming or directory service
1583N/Aimplementation. Thus a variety of services--new, emerging, and
1583N/Aalready deployed ones--can be accessed in a common way.
1583N/AThis package defines a <
tt>NamingEvent</
tt> class to represent an event
1583N/AIt also defines subinterfaces of <
tt>Context</
tt> and <
tt>DirContext</
tt>,
1583N/Acalled <
tt>EventContext</
tt> and <
tt>EventDirContext</
tt>,
1583N/Athrough which applications can register their interest in events
1583N/A<
tt>NamingEvent</
tt> represents an event that occurs in a
1583N/Anaming or directory service. There are two categories of naming events:
1583N/A<
li>Those that affect the objects' contents.
1583N/AEach category of events is handled by a corresponding listener:
1583N/A<
tt>NamespaceChangeListener</
tt>, <
tt>ObjectChangeListener</
tt>.
1583N/AAn application, for example, can register its interest in changes to
1583N/Aobjects in a context as follows:
1583N/A (EventContext)(new InitialContext()).lookup("o=wiz,c=us");
1583N/Aclass ChangeHandler implements ObjectChangeListener {
1583N/A public void objectChanged(NamingEvent evt) {
public void namingExceptionThrown(NamingExceptionEvent evt) {
<
h4>Threading Issues</
h4>
When an event is dispatched to a listener, the listener method (such
as <
tt>objectChanged()</
tt>) may be executed in a thread other than the
one in which the call to <
tt>addNamingListener()</
tt> 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.
it must take into account the possibility that other threads will be
working with that context concurrently. Likewise, when a listener is
registered via <
tt>addNamingListener()</
tt>, the registering thread
must take into account the likely possibility that the service provider
will later invoke the listeners in newly-created threads. As <
tt>Context</
tt>
instances are not guaranteed to be thread-safe in general, all context
operations must be synchronized as needed.
<
h4>Exception Handling</
h4>
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 <
tt>NamingExceptionEvent</
tt> is
fired to notify the listener. The listener's
<
tt>namingExceptionThrown()</
tt> method is invoked, as shown in the
and the listener is automatically deregistered.
<
h2>Package Specification</
h2>
The JNDI API Specification and related documents can be found in the