--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/java.naming/share/classes/javax/naming/event/package.html Sun Aug 17 15:54:13 2014 +0100
@@ -0,0 +1,125 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<head>
+<!--
+Copyright (c) 1999, 2006, Oracle and/or its affiliates. All rights reserved.
+DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+
+This code is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License version 2 only, as
+published by the Free Software Foundation. Oracle designates this
+particular file as subject to the "Classpath" exception as provided
+by Oracle in the LICENSE file that accompanied this code.
+
+This code is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+version 2 for more details (a copy is included in the LICENSE file that
+accompanied this code).
+
+You should have received a copy of the GNU General Public License version
+2 along with this work; if not, write to the Free Software Foundation,
+Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+or visit www.oracle.com if you need additional information or have any
+questions.
+-->
+</head>
+<body bgcolor="white">
+
+Provides support for event notification when accessing naming and
+directory services.
+
+<p>
+This package defines the event notification operations of the Java Naming
+and Directory Interface<font size=-2><sup>TM</sup></font> (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.
+
+<h4>Naming Events</h4>
+<p>
+This package defines a <tt>NamingEvent</tt> class to represent an event
+that is generated by a naming/directory service.
+It also defines subinterfaces of <tt>Context</tt> and <tt>DirContext</tt>,
+called <tt>EventContext</tt> and <tt>EventDirContext</tt>,
+through which applications can register their interest in events
+fired by the context.
+<p>
+<tt>NamingEvent</tt> represents an event that occurs in a
+naming or directory service. There are two categories of naming events:
+<ul>
+<li>Those that affect the namespace (add/remove/rename an object)
+<li>Those that affect the objects' contents.
+</ul>
+Each category of events is handled by a corresponding listener:
+<tt>NamespaceChangeListener</tt>, <tt>ObjectChangeListener</tt>.
+<p>
+An application, for example, can register its interest in changes to
+objects in a context as follows:
+<blockquote>
+<pre>
+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());
+ }
+}
+</pre>
+</blockquote>
+
+<a name=THREADING></a>
+<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.
+<p>
+When a listener instance invokes <tt>NamingEvent.getEventContext()</tt>,
+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
+sample code above,
+and the listener is automatically deregistered.
+
+<h2>Package Specification</h2>
+
+
+The JNDI API Specification and related documents can be found in the
+<a href="../../../../technotes/guides/jndi/index.html">JNDI documentation</a>.
+
+@since 1.3
+
+</body>
+</html>