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