1. /*

  2.  * @(#)EventContext.java	1.9 01/02/09

  3.  *

  4.  * Copyright 1999-2001 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. 

  11. package javax.naming.event;

  12. 

  13. import javax.naming.Name;

  14. import javax.naming.Context;

  15. import javax.naming.NamingException;

  16. 

  17. 

  18. /**

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

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

  21.  *<p>

  22.  *<h4>Target</h4>

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

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

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

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

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

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

  29.  *<p>

  30.  * If a service only supports registration for existing

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

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

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

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

  35.  * <tt>NamingExceptionEvent</tt>.

  36.  *<p>

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

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

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

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

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

  42.  *<p>

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

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

  45.  * of nonexistent targets.

  46.  *<p>

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

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

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

  50.  * (potentially) generated. 

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

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

  53.  * the source. 

  54.  * In other words, the target,

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

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

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

  58.  * has registered.

  59.  *<p>

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

  61.  *<blockquote><pre>

  62.  *	NamespaceChangeListener listener = ...;

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

  64.  *</pre></blockquote>

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

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

  67.  *<blockquote><pre>

  68.  *	evt.getEventContext() == src

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

  70.  *</pre></blockquote>

  71.  *<p>

  72.  * Furthermore, listener registration/deregistration is with 

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

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

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

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

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

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

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

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

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

  82.  * A registered listener becomes deregistered when:

  83.  *<ul>

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

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

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

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

  88.  * instance with which it has registered.

  89.  </ul>

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

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

  92.  *

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

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

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

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

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

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

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

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

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

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

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

  104.  * registration.

  105.  *

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

  107.  *

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

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

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

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

  112.  * See the

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

  114.  * for more information on threading issues.

  115.  * 

  116.  * @author Rosanna Lee

  117.  * @author Scott Seligman

  118.  * @version 1.9 01/02/09

  119.  * @since 1.3

  120.  */

  121. 

  122. public interface EventContext extends Context {

  123.     /**

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

  125.      * by the target.

  126.      *<p>

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

  128.      */

  129.     public final static int OBJECT_SCOPE = 0;

  130. 

  131.     /**

  132.      * Constant for expressing interest in events concerning objects 

  133.      * in the context named by the target, 

  134.      * excluding the context named by the target.

  135.      *<p>

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

  137.      */

  138.     public final static int ONELEVEL_SCOPE = 1;

  139. 

  140.     /**

  141.      * Constant for expressing interest in events concerning objects 

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

  143.      * named by the target.

  144.      *<p>

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

  146.      */

  147.     public final static int SUBTREE_SCOPE = 2;

  148.     

  149. 

  150.     /**

  151.      * Adds a listener for receiving naming events fired

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

  153.      *

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

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

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

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

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

  159.      *<p>

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

  161.      * <tt>ONELEVEL_SCOPE</tt>.

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

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

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

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

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

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

  168.      *<p>

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

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

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

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

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

  174.      * See the

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

  176.      * for more information on threading issues.

  177.      *

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

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

  180.      * <tt>SUBTREE_SCOPE</tt>.

  181.      * @param l  The nonnull listener.

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

  183.      * adding the listener.

  184.      * @see #removeNamingListener

  185.      */

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

  187. 	throws NamingException;

  188. 

  189.     /**

  190.      * Adds a listener for receiving naming events fired

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

  192.      *

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

  194.      *

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

  196.      * to this context.

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

  198.      * <tt>SUBTREE_SCOPE</tt>.

  199.      * @param l  The nonnull listener.

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

  201.      * adding the listener.

  202.      * @see #removeNamingListener

  203.      */

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

  205. 	throws NamingException;

  206. 

  207.     /**

  208.      * Removes a listener from receiving naming events fired

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

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

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

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

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

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

  215.      * being dispatched).

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

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

  218.      *

  219.      * @param l  The nonnull listener.

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

  221.      * removing the listener.

  222.      * @see #addNamingListener

  223.      */

  224.     void removeNamingListener(NamingListener l) throws NamingException;

  225. 

  226.     /**

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

  228.      * that does not exist.

  229.      *

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

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

  232.      * be determined.

  233.      */

  234.     boolean targetMustExist() throws NamingException;

  235. }