0N/A<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
0N/A<html>
0N/A<head>
0N/A<!--
2362N/ACopyright (c) 1999, 2006, Oracle and/or its affiliates. All rights reserved.
0N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0N/A
0N/AThis code is free software; you can redistribute it and/or modify it
0N/Aunder the terms of the GNU General Public License version 2 only, as
2362N/Apublished by the Free Software Foundation. Oracle designates this
0N/Aparticular file as subject to the "Classpath" exception as provided
2362N/Aby Oracle in the LICENSE file that accompanied this code.
0N/A
0N/AThis code is distributed in the hope that it will be useful, but WITHOUT
0N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0N/AFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0N/Aversion 2 for more details (a copy is included in the LICENSE file that
0N/Aaccompanied this code).
0N/A
0N/AYou should have received a copy of the GNU General Public License version
0N/A2 along with this work; if not, write to the Free Software Foundation,
0N/AInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0N/A
2365N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
2365N/Aor visit www.oracle.com if you need additional information or have any
2365N/Aquestions.
0N/A-->
0N/A</head>
0N/A<body bgcolor="white">
0N/A
0N/AProvides support for event notification when accessing naming and
0N/Adirectory services.
0N/A
0N/A<p>
0N/AThis package defines the event notification operations of the Java Naming
0N/Aand Directory Interface<font size=-2><sup>TM</sup></font> (JNDI). &nbsp;
0N/AJNDI provides naming and directory functionality to applications
0N/Awritten in the Java programming language. It is designed to be
0N/Aindependent of any specific naming or directory service
0N/Aimplementation. Thus a variety of services--new, emerging, and
0N/Aalready deployed ones--can be accessed in a common way.
0N/A
0N/A<h4>Naming Events</h4>
0N/A<p>
0N/AThis package defines a <tt>NamingEvent</tt> class to represent an event
0N/Athat is generated by a naming/directory service.
0N/AIt also defines subinterfaces of <tt>Context</tt> and <tt>DirContext</tt>,
0N/Acalled <tt>EventContext</tt> and <tt>EventDirContext</tt>,
0N/Athrough which applications can register their interest in events
0N/Afired by the context.
0N/A<p>
0N/A<tt>NamingEvent</tt> represents an event that occurs in a
0N/Anaming or directory service. There are two categories of naming events:
0N/A<ul>
0N/A<li>Those that affect the namespace (add/remove/rename an object)
0N/A<li>Those that affect the objects' contents.
0N/A</ul>
0N/AEach category of events is handled by a corresponding listener:
0N/A<tt>NamespaceChangeListener</tt>, <tt>ObjectChangeListener</tt>.
0N/A<p>
0N/AAn application, for example, can register its interest in changes to
0N/Aobjects in a context as follows:
0N/A<blockquote>
0N/A<pre>
0N/AEventContext src =
0N/A (EventContext)(new InitialContext()).lookup("o=wiz,c=us");
0N/Asrc.addNamingListener("ou=users", EventContext.ONELEVEL_SCOPE,
0N/A new ChangeHandler());
0N/A...
0N/Aclass ChangeHandler implements ObjectChangeListener {
0N/A public void objectChanged(NamingEvent evt) {
0N/A System.out.println(evt.getNewBinding());
0N/A }
0N/A public void namingExceptionThrown(NamingExceptionEvent evt) {
0N/A System.out.println(evt.getException());
0N/A }
0N/A}
0N/A</pre>
0N/A</blockquote>
0N/A
0N/A<a name=THREADING></a>
0N/A<h4>Threading Issues</h4>
0N/A
0N/AWhen an event is dispatched to a listener, the listener method (such
0N/Aas <tt>objectChanged()</tt>) may be executed in a thread other than the
0N/Aone in which the call to <tt>addNamingListener()</tt> was executed.
0N/AThe choice of which thread to use is made by the service provider.
0N/AWhen an event is dispatched to multiple listeners, the service provider
0N/Amay choose (and is generally encouraged) to execute the listener methods
0N/Aconcurrently in separate threads.
0N/A<p>
0N/AWhen a listener instance invokes <tt>NamingEvent.getEventContext()</tt>,
0N/Ait must take into account the possibility that other threads will be
0N/Aworking with that context concurrently. Likewise, when a listener is
0N/Aregistered via <tt>addNamingListener()</tt>, the registering thread
0N/Amust take into account the likely possibility that the service provider
0N/Awill later invoke the listeners in newly-created threads. As <tt>Context</tt>
0N/Ainstances are not guaranteed to be thread-safe in general, all context
0N/Aoperations must be synchronized as needed.
0N/A
0N/A<h4>Exception Handling</h4>
0N/A
0N/AWhen a listener registers for events with a context, the context might
0N/Aneed to do some internal processing in order to collect information
0N/Arequired to generate the events. The context, for example, might need
0N/Ato make a request to the server to register interest in changes
0N/Aon the server that will eventually be translated into events.
0N/AIf an exception occurs that prevents information about the events from
0N/Abeing collected, the listener will never be notified of the events.
0N/AWhen such an exception occurs, a <tt>NamingExceptionEvent</tt> is
0N/Afired to notify the listener. The listener's
0N/A<tt>namingExceptionThrown()</tt> method is invoked, as shown in the
0N/Asample code above,
0N/Aand the listener is automatically deregistered.
0N/A<p>
0N/A
0N/A<h2>Package Specification</h2>
0N/A
0N/A
0N/AThe JNDI API Specification and related documents can be found in the
0N/A<a href="/technotes/guides/jndi/index.html">JNDI documentation</a>.
0N/A
0N/A@since 1.3
0N/A
0N/A</body>
0N/A</html>