1. /*

  2.  * @(#)EventContext.java	1.11 03/12/19

  3.  *

  4.  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package javax.naming.event;

  9. 

  10. import javax.naming.Name;

  11. import javax.naming.Context;

  12. import javax.naming.NamingException;

  13. 

  14. 

  15. /**

  16.  * Contains methods for registering/deregistering listeners to be notified of

  17.  * events fired when objects named in a context changes.

  18.  *<p>

  19.  *<h4>Target</h4>

  20.  * The name parameter in the <tt>addNamingListener()</tt> methods is referred

  21.  * to as the <em>target</em>. The target, along with the scope, identify

  22.  * the object(s) that the listener is interested in.

  23.  * It is possible to register interest in a target that does not exist, but

  24.  * there might be limitations in the extent to which this can be

  25.  * supported by the service provider and underlying protocol/service. 

  26.  *<p>

  27.  * If a service only supports registration for existing

  28.  * targets, an attempt to register for a nonexistent target

  29.  * results in a <tt>NameNotFoundException</tt> being thrown as early as possible,

  30.  * preferably at the time <tt>addNamingListener()</tt> is called, or if that is

  31.  * not possible, the listener will receive the exception through the 

  32.  * <tt>NamingExceptionEvent</tt>.

  33.  *<p>

  34.  * Also, for service providers that only support registration for existing

  35.  * targets, when the target that a listener has registered for is

  36.  * subsequently removed from the namespace, the listener is notified

  37.  * via a <tt>NamingExceptionEvent</tt> (containing a 

  38.  *<tt>NameNotFoundException</tt>).

  39.  *<p>

  40.  * An application can use the method <tt>targetMustExist()</tt> to check

  41.  * whether a <tt>EventContext</tt> supports registration

  42.  * of nonexistent targets.

  43.  *<p>

  44.  *<h4>Event Source</h4>

  45.  * The <tt>EventContext</tt> instance on which you invoke the 

  46.  * registration methods is the <em>event source</em> of the events that are

  47.  * (potentially) generated. 

  48.  * The source is <em>not necessarily</em> the object named by the target.

  49.  * Only when the target is the empty name is the object named by the target 

  50.  * the source. 

  51.  * In other words, the target,

  52.  * along with the scope parameter, are used to identify

  53.  * the object(s) that the listener is interested in, but the event source

  54.  * is the <tt>EventContext</tt> instance with which the listener 

  55.  * has registered.

  56.  *<p>

  57.  * For example, suppose a listener makes the following registration:

  58.  *<blockquote><pre>

  59.  *	NamespaceChangeListener listener = ...;

  60.  *	src.addNamingListener("x", SUBTREE_SCOPE, listener);

  61.  *</pre></blockquote>

  62.  * When an object named "x/y" is subsequently deleted, the corresponding

  63.  * <tt>NamingEvent</tt> (<tt>evt</tt>)  must contain:

  64.  *<blockquote><pre>

  65.  *	evt.getEventContext() == src

  66.  *	evt.getOldBinding().getName().equals("x/y")

  67.  *</pre></blockquote>

  68.  *<p>

  69.  * Furthermore, listener registration/deregistration is with 

  70.  * the <tt>EventContext</tt>

  71.  * <em>instance</em>, and not with the corresponding object in the namespace.

  72.  * If the program intends at some point to remove a listener, then it needs to 

  73.  * keep a reference to the <tt>EventContext</tt> instance on 

  74.  * which it invoked <tt>addNamingListener()</tt> (just as

  75.  * it needs to keep a reference to the listener in order to remove it

  76.  * later). It cannot expect to do a <tt>lookup()</tt> and get another instance of

  77.  * a <tt>EventContext</tt> on which to perform the deregistration.

  78.  *<h4>Lifetime of Registration</h4>

  79.  * A registered listener becomes deregistered when:

  80.  *<ul>

  81.  *<li>It is removed using <tt>removeNamingListener()</tt>.

  82.  *<li>An exception is thrown while collecting information about the events.

  83.  *  That is, when the listener receives a <tt>NamingExceptionEvent</tt>.

  84.  *<li><tt>Context.close()</tt> is invoked on the <tt>EventContext</tt> 

  85.  * instance with which it has registered.

  86.  </ul>

  87.  * Until that point, a <tt>EventContext</tt> instance that has outstanding

  88.  * listeners will continue to exist and be maintained by the service provider.

  89.  *

  90.  *<h4>Listener Implementations</h4>

  91.  * The registration/deregistration methods accept an instance of

  92.  * <tt>NamingListener</tt>. There are subinterfaces of <tt>NamingListener</tt>

  93.  * for different of event types of <tt>NamingEvent</tt>. 

  94.  * For example, the <tt>ObjectChangeListener</tt>

  95.  * interface is for the <tt>NamingEvent.OBJECT_CHANGED</tt> event type.

  96.  * To register interest in multiple event types, the listener implementation

  97.  * should implement multiple <tt>NamingListener</tt> subinterfaces and use a

  98.  * single invocation of <tt>addNamingListener()</tt>.

  99.  * In addition to reducing the number of method calls and possibly the code size

  100.  * of the listeners, this allows some service providers to optimize the

  101.  * registration.

  102.  *

  103.  *<h4>Threading Issues</h4>

  104.  *

  105.  * Like <tt>Context</tt> instances in general, instances of

  106.  * <tt>EventContext</tt> are not guaranteed to be thread-safe.

  107.  * Care must be taken when multiple threads are accessing the same

  108.  * <tt>EventContext</tt> concurrently.

  109.  * See the

  110.  * <a href=package-summary.html#THREADING>package description</a>

  111.  * for more information on threading issues.

  112.  * 

  113.  * @author Rosanna Lee

  114.  * @author Scott Seligman

  115.  * @version 1.11 03/12/19

  116.  * @since 1.3

  117.  */

  118. 

  119. public interface EventContext extends Context {

  120.     /**

  121.      * Constant for expressing interest in events concerning the object named 

  122.      * by the target.

  123.      *<p>

  124.      * The value of this constant is <tt>0</tt>.

  125.      */

  126.     public final static int OBJECT_SCOPE = 0;

  127. 

  128.     /**

  129.      * Constant for expressing interest in events concerning objects 

  130.      * in the context named by the target, 

  131.      * excluding the context named by the target.

  132.      *<p>

  133.      * The value of this constant is <tt>1</tt>.

  134.      */

  135.     public final static int ONELEVEL_SCOPE = 1;

  136. 

  137.     /**

  138.      * Constant for expressing interest in events concerning objects 

  139.      * in the subtree of the object named by the target, including the object

  140.      * named by the target.

  141.      *<p>

  142.      * The value of this constant is <tt>2</tt>.

  143.      */

  144.     public final static int SUBTREE_SCOPE = 2;

  145.     

  146. 

  147.     /**

  148.      * Adds a listener for receiving naming events fired

  149.      * when the object(s) identified by a target and scope changes.

  150.      *

  151.      * The event source of those events is this context. See the

  152.      * class description for a discussion on event source and target.

  153.      * See the descriptions of the constants <tt>OBJECT_SCOPE</tt>,

  154.      * <tt>ONELEVEL_SCOPE</tt>, and <tt>SUBTREE_SCOPE</tt> to see how

  155.      * <tt>scope</tt> affects the registration.

  156.      *<p>

  157.      * <tt>target</tt> needs to name a context only when <tt>scope</tt> is 

  158.      * <tt>ONELEVEL_SCOPE</tt>.

  159.      * <tt>target</tt> may name a non-context if <tt>scope</tt> is either 

  160.      * <tt>OBJECT_SCOPE</tt> or <tt>SUBTREE_SCOPE</tt>.  Using 

  161.      * <tt>SUBTREE_SCOPE</tt> for a non-context might be useful,

  162.      * for example, if the caller does not know in advance whether <tt>target</tt> 

  163.      * is a context and just wants to register interest in the (possibly

  164.      * degenerate subtree) rooted at <tt>target</tt>.

  165.      *<p>

  166.      * When the listener is notified of an event, the listener may

  167.      * in invoked in a thread other than the one in which

  168.      * <tt>addNamingListener()</tt> is executed.

  169.      * Care must be taken when multiple threads are accessing the same

  170.      * <tt>EventContext</tt> concurrently.

  171.      * See the

  172.      * <a href=package-summary.html#THREADING>package description</a>

  173.      * for more information on threading issues.

  174.      *

  175.      * @param target A nonnull name to be resolved relative to this context.

  176.      * @param scope One of <tt>OBJECT_SCOPE</tt>, <tt>ONELEVEL_SCOPE</tt>, or

  177.      * <tt>SUBTREE_SCOPE</tt>.

  178.      * @param l  The nonnull listener.

  179.      * @exception NamingException If a problem was encountered while

  180.      * adding the listener.

  181.      * @see #removeNamingListener

  182.      */

  183.     void addNamingListener(Name target, int scope, NamingListener l) 

  184. 	throws NamingException;

  185. 

  186.     /**

  187.      * Adds a listener for receiving naming events fired

  188.      * when the object named by the string target name and scope changes.

  189.      *

  190.      * See the overload that accepts a <tt>Name</tt> for details.

  191.      *

  192.      * @param target The nonnull string name of the object resolved relative 

  193.      * to this context.

  194.      * @param scope One of <tt>OBJECT_SCOPE</tt>, <tt>ONELEVEL_SCOPE</tt>, or

  195.      * <tt>SUBTREE_SCOPE</tt>.

  196.      * @param l  The nonnull listener.

  197.      * @exception NamingException If a problem was encountered while

  198.      * adding the listener.

  199.      * @see #removeNamingListener

  200.      */

  201.     void addNamingListener(String target, int scope, NamingListener l) 

  202. 	throws NamingException;

  203. 

  204.     /**

  205.      * Removes a listener from receiving naming events fired

  206.      * by this <tt>EventContext</tt>.

  207.      * The listener may have registered more than once with this

  208.      * <tt>EventContext</tt>, perhaps with different target/scope arguments.

  209.      * After this method is invoked, the listener will no longer

  210.      * receive events with this <tt>EventContext</tt> instance 

  211.      * as the event source (except for those events already in the process of

  212.      * being dispatched).

  213.      * If the listener was not, or is no longer, registered with 

  214.      * this <tt>EventContext</tt> instance, this method does not do anything.

  215.      *

  216.      * @param l  The nonnull listener.

  217.      * @exception NamingException If a problem was encountered while

  218.      * removing the listener.

  219.      * @see #addNamingListener

  220.      */

  221.     void removeNamingListener(NamingListener l) throws NamingException;

  222. 

  223.     /**

  224.      * Determines whether a listener can register interest in a target

  225.      * that does not exist.

  226.      *

  227.      * @return true if the target must exist; false if the target need not exist.

  228.      * @exception NamingException If the context's behavior in this regard cannot

  229.      * be determined.

  230.      */

  231.     boolean targetMustExist() throws NamingException;

  232. }