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
27package 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
43public 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}
337