| <!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™ (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 <code>NamingEvent</code> class to represent an event |
| that is generated by a naming/directory service. |
| It also defines subinterfaces of <code>Context</code> and <code>DirContext</code>, |
| called <code>EventContext</code> and <code>EventDirContext</code>, |
| through which applications can register their interest in events |
| fired by the context. |
| <p> |
| <code>NamingEvent</code> 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: |
| <code>NamespaceChangeListener</code>, <code>ObjectChangeListener</code>. |
| <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 <code>objectChanged()</code>) may be executed in a thread other than the |
| one in which the call to <code>addNamingListener()</code> 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 <code>NamingEvent.getEventContext()</code>, |
| it must take into account the possibility that other threads will be |
| working with that context concurrently. Likewise, when a listener is |
| registered via <code>addNamingListener()</code>, the registering thread |
| must take into account the likely possibility that the service provider |
| will later invoke the listeners in newly-created threads. As <code>Context</code> |
| 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 <code>NamingExceptionEvent</code> is |
| fired to notify the listener. The listener's |
| <code>namingExceptionThrown()</code> 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> |