1 /*
2 * Copyright (c) 1999, 2010, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
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 }