View Javadoc
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 <tt>0</tt>.
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 <tt>1</tt>.
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 <tt>2</tt>.
94       */
95      public final static int SUBTREE_SCOPE = 2;
96  
97      /**
98       * Contains the scope with which to apply the search. One of
99       * <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,
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 }