EventDirContext.java revision 3261
3261N/A * Copyright (c) 1999, 2010, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * Contains methods for registering listeners to be notified 0N/A * of events fired when objects named in a directory context changes. 0N/A * The methods in this interface support identification of objects by 0N/A *<P>Using the search filter, it is possible to register interest in objects 0N/A * that do not exist at the time of registration but later come into existence and 0N/A * satisfy the filter. However, there might be limitations in the extent 0N/A * to which this can be supported by the service provider and underlying 0N/A * supported in this way, <tt>addNamingListener()</tt> throws an 0N/A * <tt>InvalidSearchFilterException</tt>. 0N/A * See <tt>EventContext</tt> for a description of event source 0N/A * that are also applicable to methods in this interface. 0N/A * for information on threading issues. 0N/A * A <tt>SearchControls</tt> or array object 0N/A * passed as a parameter to any method is owned by the caller. 0N/A * The service provider will not modify the object or keep a reference to it. 0N/A * @author Rosanna Lee 0N/A * @author Scott Seligman 0N/A * Adds a listener for receiving naming events fired 0N/A * when objects identified by the search filter <tt>filter</tt> at 0N/A * the object named by target are modified. 0N/A * The scope, returningObj flag, and returningAttributes flag from 0N/A * the search controls <tt>ctls</tt> are used to control the selection 0N/A * of objects that the listener is interested in, 0N/A * and determines what information is returned in the eventual 0N/A * <tt>NamingEvent</tt> object. Note that the requested 0N/A * information to be returned might not be present in the <tt>NamingEvent</tt> 0N/A * object if they are unavailable or could not be obtained by the 0N/A * service provider or service. 0N/A * @param target The nonnull name of the object resolved relative to this context. 0N/A * @param filter The nonnull string filter (see RFC2254). 0N/A * @param ctls The possibly null search controls. If null, the default 0N/A * search controls are used. 0N/A * @param l The nonnull listener. 0N/A * @exception NamingException If a problem was encountered while 0N/A * adding the listener. 0N/A * @see EventContext#removeNamingListener 0N/A * @see javax.naming.directory.DirContext#search(javax.naming.Name, java.lang.String, javax.naming.directory.SearchControls) 0N/A * Adds a listener for receiving naming events fired when 0N/A * objects identified by the search filter <tt>filter</tt> at the 0N/A * object named by the string target name are modified. 0N/A * See the overload that accepts a <tt>Name</tt> for details of 0N/A * how this method behaves. 0N/A * @param target The nonnull string name of the object resolved relative to this context. 0N/A * @param filter The nonnull string filter (see RFC2254). 0N/A * @param ctls The possibly null search controls. If null, the default 0N/A * search controls is used. 0N/A * @param l The nonnull listener. 0N/A * @exception NamingException If a problem was encountered while 0N/A * adding the listener. 0N/A * @see EventContext#removeNamingListener 0N/A * @see javax.naming.directory.DirContext#search(java.lang.String, java.lang.String, javax.naming.directory.SearchControls) 0N/A * Adds a listener for receiving naming events fired 0N/A * when objects identified by the search filter <tt>filter</tt> and 0N/A * filter arguments at the object named by the target are modified. 0N/A * The scope, returningObj flag, and returningAttributes flag from 0N/A * the search controls <tt>ctls</tt> are used to control the selection 0N/A * of objects that the listener is interested in, 0N/A * and determines what information is returned in the eventual 0N/A * <tt>NamingEvent</tt> object. Note that the requested 0N/A * information to be returned might not be present in the <tt>NamingEvent</tt> 0N/A * object if they are unavailable or could not be obtained by the 0N/A * service provider or service. 0N/A * @param target The nonnull name of the object resolved relative to this context. 0N/A * @param filter The nonnull string filter (see RFC2254). 0N/A * @param filterArgs The possibly null array of arguments for the filter. 0N/A * @param ctls The possibly null search controls. If null, the default 0N/A * search controls are used. 0N/A * @param l The nonnull listener. 0N/A * @exception NamingException If a problem was encountered while 0N/A * adding the listener. 0N/A * @see EventContext#removeNamingListener 0N/A * @see javax.naming.directory.DirContext#search(javax.naming.Name, java.lang.String, java.lang.Object[], javax.naming.directory.SearchControls) 0N/A * Adds a listener for receiving naming events fired when 0N/A * objects identified by the search filter <tt>filter</tt> 0N/A * and filter arguments at the 0N/A * object named by the string target name are modified. 0N/A * See the overload that accepts a <tt>Name</tt> for details of 0N/A * how this method behaves. 0N/A * @param target The nonnull string name of the object resolved relative to this context. 0N/A * @param filter The nonnull string filter (see RFC2254). 0N/A * @param filterArgs The possibly null array of arguments for the filter. 0N/A * @param ctls The possibly null search controls. If null, the default 0N/A * search controls is used. 0N/A * @param l The nonnull listener. 0N/A * @exception NamingException If a problem was encountered while 0N/A * adding the listener. 0N/A * @see EventContext#removeNamingListener 0N/A * @see javax.naming.directory.DirContext#search(java.lang.String, java.lang.String, java.lang.Object[], javax.naming.directory.SearchControls) */