ojluni/src/main/java/javax/naming/event/package.html - platform/libcore.git - Git at Google

 <!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). &nbsp;
 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.
 <p>

 <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>
	<!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.
	<p>

	<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>