001 /*
002 * Copyright 1999-2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.naming.event;
027
028 import javax.naming.Name;
029 import javax.naming.NamingException;
030 import javax.naming.directory.DirContext;
031 import javax.naming.directory.SearchControls;
032
033 /**
034 * Contains methods for registering listeners to be notified
035 * of events fired when objects named in a directory context changes.
036 *<p>
037 * The methods in this interface support identification of objects by
038 * <A HREF="ftp://ftp.isi.edu/in-notes/rfc2254.txt">RFC 2254</a>
039 * search filters.
040 *
041 *<P>Using the search filter, it is possible to register interest in objects
042 * that do not exist at the time of registration but later come into existence and
043 * satisfy the filter. However, there might be limitations in the extent
044 * to which this can be supported by the service provider and underlying
045 * protocol/service. If the caller submits a filter that cannot be
046 * supported in this way, <tt>addNamingListener()</tt> throws an
047 * <tt>InvalidSearchFilterException</tt>.
048 *<p>
049 * See <tt>EventContext</tt> for a description of event source
050 * and target, and information about listener registration/deregistration
051 * that are also applicable to methods in this interface.
052 * See the
053 * <a href=package-summary.html#THREADING>package description</a>
054 * for information on threading issues.
055 *<p>
056 * A <tt>SearchControls</tt> or array object
057 * passed as a parameter to any method is owned by the caller.
058 * The service provider will not modify the object or keep a reference to it.
059 *
060 * @author Rosanna Lee
061 * @author Scott Seligman
062 * @version 1.8 03/12/19
063 * @since 1.3
064 */
065
066 public interface EventDirContext extends EventContext, DirContext {
067 /**
068 * Adds a listener for receiving naming events fired
069 * when objects identified by the search filter <tt>filter</tt> at
070 * the object named by target are modified.
071 * <p>
072 * The scope, returningObj flag, and returningAttributes flag from
073 * the search controls <tt>ctls</tt> are used to control the selection
074 * of objects that the listener is interested in,
075 * and determines what information is returned in the eventual
076 * <tt>NamingEvent</tt> object. Note that the requested
077 * information to be returned might not be present in the <tt>NamingEvent</tt>
078 * object if they are unavailable or could not be obtained by the
079 * service provider or service.
080 *
081 * @param target The nonnull name of the object resolved relative to this context.
082 * @param filter The nonnull string filter (see RFC2254).
083 * @param ctls The possibly null search controls. If null, the default
084 * search controls are used.
085 * @param l The nonnull listener.
086 * @exception NamingException If a problem was encountered while
087 * adding the listener.
088 * @see EventContext#removeNamingListener
089 * @see javax.naming.directory.DirContext#search(javax.naming.Name, java.lang.String, javax.naming.directory.SearchControls)
090 */
091 void addNamingListener(Name target, String filter,
092 SearchControls ctls, NamingListener l)
093 throws NamingException;
094
095 /**
096 * Adds a listener for receiving naming events fired when
097 * objects identified by the search filter <tt>filter</tt> at the
098 * object named by the string target name are modified.
099 * See the overload that accepts a <tt>Name</tt> for details of
100 * how this method behaves.
101 *
102 * @param target The nonnull string name of the object resolved relative to this context.
103 * @param filter The nonnull string filter (see RFC2254).
104 * @param ctls The possibly null search controls. If null, the default
105 * search controls is used.
106 * @param l The nonnull listener.
107 * @exception NamingException If a problem was encountered while
108 * adding the listener.
109 * @see EventContext#removeNamingListener
110 * @see javax.naming.directory.DirContext#search(java.lang.String, java.lang.String, javax.naming.directory.SearchControls)
111 */
112 void addNamingListener(String target, String filter,
113 SearchControls ctls, NamingListener l)
114 throws NamingException;
115
116 /**
117 * Adds a listener for receiving naming events fired
118 * when objects identified by the search filter <tt>filter</tt> and
119 * filter arguments at the object named by the target are modified.
120 * The scope, returningObj flag, and returningAttributes flag from
121 * the search controls <tt>ctls</tt> are used to control the selection
122 * of objects that the listener is interested in,
123 * and determines what information is returned in the eventual
124 * <tt>NamingEvent</tt> object. Note that the requested
125 * information to be returned might not be present in the <tt>NamingEvent</tt>
126 * object if they are unavailable or could not be obtained by the
127 * service provider or service.
128 *
129 * @param target The nonnull name of the object resolved relative to this context.
130 * @param filter The nonnull string filter (see RFC2254).
131 * @param filterArgs The possibly null array of arguments for the filter.
132 * @param ctls The possibly null search controls. If null, the default
133 * search controls are used.
134 * @param l The nonnull listener.
135 * @exception NamingException If a problem was encountered while
136 * adding the listener.
137 * @see EventContext#removeNamingListener
138 * @see javax.naming.directory.DirContext#search(javax.naming.Name, java.lang.String, java.lang.Object[], javax.naming.directory.SearchControls)
139 */
140 void addNamingListener(Name target, String filter,
141 Object[] filterArgs, SearchControls ctls, NamingListener l)
142 throws NamingException;
143
144 /**
145 * Adds a listener for receiving naming events fired when
146 * objects identified by the search filter <tt>filter</tt>
147 * and filter arguments at the
148 * object named by the string target name are modified.
149 * See the overload that accepts a <tt>Name</tt> for details of
150 * how this method behaves.
151 *
152 * @param target The nonnull string name of the object resolved relative to this context.
153 * @param filter The nonnull string filter (see RFC2254).
154 * @param filterArgs The possibly null array of arguments for the filter.
155 * @param ctls The possibly null search controls. If null, the default
156 * search controls is used.
157 * @param l The nonnull listener.
158 * @exception NamingException If a problem was encountered while
159 * adding the listener.
160 * @see EventContext#removeNamingListener
161 * @see javax.naming.directory.DirContext#search(java.lang.String, java.lang.String, java.lang.Object[], javax.naming.directory.SearchControls) */
162 void addNamingListener(String target, String filter,
163 Object[] filterArgs, SearchControls ctls, NamingListener l)
164 throws NamingException;
165 }
|