| J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <!-- |
| 5 | Copyright 1999-2006 Sun Microsystems, Inc. All Rights Reserved. |
| 6 | DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| 7 | |
| 8 | This code is free software; you can redistribute it and/or modify it |
| 9 | under the terms of the GNU General Public License version 2 only, as |
| 10 | published by the Free Software Foundation. Sun designates this |
| 11 | particular file as subject to the "Classpath" exception as provided |
| 12 | by Sun in the LICENSE file that accompanied this code. |
| 13 | |
| 14 | This code is distributed in the hope that it will be useful, but WITHOUT |
| 15 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| 16 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| 17 | version 2 for more details (a copy is included in the LICENSE file that |
| 18 | accompanied this code). |
| 19 | |
| 20 | You should have received a copy of the GNU General Public License version |
| 21 | 2 along with this work; if not, write to the Free Software Foundation, |
| 22 | Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| 23 | |
| 24 | Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 25 | CA 95054 USA or visit www.sun.com if you need additional information or |
| 26 | have any questions. |
| 27 | --> |
| 28 | </head> |
| 29 | <body bgcolor="white"> |
| 30 | |
| 31 | Provides support for event notification when accessing naming and |
| 32 | directory services. |
| 33 | |
| 34 | <p> |
| 35 | This package defines the event notification operations of the Java Naming |
| 36 | and Directory Interface<font size=-2><sup>TM</sup></font> (JNDI). |
| 37 | JNDI provides naming and directory functionality to applications |
| 38 | written in the Java programming language. It is designed to be |
| 39 | independent of any specific naming or directory service |
| 40 | implementation. Thus a variety of services--new, emerging, and |
| 41 | already deployed ones--can be accessed in a common way. |
| 42 | |
| 43 | <h4>Naming Events</h4> |
| 44 | <p> |
| 45 | This package defines a <tt>NamingEvent</tt> class to represent an event |
| 46 | that is generated by a naming/directory service. |
| 47 | It also defines subinterfaces of <tt>Context</tt> and <tt>DirContext</tt>, |
| 48 | called <tt>EventContext</tt> and <tt>EventDirContext</tt>, |
| 49 | through which applications can register their interest in events |
| 50 | fired by the context. |
| 51 | <p> |
| 52 | <tt>NamingEvent</tt> represents an event that occurs in a |
| 53 | naming or directory service. There are two categories of naming events: |
| 54 | <ul> |
| 55 | <li>Those that affect the namespace (add/remove/rename an object) |
| 56 | <li>Those that affect the objects' contents. |
| 57 | </ul> |
| 58 | Each category of events is handled by a corresponding listener: |
| 59 | <tt>NamespaceChangeListener</tt>, <tt>ObjectChangeListener</tt>. |
| 60 | <p> |
| 61 | An application, for example, can register its interest in changes to |
| 62 | objects in a context as follows: |
| 63 | <blockquote> |
| 64 | <pre> |
| 65 | EventContext src = |
| 66 | (EventContext)(new InitialContext()).lookup("o=wiz,c=us"); |
| 67 | src.addNamingListener("ou=users", EventContext.ONELEVEL_SCOPE, |
| 68 | new ChangeHandler()); |
| 69 | ... |
| 70 | class ChangeHandler implements ObjectChangeListener { |
| 71 | public void objectChanged(NamingEvent evt) { |
| 72 | System.out.println(evt.getNewBinding()); |
| 73 | } |
| 74 | public void namingExceptionThrown(NamingExceptionEvent evt) { |
| 75 | System.out.println(evt.getException()); |
| 76 | } |
| 77 | } |
| 78 | </pre> |
| 79 | </blockquote> |
| 80 | |
| 81 | <a name=THREADING></a> |
| 82 | <h4>Threading Issues</h4> |
| 83 | |
| 84 | When an event is dispatched to a listener, the listener method (such |
| 85 | as <tt>objectChanged()</tt>) may be executed in a thread other than the |
| 86 | one in which the call to <tt>addNamingListener()</tt> was executed. |
| 87 | The choice of which thread to use is made by the service provider. |
| 88 | When an event is dispatched to multiple listeners, the service provider |
| 89 | may choose (and is generally encouraged) to execute the listener methods |
| 90 | concurrently in separate threads. |
| 91 | <p> |
| 92 | When a listener instance invokes <tt>NamingEvent.getEventContext()</tt>, |
| 93 | it must take into account the possibility that other threads will be |
| 94 | working with that context concurrently. Likewise, when a listener is |
| 95 | registered via <tt>addNamingListener()</tt>, the registering thread |
| 96 | must take into account the likely possibility that the service provider |
| 97 | will later invoke the listeners in newly-created threads. As <tt>Context</tt> |
| 98 | instances are not guaranteed to be thread-safe in general, all context |
| 99 | operations must be synchronized as needed. |
| 100 | |
| 101 | <h4>Exception Handling</h4> |
| 102 | |
| 103 | When a listener registers for events with a context, the context might |
| 104 | need to do some internal processing in order to collect information |
| 105 | required to generate the events. The context, for example, might need |
| 106 | to make a request to the server to register interest in changes |
| 107 | on the server that will eventually be translated into events. |
| 108 | If an exception occurs that prevents information about the events from |
| 109 | being collected, the listener will never be notified of the events. |
| 110 | When such an exception occurs, a <tt>NamingExceptionEvent</tt> is |
| 111 | fired to notify the listener. The listener's |
| 112 | <tt>namingExceptionThrown()</tt> method is invoked, as shown in the |
| 113 | sample code above, |
| 114 | and the listener is automatically deregistered. |
| 115 | <p> |
| 116 | |
| 117 | <h2>Package Specification</h2> |
| 118 | |
| 119 | |
| 120 | The JNDI API Specification and related documents can be found in the |
| 121 | <a href="../../../../technotes/guides/jndi/index.html">JNDI documentation</a>. |
| 122 | |
| 123 | @since 1.3 |
| 124 | |
| 125 | </body> |
| 126 | </html> |