001 /*
002 * Copyright 1999-2000 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.directory;
027
028 /**
029 * This class encapsulates
030 * factors that determine scope of search and what gets returned
031 * as a result of the search.
032 *<p>
033 * A SearchControls instance is not synchronized against concurrent
034 * multithreaded access. Multiple threads trying to access and modify
035 * a single SearchControls instance should lock the object.
036 *
037 * @author Rosanna Lee
038 * @author Scott Seligman
039 * @version 1.17 07/05/05
040 * @since 1.3
041 */
042
043 public class SearchControls implements java.io.Serializable {
044 /**
045 * Search the named object.
046 *<p>
047 * The NamingEnumeration that results from search()
048 * using OBJECT_SCOPE will contain one or zero element.
049 * The enumeration contains one element if the named object satisfies
050 * the search filter specified in search().
051 * The element will have as its name the empty string because the names
052 * of elements in the NamingEnumeration are relative to the
053 * target context--in this case, the target context is the named object.
054 * It contains zero element if the named object does not satisfy
055 * the search filter specified in search().
056 * <p>
057 * The value of this constant is <tt>0</tt>.
058 */
059 public final static int OBJECT_SCOPE = 0;
060
061 /**
062 * Search one level of the named context.
063 *<p>
064 * The NamingEnumeration that results from search()
065 * using ONELEVEL_SCOPE contains elements with
066 * objects in the named context that satisfy
067 * the search filter specified in search().
068 * The names of elements in the NamingEnumeration are atomic names
069 * relative to the named context.
070 * <p>
071 * The value of this constant is <tt>1</tt>.
072 */
073 public final static int ONELEVEL_SCOPE = 1;
074 /**
075 * Search the entire subtree rooted at the named object.
076 *<p>
077 * If the named object is not a DirContext, search only the object.
078 * If the named object is a DirContext, search the subtree
079 * rooted at the named object, including the named object itself.
080 *<p>
081 * The search will not cross naming system boundaries.
082 *<p>
083 * The NamingEnumeration that results from search()
084 * using SUBTREE_SCOPE contains elements of objects
085 * from the subtree (including the named context)
086 * that satisfy the search filter specified in search().
087 * The names of elements in the NamingEnumeration are either
088 * relative to the named context or is a URL string.
089 * If the named context satisfies the search filter, it is
090 * included in the enumeration with the empty string as
091 * its name.
092 * <p>
093 * The value of this constant is <tt>2</tt>.
094 */
095 public final static int SUBTREE_SCOPE = 2;
096
097 /**
098 * Contains the scope with which to apply the search. One of
099 * <tt>ONELEVEL_SCOPE</tt>, <tt>OBJECT_SCOPE</tt>, or
100 * <tt>SUBTREE_SCOPE</tt>.
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 <tt>SearchResult</tt>.
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 * <tt>SearchResult</tt> for each matching entry of search. <tt>null</tt>
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, long countlim, int timelim,
178 String[] attrs, boolean retobj, boolean deref) {
179 searchScope = scope;
180 timeLimit = timelim; // no limit
181 derefLink = deref;
182 returnObj = retobj;
183 countLimit = countlim; // no limit
184 attributesToReturn = attrs; // return all
185 }
186
187 /**
188 * Retrieves the search scope of these SearchControls.
189 *<p>
190 * One of OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE.
191 *
192 * @return The search scope of this SearchControls.
193 * @see #setSearchScope
194 */
195 public int getSearchScope() {
196 return searchScope;
197 }
198
199 /**
200 * Retrieves the time limit of these SearchControls in milliseconds.
201 *<p>
202 * If the value is 0, this means to wait indefinitely.
203 * @return The time limit of these SearchControls in milliseconds.
204 * @see #setTimeLimit
205 */
206 public int getTimeLimit() {
207 return timeLimit;
208 }
209
210 /**
211 * Determines whether links will be dereferenced during the search.
212 *
213 * @return true if links will be dereferenced; false otherwise.
214 * @see #setDerefLinkFlag
215 */
216 public boolean getDerefLinkFlag() {
217 return derefLink;
218 }
219
220 /**
221 * Determines whether objects will be returned as part of the result.
222 *
223 * @return true if objects will be returned; false otherwise.
224 * @see #setReturningObjFlag
225 */
226 public boolean getReturningObjFlag() {
227 return returnObj;
228 }
229
230 /**
231 * Retrieves the maximum number of entries that will be returned
232 * as a result of the search.
233 *<p>
234 * 0 indicates that all entries will be returned.
235 * @return The maximum number of entries that will be returned.
236 * @see #setCountLimit
237 */
238 public long getCountLimit() {
239 return countLimit;
240 }
241
242 /**
243 * Retrieves the attributes that will be returned as part of the search.
244 *<p>
245 * A value of null indicates that all attributes will be returned.
246 * An empty array indicates that no attributes are to be returned.
247 *
248 * @return An array of attribute ids identifying the attributes that
249 * will be returned. Can be null.
250 * @see #setReturningAttributes
251 */
252 public String[] getReturningAttributes() {
253 return attributesToReturn;
254 }
255
256 /**
257 * Sets the search scope to one of:
258 * OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE.
259 * @param scope The search scope of this SearchControls.
260 * @see #getSearchScope
261 */
262 public void setSearchScope(int scope) {
263 searchScope = scope;
264 }
265
266 /**
267 * Sets the time limit of these SearchControls in milliseconds.
268 *<p>
269 * If the value is 0, this means to wait indefinitely.
270 * @param ms The time limit of these SearchControls in milliseconds.
271 * @see #getTimeLimit
272 */
273 public void setTimeLimit(int ms) {
274 timeLimit = ms;
275 }
276
277 /**
278 * Enables/disables link dereferencing during the search.
279 *
280 * @param on if true links will be dereferenced; if false, not followed.
281 * @see #getDerefLinkFlag
282 */
283 public void setDerefLinkFlag(boolean on) {
284 derefLink = on;
285 }
286
287 /**
288 * Enables/disables returning objects returned as part of the result.
289 *<p>
290 * If disabled, only the name and class of the object is returned.
291 * If enabled, the object will be returned.
292 *
293 * @param on if true, objects will be returned; if false,
294 * objects will not be returned.
295 * @see #getReturningObjFlag
296 */
297 public void setReturningObjFlag(boolean on) {
298 returnObj = on;
299 }
300
301 /**
302 * Sets the maximum number of entries to be returned
303 * as a result of the search.
304 *<p>
305 * 0 indicates no limit: all entries will be returned.
306 *
307 * @param limit The maximum number of entries that will be returned.
308 * @see #getCountLimit
309 */
310 public void setCountLimit(long limit) {
311 countLimit = limit;
312 }
313
314 /**
315 * Specifies the attributes that will be returned as part of the search.
316 *<p>
317 * null indicates that all attributes will be returned.
318 * An empty array indicates no attributes are returned.
319 *
320 * @param attrs An array of attribute ids identifying the attributes that
321 * will be returned. Can be null.
322 * @see #getReturningAttributes
323 */
324 public void setReturningAttributes(String[] attrs) {
325 attributesToReturn = attrs;
326 }
327
328 /**
329 * Use serialVersionUID from JNDI 1.1.1 for interoperability.
330 */
331 private static final long serialVersionUID = -2480540967773454797L;
332 }
|