EventDirContext


1   /*
2    * @(#)EventDirContext.java 1.8 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   import javax.naming.Name  ;
10  import javax.naming.NamingException  ;
11  import javax.naming.directory.DirContext  ;
12  import javax.naming.directory.SearchControls  ;
13  
14  /**
15   * Contains methods for registering listeners to be notified
16   * of events fired when objects named in a directory context changes.
17   *<p>
18   * The methods in this interface support identification of objects by 
19   * <A HREF="ftp://ftp.isi.edu/in-notes/rfc2254.txt">RFC 2254</a>
20   * search filters.
21   *
22   *<P>Using the search filter, it is possible to register interest in objects 
23   * that do not exist at the time of registration but later come into existence and
24   * satisfy the filter.  However, there might be limitations in the extent
25   * to which this can be supported by the service provider and underlying
26   * protocol/service.  If the caller submits a filter that cannot be
27   * supported in this way, <tt>addNamingListener()</tt> throws an
28   * <tt>InvalidSearchFilterException</tt>.
29   *<p>
30   * See <tt>EventContext</tt> for a description of event source
31   * and target, and information about listener registration/deregistration
32   * that are also applicable to methods in this interface.
33   * See the
34   * <a HREF=package-summary.html#THREADING>package description</a>
35   * for information on threading issues.
36   *<p>
37   * A <tt>SearchControls</tt> or array object
38   * passed as a parameter to any method is owned by the caller.
39   * The service provider will not modify the object or keep a reference to it.
40   * 
41   * @author Rosanna Lee
42   * @author Scott Seligman
43   * @version 1.8 03/12/19
44   * @since 1.3
45   */
46  
47  public interface EventDirContext extends EventContext  , DirContext   {
48      /**
49       * Adds a listener for receiving naming events fired
50       * when objects identified by the search filter <tt>filter</tt> at
51       * the object named by target are modified.
52       * <p>
53       * The scope, returningObj flag, and returningAttributes flag from
54       * the search controls <tt>ctls</tt> are used to control the selection
55       * of objects that the listener is interested in,
56       * and determines what information is returned in the eventual
57       * <tt>NamingEvent</tt> object. Note that the requested
58       * information to be returned might not be present in the <tt>NamingEvent</tt>
59       * object if they are unavailable or could not be obtained by the
60       * service provider or service.
61       *
62       * @param target The nonnull name of the object resolved relative to this context.
63       * @param filter The nonnull string filter (see RFC2254).
64       * @param ctls   The possibly null search controls. If null, the default
65       *        search controls are used.
66       * @param l  The nonnull listener.
67       * @exception NamingException If a problem was encountered while
68       * adding the listener.
69       * @see EventContext#removeNamingListener
70       * @see javax.naming.directory.DirContext#search(javax.naming.Name, java.lang.String, javax.naming.directory.SearchControls)
71       */
72      void addNamingListener(Name   target, String   filter, SearchControls   ctls, 
73      NamingListener   l) throws NamingException  ;
74  
75      /**
76       * Adds a listener for receiving naming events fired when
77       * objects identified by the search filter <tt>filter</tt> at the
78       * object named by the string target name are modified.
79       * See the overload that accepts a <tt>Name</tt> for details of
80       * how this method behaves.
81       *
82       * @param target The nonnull string name of the object resolved relative to this context.
83       * @param filter The nonnull string filter (see RFC2254).
84       * @param ctls   The possibly null search controls. If null, the default
85       *        search controls is used.
86       * @param l  The nonnull listener.
87       * @exception NamingException If a problem was encountered while
88       * adding the listener.
89       * @see EventContext#removeNamingListener
90       * @see javax.naming.directory.DirContext#search(java.lang.String, java.lang.String, javax.naming.directory.SearchControls)
91       */
92      void addNamingListener(String   target, String   filter, SearchControls   ctls, 
93      NamingListener   l) throws NamingException  ;
94  
95      /**
96       * Adds a listener for receiving naming events fired
97       * when objects identified by the search filter <tt>filter</tt> and
98       * filter arguments at the object named by the target are modified.
99       * The scope, returningObj flag, and returningAttributes flag from
100      * the search controls <tt>ctls</tt> are used to control the selection
101      * of objects that the listener is interested in,
102      * and determines what information is returned in the eventual
103      * <tt>NamingEvent</tt> object.  Note that the requested
104      * information to be returned might not be present in the <tt>NamingEvent</tt>
105      * object if they are unavailable or could not be obtained by the
106      * service provider or service.
107      *
108      * @param target The nonnull name of the object resolved relative to this context.
109      * @param filter The nonnull string filter (see RFC2254).
110      * @param filterArgs The possibly null array of arguments for the filter.
111      * @param ctls   The possibly null search controls. If null, the default
112      *        search controls are used.
113      * @param l  The nonnull listener.
114      * @exception NamingException If a problem was encountered while
115      * adding the listener.
116      * @see EventContext#removeNamingListener
117      * @see javax.naming.directory.DirContext#search(javax.naming.Name, java.lang.String, java.lang.Object[], javax.naming.directory.SearchControls)
118      */
119     void addNamingListener(Name   target, String   filter, Object  [] filterArgs,
120     SearchControls   ctls, NamingListener   l) throws NamingException  ;
121 
122     /**
123      * Adds a listener for receiving naming events fired when
124      * objects identified by the search filter <tt>filter</tt> 
125      * and filter arguments at the
126      * object named by the string target name are modified.
127      * See the overload that accepts a <tt>Name</tt> for details of
128      * how this method behaves.
129      *
130      * @param target The nonnull string name of the object resolved relative to this context.
131      * @param filter The nonnull string filter (see RFC2254).
132      * @param filterArgs The possibly null array of arguments for the filter.
133      * @param ctls   The possibly null search controls. If null, the default
134      *        search controls is used.
135      * @param l  The nonnull listener.
136      * @exception NamingException If a problem was encountered while
137      * adding the listener.
138      * @see EventContext#removeNamingListener
139      * @see javax.naming.directory.DirContext#search(java.lang.String, java.lang.String, java.lang.Object[], javax.naming.directory.SearchControls)      */
140     void addNamingListener(String   target, String   filter, Object  [] filterArgs,
141     SearchControls   ctls, NamingListener   l) throws NamingException  ;
142 }
143
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags