1. /*

  2.  * @(#)EventDirContext.java	1.5 00/02/02

  3.  *

  4.  * Copyright 1999, 2000 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. import javax.naming.Name;

  13. import javax.naming.NamingException;

  14. import javax.naming.directory.DirContext;

  15. import javax.naming.directory.SearchControls;

  16. 

  17. /**

  18.  * Contains methods for registering listeners to be notified

  19.  * of events fired when objects named in a directory context changes.

  20.  *<p>

  21.  * The methods in this interface support identification of objects by 

  22.  * <A HREF="ftp://ftp.isi.edu/in-notes/rfc2254.txt">RFC 2254</a>

  23.  * search filters.

  24.  *

  25.  *<P>Using the search filter, it is possible to register interest in objects 

  26.  * that do not exist at the time of registration but later come into existence and

  27.  * satisfy the filter.  However, there might be limitations in the extent

  28.  * to which this can be supported by the service provider and underlying

  29.  * protocol/service.  If the caller submits a filter that cannot be

  30.  * supported in this way, <tt>addNamingListener()</tt> throws an

  31.  * <tt>InvalidSearchFilterException</tt>.

  32.  *<p>

  33.  * See <tt>EventContext</tt> for a description of event source

  34.  * and target, and information about listener registration/deregistration

  35.  * that are also applicable to methods in this interface.

  36.  * See the

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

  38.  * for information on threading issues.

  39.  *<p>

  40.  * A <tt>SearchControls</tt> or array object

  41.  * passed as a parameter to any method is owned by the caller.

  42.  * The service provider will not modify the object or keep a reference to it.

  43.  * 

  44.  * @author Rosanna Lee

  45.  * @author Scott Seligman

  46.  * @version 1.5 00/02/02

  47.  * @since 1.3

  48.  */

  49. 

  50. public interface EventDirContext extends EventContext, DirContext {

  51.     /**

  52.      * Adds a listener for receiving naming events fired

  53.      * when objects identified by the search filter <tt>filter</tt> at

  54.      * the object named by target are modified.

  55.      * <p>

  56.      * The scope, returningObj flag, and returningAttributes flag from

  57.      * the search controls <tt>ctls</tt> are used to control the selection

  58.      * of objects that the listener is interested in,

  59.      * and determines what information is returned in the eventual

  60.      * <tt>NamingEvent</tt> object. Note that the requested

  61.      * information to be returned might not be present in the <tt>NamingEvent</tt>

  62.      * object if they are unavailable or could not be obtained by the

  63.      * service provider or service.

  64.      *

  65.      * @param target The nonnull name of the object resolved relative to this context.

  66.      * @param filter The nonnull string filter (see RFC2254).

  67.      * @param ctls   The possibly null search controls. If null, the default

  68.      * 	      search controls are used.

  69.      * @param l  The nonnull listener.

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

  71.      * adding the listener.

  72.      * @see EventContext#removeNamingListener

  73.      * @see javax.naming.directory.DirContext#search(javax.naming.Name, java.lang.String, javax.naming.directory.SearchControls)

  74.      */

  75.     void addNamingListener(Name target, String filter, SearchControls ctls, 

  76. 	NamingListener l) throws NamingException;

  77. 

  78.     /**

  79.      * Adds a listener for receiving naming events fired when

  80.      * objects identified by the search filter <tt>filter</tt> at the

  81.      * object named by the string target name are modified.

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

  83.      * how this method behaves.

  84.      *

  85.      * @param target The nonnull string name of the object resolved relative to this context.

  86.      * @param filter The nonnull string filter (see RFC2254).

  87.      * @param ctls   The possibly null search controls. If null, the default

  88.      * 	      search controls is used.

  89.      * @param l  The nonnull listener.

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

  91.      * adding the listener.

  92.      * @see EventContext#removeNamingListener

  93.      * @see javax.naming.directory.DirContext#search(java.lang.String, java.lang.String, javax.naming.directory.SearchControls)

  94.      */

  95.     void addNamingListener(String target, String filter, SearchControls ctls, 

  96. 	NamingListener l) throws NamingException;

  97. 

  98.     /**

  99.      * Adds a listener for receiving naming events fired

  100.      * when objects identified by the search filter <tt>filter</tt> and

  101.      * filter arguments at the object named by the target are modified.

  102.      * The scope, returningObj flag, and returningAttributes flag from

  103.      * the search controls <tt>ctls</tt> are used to control the selection

  104.      * of objects that the listener is interested in,

  105.      * and determines what information is returned in the eventual

  106.      * <tt>NamingEvent</tt> object.  Note that the requested

  107.      * information to be returned might not be present in the <tt>NamingEvent</tt>

  108.      * object if they are unavailable or could not be obtained by the

  109.      * service provider or service.

  110.      *

  111.      * @param target The nonnull name of the object resolved relative to this context.

  112.      * @param filter The nonnull string filter (see RFC2254).

  113.      * @param filterArgs The possibly null array of arguments for the filter.

  114.      * @param ctls   The possibly null search controls. If null, the default

  115.      * 	      search controls are used.

  116.      * @param l  The nonnull listener.

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

  118.      * adding the listener.

  119.      * @see EventContext#removeNamingListener

  120.      * @see javax.naming.directory.DirContext#search(javax.naming.Name, java.lang.String, java.lang.Object[], javax.naming.directory.SearchControls)

  121.      */

  122.     void addNamingListener(Name target, String filter, Object[] filterArgs,

  123. 	SearchControls ctls, NamingListener l) throws NamingException;

  124. 

  125.     /**

  126.      * Adds a listener for receiving naming events fired when

  127.      * objects identified by the search filter <tt>filter</tt> 

  128.      * and filter arguments at the

  129.      * object named by the string target name are modified.

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

  131.      * how this method behaves.

  132.      *

  133.      * @param target The nonnull string name of the object resolved relative to this context.

  134.      * @param filter The nonnull string filter (see RFC2254).

  135.      * @param filterArgs The possibly null array of arguments for the filter.

  136.      * @param ctls   The possibly null search controls. If null, the default

  137.      * 	      search controls is used.

  138.      * @param l  The nonnull listener.

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

  140.      * adding the listener.

  141.      * @see EventContext#removeNamingListener

  142.      * @see javax.naming.directory.DirContext#search(java.lang.String, java.lang.String, java.lang.Object[], javax.naming.directory.SearchControls)      */

  143.     void addNamingListener(String target, String filter, Object[] filterArgs,

  144. 	SearchControls ctls, NamingListener l) throws NamingException;

  145. }