1 /*
2 * Copyright (c) 1999, 2000, 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
27 package javax.naming.directory;
28
29 /**
30 * This class encapsulates
31 * factors that determine scope of search and what gets returned
32 * as a result of the search.
33 *<p>
34 * A SearchControls instance is not synchronized against concurrent
35 * multithreaded access. Multiple threads trying to access and modify
36 * a single SearchControls instance should lock the object.
37 *
38 * @author Rosanna Lee
39 * @author Scott Seligman
40 * @since 1.3
41 */
42
43 public class SearchControls implements java.io.Serializable {
44 /**
45 * Search the named object.
46 *<p>
47 * The NamingEnumeration that results from search()
48 * using OBJECT_SCOPE will contain one or zero element.
49 * The enumeration contains one element if the named object satisfies
50 * the search filter specified in search().
51 * The element will have as its name the empty string because the names
52 * of elements in the NamingEnumeration are relative to the
53 * target context--in this case, the target context is the named object.
54 * It contains zero element if the named object does not satisfy
55 * the search filter specified in search().
56 * <p>
57 * The value of this constant is {@code 0}.
58 */
59 public final static int OBJECT_SCOPE = 0;
60
61 /**
62 * Search one level of the named context.
63 *<p>
64 * The NamingEnumeration that results from search()
65 * using ONELEVEL_SCOPE contains elements with
66 * objects in the named context that satisfy
67 * the search filter specified in search().
68 * The names of elements in the NamingEnumeration are atomic names
69 * relative to the named context.
70 * <p>
71 * The value of this constant is {@code 1}.
72 */
73 public final static int ONELEVEL_SCOPE = 1;
74 /**
75 * Search the entire subtree rooted at the named object.
76 *<p>
77 * If the named object is not a DirContext, search only the object.
78 * If the named object is a DirContext, search the subtree
79 * rooted at the named object, including the named object itself.
80 *<p>
81 * The search will not cross naming system boundaries.
82 *<p>
83 * The NamingEnumeration that results from search()
84 * using SUBTREE_SCOPE contains elements of objects
85 * from the subtree (including the named context)
86 * that satisfy the search filter specified in search().
87 * The names of elements in the NamingEnumeration are either
88 * relative to the named context or is a URL string.
89 * If the named context satisfies the search filter, it is
90 * included in the enumeration with the empty string as
91 * its name.
92 * <p>
93 * The value of this constant is {@code 2}.
94 */
95 public final static int SUBTREE_SCOPE = 2;
96
97 /**
98 * Contains the scope with which to apply the search. One of
99 * {@code ONELEVEL_SCOPE}, {@code OBJECT_SCOPE}, or
100 * {@code SUBTREE_SCOPE}.
101 * @serial
102 */
103 private int searchScope;
104
105 /**
106 * Contains the milliseconds to wait before returning
107 * from search.
108 * @serial
109 */
110 private int timeLimit;
111
112 /**
113 * Indicates whether JNDI links are dereferenced during
114 * search.
115 * @serial
116 */
117 private boolean derefLink;
118
119 /**
120 * Indicates whether object is returned in {@code SearchResult}.
121 * @serial
122 */
123 private boolean returnObj;
124
125 /**
126 * Contains the maximum number of SearchResults to return.
127 * @serial
128 */
129 private long countLimit;
130
131 /**
132 * Contains the list of attributes to be returned in
133 * {@code SearchResult} for each matching entry of search. {@code null}
134 * indicates that all attributes are to be returned.
135 * @serial
136 */
137 private String[] attributesToReturn;
138
139 /**
140 * Constructs a search constraints using defaults.
141 *<p>
142 * The defaults are:
143 * <ul>
144 * <li>search one level
145 * <li>no maximum return limit for search results
146 * <li>no time limit for search
147 * <li>return all attributes associated with objects that satisfy
148 * the search filter.
149 * <li>do not return named object (return only name and class)
150 * <li>do not dereference links during search
151 *</ul>
152 */
153 public SearchControls() {
154 searchScope = ONELEVEL_SCOPE;
155 timeLimit = 0; // no limit
156 countLimit = 0; // no limit
157 derefLink = false;
158 returnObj = false;
159 attributesToReturn = null; // return all
160 }
161
162 /**
163 * Constructs a search constraints using arguments.
164 * @param scope The search scope. One of:
165 * OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE.
166 * @param timelim The number of milliseconds to wait before returning.
167 * If 0, wait indefinitely.
168 * @param deref If true, dereference links during search.
169 * @param countlim The maximum number of entries to return. If 0, return
170 * all entries that satisfy filter.
171 * @param retobj If true, return the object bound to the name of the
172 * entry; if false, do not return object.
173 * @param attrs The identifiers of the attributes to return along with
174 * the entry. If null, return all attributes. If empty
175 * return no attributes.
176 */
177 public SearchControls(int scope,
178 long countlim,
179 int timelim,
180 String[] attrs,
181 boolean retobj,
182 boolean deref) {
183 searchScope = scope;
184 timeLimit = timelim; // no limit
185 derefLink = deref;
186 returnObj = retobj;
187 countLimit = countlim; // no limit
188 attributesToReturn = attrs; // return all
189 }
190
191 /**
192 * Retrieves the search scope of these SearchControls.
193 *<p>
194 * One of OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE.
195 *
196 * @return The search scope of this SearchControls.
197 * @see #setSearchScope
198 */
199 public int getSearchScope() {
200 return searchScope;
201 }
202
203 /**
204 * Retrieves the time limit of these SearchControls in milliseconds.
205 *<p>
206 * If the value is 0, this means to wait indefinitely.
207 * @return The time limit of these SearchControls in milliseconds.
208 * @see #setTimeLimit
209 */
210 public int getTimeLimit() {
211 return timeLimit;
212 }
213
214 /**
215 * Determines whether links will be dereferenced during the search.
216 *
217 * @return true if links will be dereferenced; false otherwise.
218 * @see #setDerefLinkFlag
219 */
220 public boolean getDerefLinkFlag() {
221 return derefLink;
222 }
223
224 /**
225 * Determines whether objects will be returned as part of the result.
226 *
227 * @return true if objects will be returned; false otherwise.
228 * @see #setReturningObjFlag
229 */
230 public boolean getReturningObjFlag() {
231 return returnObj;
232 }
233
234 /**
235 * Retrieves the maximum number of entries that will be returned
236 * as a result of the search.
237 *<p>
238 * 0 indicates that all entries will be returned.
239 * @return The maximum number of entries that will be returned.
240 * @see #setCountLimit
241 */
242 public long getCountLimit() {
243 return countLimit;
244 }
245
246 /**
247 * Retrieves the attributes that will be returned as part of the search.
248 *<p>
249 * A value of null indicates that all attributes will be returned.
250 * An empty array indicates that no attributes are to be returned.
251 *
252 * @return An array of attribute ids identifying the attributes that
253 * will be returned. Can be null.
254 * @see #setReturningAttributes
255 */
256 public String[] getReturningAttributes() {
257 return attributesToReturn;
258 }
259
260 /**
261 * Sets the search scope to one of:
262 * OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE.
263 * @param scope The search scope of this SearchControls.
264 * @see #getSearchScope
265 */
266 public void setSearchScope(int scope) {
267 searchScope = scope;
268 }
269
270 /**
271 * Sets the time limit of these SearchControls in milliseconds.
272 *<p>
273 * If the value is 0, this means to wait indefinitely.
274 * @param ms The time limit of these SearchControls in milliseconds.
275 * @see #getTimeLimit
276 */
277 public void setTimeLimit(int ms) {
278 timeLimit = ms;
279 }
280
281 /**
282 * Enables/disables link dereferencing during the search.
283 *
284 * @param on if true links will be dereferenced; if false, not followed.
285 * @see #getDerefLinkFlag
286 */
287 public void setDerefLinkFlag(boolean on) {
288 derefLink = on;
289 }
290
291 /**
292 * Enables/disables returning objects returned as part of the result.
293 *<p>
294 * If disabled, only the name and class of the object is returned.
295 * If enabled, the object will be returned.
296 *
297 * @param on if true, objects will be returned; if false,
298 * objects will not be returned.
299 * @see #getReturningObjFlag
300 */
301 public void setReturningObjFlag(boolean on) {
302 returnObj = on;
303 }
304
305 /**
306 * Sets the maximum number of entries to be returned
307 * as a result of the search.
308 *<p>
309 * 0 indicates no limit: all entries will be returned.
310 *
311 * @param limit The maximum number of entries that will be returned.
312 * @see #getCountLimit
313 */
314 public void setCountLimit(long limit) {
315 countLimit = limit;
316 }
317
318 /**
319 * Specifies the attributes that will be returned as part of the search.
320 *<p>
321 * null indicates that all attributes will be returned.
322 * An empty array indicates no attributes are returned.
323 *
324 * @param attrs An array of attribute ids identifying the attributes that
325 * will be returned. Can be null.
326 * @see #getReturningAttributes
327 */
328 public void setReturningAttributes(String[] attrs) {
329 attributesToReturn = attrs;
330 }
331
332 /**
333 * Use serialVersionUID from JNDI 1.1.1 for interoperability.
334 */
335 private static final long serialVersionUID = -2480540967773454797L;
336 }